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