1.\" $OpenBSD: write.2,v 1.38 2013/04/08 07:39:17 jmc Exp $ 2.\" $NetBSD: write.2,v 1.6 1995/02/27 12:39:43 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)write.2 8.5 (Berkeley) 4/2/94 32.\" 33.Dd $Mdocdate: April 8 2013 $ 34.Dt WRITE 2 35.Os 36.Sh NAME 37.Nm write , 38.Nm writev , 39.Nm pwrite , 40.Nm pwritev 41.Nd write output 42.Sh SYNOPSIS 43.Fd #include <unistd.h> 44.Ft ssize_t 45.Fn write "int d" "const void *buf" "size_t nbytes" 46.Ft ssize_t 47.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" 48.Pp 49.Fd #include <sys/uio.h> 50.Ft ssize_t 51.Fn writev "int d" "const struct iovec *iov" "int iovcnt" 52.Fd #include <sys/types.h> 53.Fd #include <sys/uio.h> 54.Ft ssize_t 55.Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" 56.Sh DESCRIPTION 57.Fn write 58attempts to write 59.Fa nbytes 60of data to the object referenced by the descriptor 61.Fa d 62from the buffer pointed to by 63.Fa buf . 64.Fn writev 65performs the same action, but gathers the output data from the 66.Fa iovcnt 67buffers specified by the members of the 68.Fa iov 69array: iov[0], iov[1], ..., iov[iovcnt-1]. 70.Fn pwrite 71and 72.Fn pwritev 73perform the same functions, but write to the specified position 74.Fa offset 75in the file without modifying the file pointer. 76.Pp 77For 78.Fn writev 79and 80.Fn pwritev , 81the 82.Fa iovec 83structure is defined as: 84.Bd -literal -offset indent 85struct iovec { 86 void *iov_base; 87 size_t iov_len; 88}; 89.Ed 90.Pp 91Each 92.Fa iovec 93entry specifies the base address and length of an area 94in memory from which data should be written. 95.Fn writev 96and 97.Fn pwritev 98will always write a complete area before proceeding to the next. 99.Pp 100On objects capable of seeking, the 101.Fn write 102starts at a position given by the pointer associated with 103.Fa d 104(see 105.Xr lseek 2 ) . 106Upon return from 107.Fn write , 108the pointer is incremented by the number of bytes which were written. 109If a file was opened with the O_APPEND flag (see 110.Xr open 2 ) , 111calls to 112.Fn write 113or 114.Fn writev 115will automatically set the pointer to the end of the file before writing. 116.Pp 117Objects that are not capable of seeking always write from the current 118position. 119The value of the pointer associated with such an object is undefined. 120.Pp 121If the real user is not the superuser, then 122.Fn write 123clears the set-user-ID bit on a file. 124This prevents penetration of system security by a user who 125.Dq captures 126a writable set-user-ID file owned by the superuser. 127.Pp 128If 129.Fn write 130succeeds it will update the st_ctime and st_mtime fields of the file's 131meta-data (see 132.Xr stat 2 ) . 133.Pp 134When using non-blocking I/O on objects such as sockets that are subject 135to flow control, 136.Fn write 137and 138.Fn writev 139may write fewer bytes than requested; the return value must be noted, 140and the remainder of the operation should be retried when possible. 141.Pp 142Note that 143.Fn writev 144and 145.Fn pwritev 146will fail if the value of 147.Fa iovcnt 148exceeds the constant 149.Dv IOV_MAX . 150.Sh RETURN VALUES 151Upon successful completion the number of bytes which were written 152is returned. 153Otherwise, a \-1 is returned and the global variable 154.Va errno 155is set to indicate the error. 156.Sh ERRORS 157.Fn write , 158.Fn pwrite , 159.Fn writev , 160and 161.Fn pwritev 162will fail and the file pointer will remain unchanged if: 163.Bl -tag -width Er 164.It Bq Er EBADF 165.Fa d 166is not a valid descriptor open for writing. 167.It Bq Er EFBIG 168An attempt was made to write a file that exceeds the process's 169file size limit or the maximum file size. 170.It Bq Er ENOSPC 171There is no free space remaining on the file system containing the file. 172.It Bq Er EDQUOT 173The user's quota of disk blocks on the file system containing the file 174has been exhausted. 175.It Bq Er EINTR 176A write to a slow device 177(i.e. one that might block for an arbitrary amount of time) 178was interrupted by the delivery of a signal 179before any data could be written. 180.It Bq Er EIO 181An I/O error occurred while reading from or writing to the file system. 182.It Bq Er EFAULT 183Part of 184.Fa buf 185points outside the process's allocated address space. 186.El 187.Pp 188In addition, 189.Fn write 190and 191.Fn writev 192may return the following errors: 193.Bl -tag -width Er 194.It Bq Er EPIPE 195An attempt is made to write to a pipe that is not open 196for reading by any process. 197.It Bq Er EPIPE 198An attempt is made to write to a socket of type 199.Dv SOCK_STREAM 200that is not connected to a peer socket. 201.It Bq Er EAGAIN 202The file was marked for non-blocking I/O, and no data could be 203written immediately. 204.It Bq Er ENETDOWN 205The destination address specified a network that is down. 206.It Bq Er EDESTADDRREQ 207The destination is no longer available when writing to a 208.Ux Ns -domain 209datagram socket on which 210.Xr connect 2 211had been used to set a destination address. 212.It Bq Er EIO 213The process is a member of a background process attempting to write 214to its controlling terminal, 215.Dv TOSTOP 216is set on the terminal, 217the process isn't ignoring the 218.Dv SIGTTOUT 219signal and the thread isn't blocking the 220.Dv SIGTTOUT 221signal, 222and either the process was created with 223.Xr vfork 2 224and hasn't successfully executed one of the exec functions or 225the process group is orphaned. 226.El 227.Pp 228.Fn write 229and 230.Fn pwrite 231may return the following error: 232.Bl -tag -width Er 233.It Bq Er EINVAL 234.Fa nbytes 235was larger than 236.Dv SSIZE_MAX . 237.El 238.Pp 239.Fn pwrite 240and 241.Fn pwritev 242may return the following error: 243.Bl -tag -width Er 244.It Bq Er EINVAL 245.Fa offset 246was negative. 247.It Bq Er ESPIPE 248.Fa d 249is associated with a pipe, socket, FIFO, or tty. 250.El 251.Pp 252.Fn writev 253and 254.Fn pwritev 255may return one of the following errors: 256.Bl -tag -width Er 257.It Bq Er EINVAL 258.Fa iovcnt 259was less than or equal to 0, or greater than 260.Dv IOV_MAX . 261.It Bq Er EINVAL 262The sum of the 263.Fa iov_len 264values in the 265.Fa iov 266array overflowed an 267.Em ssize_t . 268.It Bq Er EFAULT 269Part of 270.Fa iov 271points outside the process's allocated address space. 272.It Bq Er ENOBUFS 273The system lacked sufficient buffer space or a queue was full. 274.El 275.Sh SEE ALSO 276.Xr fcntl 2 , 277.Xr lseek 2 , 278.Xr open 2 , 279.Xr pipe 2 , 280.Xr poll 2 , 281.Xr select 2 , 282.Xr termios 4 283.Sh STANDARDS 284The 285.Fn write , 286.Fn writev , 287and 288.Fn pwrite 289functions conform to 290.St -p1003.1-2008 . 291.Sh HISTORY 292The 293.Fn pwritev 294function call appeared in 295.Ox 2.7 . 296The 297.Fn pwrite 298function call appeared in 299.At V.4 . 300The 301.Fn writev 302function call appeared in 303.Bx 4.2 . 304The 305.Fn write 306function call appeared in 307.At v2 . 308.Sh CAVEATS 309Error checks should explicitly test for \-1. 310Code such as 311.Bd -literal -offset indent 312while ((nr = write(fd, buf, sizeof(buf))) > 0) 313.Ed 314.Pp 315is not maximally portable, as some platforms allow for 316.Va nbytes 317to range between 318.Dv SSIZE_MAX 319and 320.Dv SIZE_MAX 321\- 2, in which case the return value of an error-free 322.Fn write 323may appear as a negative number distinct from \-1. 324Proper loops should use 325.Bd -literal -offset indent 326while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) 327.Ed 328