1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)write.2 8.5 (Berkeley) 4/2/94 29.\" $FreeBSD: src/lib/libc/sys/write.2,v 1.12.2.8 2002/10/13 17:42:14 schweikh Exp $ 30.\" 31.Dd March 2, 2018 32.Dt WRITE 2 33.Os 34.Sh NAME 35.Nm write , 36.Nm writev , 37.Nm pwrite , 38.Nm pwritev , 39.Nm extpwrite , 40.Nm extpwritev 41.Nd write output 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/uio.h 47.In unistd.h 48.Ft ssize_t 49.Fn write "int d" "const void *buf" "size_t nbytes" 50.Ft ssize_t 51.Fn writev "int d" "const struct iovec *iov" "int iovcnt" 52.Ft ssize_t 53.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" 54.Ft ssize_t 55.Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" 56.Ft ssize_t 57.Fn extpwrite "int d" "const void *buf" "size_t nbytes" "int flags" "off_t offset" 58.Ft ssize_t 59.Fn extpwritev "int d" "const struct iovec *iov" "int iovcnt" "int flags" "off_t offset" 60.Sh DESCRIPTION 61.Fn Write 62attempts to write 63.Fa nbytes 64of data to the object referenced by the descriptor 65.Fa d 66from the buffer pointed to by 67.Fa buf . 68.Fn Writev 69and 70.Fn pwritev 71perform the same action, but gather the output data 72from the 73.Fa iovcnt 74buffers specified by the members of the 75.Fa iov 76array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. 77.Fn Pwrite 78and 79.Fn pwritev 80perform the same function, but write to the specified position in 81the file without modifying the file pointer. 82.Pp 83For 84.Fn writev 85and 86.Fn pwritev , 87the 88.Fa iovec 89structure is defined as: 90.Pp 91.Bd -literal -offset indent -compact 92struct iovec { 93 char *iov_base; /* Base address. */ 94 size_t iov_len; /* Length. */ 95}; 96.Ed 97.Pp 98Each 99.Fa iovec 100entry specifies the base address and length of an area 101in memory from which data should be written. 102.Fn Writev 103and 104.Fn pwritev 105will always write a complete area before proceeding 106to the next. 107.Pp 108The 109.Fn extpwrite 110and 111.Fn extpwritev 112allow a 113.Ar flags 114argument 115to also be passed in, controlling blocking/non-blocking and other features 116on a call-by-call basis, ignoring the related default for the descriptor. 117Allowed flags are: 118.Bl -tag -width ".Dv O_FNONBLOCKING" 119.It Dv O_FBLOCKING 120Force the system call to operate in a blocking fashion. 121.It Dv O_FNONBLOCKING 122Force the system call to operate in a non-blocking fashion. 123.It Dv O_FAPPEND 124Force append mode for the operation. 125.It Dv O_FOFFSET 126Force offset mode for the operation. 127.It Dv O_FSYNCWRITE 128Force the system call to issue the write synchronously. 129.It Dv O_FASYNCWRITE 130Force the system call to issue the write asynchronously. 131.El 132.Pp 133On objects capable of seeking, the 134.Fn write 135starts at a position 136given by the pointer associated with 137.Fa d , 138see 139.Xr lseek 2 . 140Upon return from 141.Fn write , 142the pointer is incremented by the number of bytes which were written. 143.Pp 144Objects that are not capable of seeking always write from the current 145position. The value of the pointer associated with such an object 146is undefined. 147.Pp 148If the real user is not the super-user, then 149.Fn write 150clears the set-user-id bit on a file. 151This prevents penetration of system security 152by a user who 153.Dq captures 154a writable set-user-id file 155owned by the super-user. 156.Pp 157When using non-blocking I/O on objects such as sockets that are subject 158to flow control, 159.Fn write 160and 161.Fn writev 162may write fewer bytes than requested; 163the return value must be noted, 164and the remainder of the operation should be retried when possible. 165.Sh RETURN VALUES 166Upon successful completion the number of bytes which were written 167is returned. Otherwise a -1 is returned and the global variable 168.Va errno 169is set to indicate the error. 170.Sh ERRORS 171.Fn Write , 172.Fn writev , 173.Fn pwrite , 174.Fn pwritev , 175.Fn extpwrite 176and 177.Fn extpwritev 178will fail and the file pointer will remain unchanged if: 179.Bl -tag -width Er 180.It Bq Er EBADF 181.Fa D 182is not a valid descriptor open for writing. 183.It Bq Er EPIPE 184An attempt is made to write to a pipe that is not open 185for reading by any process. 186.It Bq Er EPIPE 187An attempt is made to write to a socket of type 188.Dv SOCK_STREAM 189that is not connected to a peer socket. 190.It Bq Er EFBIG 191An attempt was made to write a file that exceeds the process's 192file size limit or the maximum file size. 193.It Bq Er EFAULT 194Part of 195.Fa iov 196or data to be written to the file 197points outside the process's allocated address space. 198.It Bq Er EINVAL 199The pointer associated with 200.Fa d 201was negative. 202.It Bq Er ENOSPC 203There is no free space remaining on the file system 204containing the file. 205.It Bq Er EDQUOT 206The user's quota of disk blocks on the file system 207containing the file has been exhausted. 208.It Bq Er EIO 209An I/O error occurred while reading from or writing to the file system. 210.It Bq Er EINTR 211A signal interrupted the write before it could be completed. 212.It Bq Er EAGAIN 213The file was marked for non-blocking I/O, 214and no data could be written immediately. 215.It Bq Er EROFS 216An attempt was made to write over a disk label area at the beginning 217of a disk. 218Use 219.Xr disklabel 8 220.Fl W 221to enable writing on the disk label area. 222.El 223.Pp 224In addition, 225.Fn writev 226.Fn pwritev , 227and 228.Fn extpwritev 229may return one of the following errors: 230.Bl -tag -width Er 231.It Bq Er EDESTADDRREQ 232The destination is no longer available when writing to a 233.Ux 234domain datagram socket on which 235.Xr connect 2 236had been used to set a destination address. 237.It Bq Er EINVAL 238.Fa Iovcnt 239was less than or equal to 0, or greater than 240.Dv UIO_MAXIOV . 241.It Bq Er EINVAL 242One of the 243.Fa iov_len 244values in the 245.Fa iov 246array was negative. 247.It Bq Er EINVAL 248The sum of the 249.Fa iov_len 250values in the 251.Fa iov 252array overflowed a 32-bit integer. 253.It Bq Er ENOBUFS 254The mbuf pool has been completely exhausted when writing to a socket. 255.El 256.Pp 257The 258.Fn pwrite , 259.Fn pwritev , 260.Fn extpwrite 261and 262.Fn extpwritev 263calls may also return the following errors: 264.Bl -tag -width Er 265.It Bq Er EINVAL 266The specified file offset is invalid. 267.It Bq Er ESPIPE 268The file descriptor is associated with a pipe, socket, or FIFO. 269.El 270.Sh SEE ALSO 271.Xr fcntl 2 , 272.Xr lseek 2 , 273.Xr open 2 , 274.Xr pipe 2 , 275.Xr select 2 276.Sh STANDARDS 277The 278.Fn write 279function call is expected to conform to 280.St -p1003.1-90 . 281The 282.Fn writev 283and 284.Fn pwrite 285functions are expected to conform to 286.St -xpg4.2 . 287.Pp 288The 289.Fn extpwrite 290and 291.Fn extpwritev 292functions are 293.Dx 294specific extensions. 295.Sh HISTORY 296The 297.Fn pwritev 298function call was added in 299.Dx 1.5 . 300The 301.Fn pwrite 302function call 303appeared in 304.At V.4 . 305The 306.Fn writev 307function call 308appeared in 309.Bx 4.2 . 310A 311.Fn write 312function call appeared in 313.At v6 . 314