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