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.\" $DragonFly: src/lib/libc/sys/write.2,v 1.5 2006/04/27 16:01:33 swildner Exp $ 35.\" 36.Dd April 27, 2006 37.Dt WRITE 2 38.Os 39.Sh NAME 40.Nm write , 41.Nm writev , 42.Nm pwrite , 43.Nm pwritev 44.Nd write output 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In sys/types.h 49.In sys/uio.h 50.In unistd.h 51.Ft ssize_t 52.Fn write "int d" "const void *buf" "size_t nbytes" 53.Ft ssize_t 54.Fn writev "int d" "const struct iovec *iov" "int iovcnt" 55.Ft ssize_t 56.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" 57.Ft ssize_t 58.Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" 59.Sh DESCRIPTION 60.Fn Write 61attempts to write 62.Fa nbytes 63of data to the object referenced by the descriptor 64.Fa d 65from the buffer pointed to by 66.Fa buf . 67.Fn Writev 68and 69.Fn pwritev 70perform the same action, but gather the output data 71from the 72.Fa iovcnt 73buffers specified by the members of the 74.Fa iov 75array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. 76.Fn Pwrite 77and 78.Fn pwritev 79perform the same function, but write to the specified position in 80the file without modifying the file pointer. 81.Pp 82For 83.Fn writev 84and 85.Fn pwritev , 86the 87.Fa iovec 88structure is defined as: 89.Pp 90.Bd -literal -offset indent -compact 91struct iovec { 92 char *iov_base; /* Base address. */ 93 size_t iov_len; /* Length. */ 94}; 95.Ed 96.Pp 97Each 98.Fa iovec 99entry specifies the base address and length of an area 100in memory from which data should be written. 101.Fn Writev 102and 103.Fn pwritev 104will always write a complete area before proceeding 105to the next. 106.Pp 107On objects capable of seeking, the 108.Fn write 109starts at a position 110given by the pointer associated with 111.Fa d , 112see 113.Xr lseek 2 . 114Upon return from 115.Fn write , 116the pointer is incremented by the number of bytes which were written. 117.Pp 118Objects that are not capable of seeking always write from the current 119position. The value of the pointer associated with such an object 120is undefined. 121.Pp 122If the real user is not the super-user, then 123.Fn write 124clears the set-user-id bit on a file. 125This prevents penetration of system security 126by a user who 127.Dq captures 128a writable set-user-id file 129owned by the super-user. 130.Pp 131When using non-blocking I/O on objects such as sockets that are subject 132to flow control, 133.Fn write 134and 135.Fn writev 136may write fewer bytes than requested; 137the return value must be noted, 138and the remainder of the operation should be retried when possible. 139.Sh RETURN VALUES 140Upon successful completion the number of bytes which were written 141is returned. Otherwise a -1 is returned and the global variable 142.Va errno 143is set to indicate the error. 144.Sh ERRORS 145.Fn Write , 146.Fn writev , 147.Fn pwrite , 148and 149.Fn pwritev 150will fail and the file pointer will remain unchanged if: 151.Bl -tag -width Er 152.It Bq Er EBADF 153.Fa D 154is not a valid descriptor open for writing. 155.It Bq Er EPIPE 156An attempt is made to write to a pipe that is not open 157for reading by any process. 158.It Bq Er EPIPE 159An attempt is made to write to a socket of type 160.Dv SOCK_STREAM 161that is not connected to a peer socket. 162.It Bq Er EFBIG 163An attempt was made to write a file that exceeds the process's 164file size limit or the maximum file size. 165.It Bq Er EFAULT 166Part of 167.Fa iov 168or data to be written to the file 169points outside the process's allocated address space. 170.It Bq Er EINVAL 171The pointer associated with 172.Fa d 173was negative. 174.It Bq Er ENOSPC 175There is no free space remaining on the file system 176containing the file. 177.It Bq Er EDQUOT 178The user's quota of disk blocks on the file system 179containing the file has been exhausted. 180.It Bq Er EIO 181An I/O error occurred while reading from or writing to the file system. 182.It Bq Er EINTR 183A signal interrupted the write before it could be completed. 184.It Bq Er EAGAIN 185The file was marked for non-blocking I/O, 186and no data could be written immediately. 187.It Bq Er EROFS 188An attempt was made to write over a disk label area at the beginning 189of a disk. 190Use 191.Xr disklabel 8 192.Fl W 193to enable writing on the disk label area. 194.El 195.Pp 196In addition, 197.Fn writev 198and 199.Fn pwritev 200may return one of the following errors: 201.Bl -tag -width Er 202.It Bq Er EDESTADDRREQ 203The destination is no longer available when writing to a 204.Ux 205domain datagram socket on which 206.Xr connect 2 207had been used to set a destination address. 208.It Bq Er EINVAL 209.Fa Iovcnt 210was less than or equal to 0, or greater than 211.Dv UIO_MAXIOV . 212.It Bq Er EINVAL 213One of the 214.Fa iov_len 215values in the 216.Fa iov 217array was negative. 218.It Bq Er EINVAL 219The sum of the 220.Fa iov_len 221values in the 222.Fa iov 223array overflowed a 32-bit integer. 224.It Bq Er ENOBUFS 225The mbuf pool has been completely exhausted when writing to a socket. 226.El 227.Pp 228The 229.Fn pwrite 230and 231.Fn pwritev 232calls may also return the following errors: 233.Bl -tag -width Er 234.It Bq Er EINVAL 235The specified file offset is invalid. 236.It Bq Er ESPIPE 237The file descriptor is associated with a pipe, socket, or FIFO. 238.El 239.Sh SEE ALSO 240.Xr fcntl 2 , 241.Xr lseek 2 , 242.Xr open 2 , 243.Xr pipe 2 , 244.Xr select 2 245.Sh STANDARDS 246The 247.Fn write 248function call is expected to conform to 249.St -p1003.1-90 . 250The 251.Fn writev 252and 253.Fn pwrite 254functions are expected to conform to 255.St -xpg4.2 . 256.Sh HISTORY 257The 258.Fn pwritev 259function call was added in 260.Dx 1.5 . 261The 262.Fn pwrite 263function call 264appeared in 265.At V.4 . 266The 267.Fn writev 268function call 269appeared in 270.Bx 4.2 . 271A 272.Fn write 273function call appeared in 274.At v6 . 275