1.\" $OpenBSD: write.2,v 1.39 2015/02/05 02:33:09 schwarze 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: February 5 2015 $ 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.In 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.In sys/uio.h 50.Ft ssize_t 51.Fn writev "int d" "const struct iovec *iov" "int iovcnt" 52.In sys/types.h 53.In 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.Vt 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.Vt 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 110.Dv O_APPEND 111flag (see 112.Xr open 2 ) , 113calls to 114.Fn write 115or 116.Fn writev 117will automatically set the pointer to the end of the file before writing. 118.Pp 119Objects that are not capable of seeking always write from the current 120position. 121The value of the pointer associated with such an object is undefined. 122.Pp 123If the real user is not the superuser, then 124.Fn write 125clears the set-user-ID bit on a file. 126This prevents penetration of system security by a user who 127.Dq captures 128a writable set-user-ID file owned by the superuser. 129.Pp 130If 131.Fn write 132succeeds it will update the st_ctime and st_mtime fields of the file's 133meta-data (see 134.Xr stat 2 ) . 135.Pp 136When using non-blocking I/O on objects such as sockets that are subject 137to flow control, 138.Fn write 139and 140.Fn writev 141may write fewer bytes than requested; the return value must be noted, 142and the remainder of the operation should be retried when possible. 143.Pp 144Note that 145.Fn writev 146and 147.Fn pwritev 148will fail if the value of 149.Fa iovcnt 150exceeds the constant 151.Dv IOV_MAX . 152.Sh RETURN VALUES 153Upon successful completion the number of bytes which were written 154is returned. 155Otherwise, a \-1 is returned and the global variable 156.Va errno 157is set to indicate the error. 158.Sh ERRORS 159.Fn write , 160.Fn pwrite , 161.Fn writev , 162and 163.Fn pwritev 164will fail and the file pointer will remain unchanged if: 165.Bl -tag -width Er 166.It Bq Er EBADF 167.Fa d 168is not a valid descriptor open for writing. 169.It Bq Er EFBIG 170An attempt was made to write a file that exceeds the process's 171file size limit or the maximum file size. 172.It Bq Er ENOSPC 173There is no free space remaining on the file system containing the file. 174.It Bq Er EDQUOT 175The user's quota of disk blocks on the file system containing the file 176has been exhausted. 177.It Bq Er EINTR 178A write to a slow device 179(i.e. one that might block for an arbitrary amount of time) 180was interrupted by the delivery of a signal 181before any data could be written. 182.It Bq Er EIO 183An I/O error occurred while reading from or writing to the file system. 184.It Bq Er EFAULT 185Part of 186.Fa buf 187points outside the process's allocated address space. 188.El 189.Pp 190In addition, 191.Fn write 192and 193.Fn writev 194may return the following errors: 195.Bl -tag -width Er 196.It Bq Er EPIPE 197An attempt is made to write to a pipe that is not open 198for reading by any process. 199.It Bq Er EPIPE 200An attempt is made to write to a socket of type 201.Dv SOCK_STREAM 202that is not connected to a peer socket. 203.It Bq Er EAGAIN 204The file was marked for non-blocking I/O, and no data could be 205written immediately. 206.It Bq Er ENETDOWN 207The destination address specified a network that is down. 208.It Bq Er EDESTADDRREQ 209The destination is no longer available when writing to a 210.Ux Ns -domain 211datagram socket on which 212.Xr connect 2 213had been used to set a destination address. 214.It Bq Er EIO 215The process is a member of a background process attempting to write 216to its controlling terminal, 217.Dv TOSTOP 218is set on the terminal, 219the process isn't ignoring the 220.Dv SIGTTOUT 221signal and the thread isn't blocking the 222.Dv SIGTTOUT 223signal, 224and either the process was created with 225.Xr vfork 2 226and hasn't successfully executed one of the exec functions or 227the process group is orphaned. 228.El 229.Pp 230.Fn write 231and 232.Fn pwrite 233may return the following error: 234.Bl -tag -width Er 235.It Bq Er EINVAL 236.Fa nbytes 237was larger than 238.Dv SSIZE_MAX . 239.El 240.Pp 241.Fn pwrite 242and 243.Fn pwritev 244may return the following error: 245.Bl -tag -width Er 246.It Bq Er EINVAL 247.Fa offset 248was negative. 249.It Bq Er ESPIPE 250.Fa d 251is associated with a pipe, socket, FIFO, or tty. 252.El 253.Pp 254.Fn writev 255and 256.Fn pwritev 257may return one of the following errors: 258.Bl -tag -width Er 259.It Bq Er EINVAL 260.Fa iovcnt 261was less than or equal to 0, or greater than 262.Dv IOV_MAX . 263.It Bq Er EINVAL 264The sum of the 265.Fa iov_len 266values in the 267.Fa iov 268array overflowed an 269.Vt ssize_t . 270.It Bq Er EFAULT 271Part of 272.Fa iov 273points outside the process's allocated address space. 274.It Bq Er ENOBUFS 275The system lacked sufficient buffer space or a queue was full. 276.El 277.Sh SEE ALSO 278.Xr fcntl 2 , 279.Xr lseek 2 , 280.Xr open 2 , 281.Xr pipe 2 , 282.Xr poll 2 , 283.Xr select 2 , 284.Xr termios 4 285.Sh STANDARDS 286The 287.Fn write , 288.Fn writev , 289and 290.Fn pwrite 291functions conform to 292.St -p1003.1-2008 . 293.Sh HISTORY 294The 295.Fn pwritev 296function call appeared in 297.Ox 2.7 . 298The 299.Fn pwrite 300function call appeared in 301.At V.4 . 302The 303.Fn writev 304function call appeared in 305.Bx 4.2 . 306The 307.Fn write 308function call appeared in 309.At v2 . 310.Sh CAVEATS 311Error checks should explicitly test for \-1. 312Code such as 313.Bd -literal -offset indent 314while ((nr = write(fd, buf, sizeof(buf))) > 0) 315.Ed 316.Pp 317is not maximally portable, as some platforms allow for 318.Fa nbytes 319to range between 320.Dv SSIZE_MAX 321and 322.Dv SIZE_MAX 323\- 2, in which case the return value of an error-free 324.Fn write 325may appear as a negative number distinct from \-1. 326Proper loops should use 327.Bd -literal -offset indent 328while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) 329.Ed 330