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