1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)write.2 8.5 (Berkeley) 04/02/94 7.\" 8.Dd 9.Dt WRITE 2 10.Os BSD 4 11.Sh NAME 12.Nm write , 13.Nm writev 14.Nd write output 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/uio.h> 18.Fd #include <unistd.h> 19.Ft ssize_t 20.Fn write "int d" "const void *buf" "size_t nbytes" 21.Ft ssize_t 22.Fn writev "int d" "const struct iovec *iov" "int iovcnt" 23.Sh DESCRIPTION 24.Fn Write 25attempts to write 26.Fa nbytes 27of data to the object referenced by the descriptor 28.Fa d 29from the buffer pointed to by 30.Fa buf . 31.Fn Writev 32performs the same action, but gathers the output data 33from the 34.Fa iovcnt 35buffers specified by the members of the 36.Fa iov 37array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. 38.Pp 39For 40.Fn writev , 41the 42.Fa iovec 43structure is defined as: 44.Pp 45.Bd -literal -offset indent -compact 46struct iovec { 47 void *iov_base; 48 size_t iov_len; 49}; 50.Ed 51.Pp 52Each 53.Fa iovec 54entry specifies the base address and length of an area 55in memory from which data should be written. 56.Fn Writev 57will always write a complete area before proceeding 58to the next. 59.Pp 60On objects capable of seeking, the 61.Fn write 62starts at a position 63given by the pointer associated with 64.Fa d , 65see 66.Xr lseek 2 . 67Upon return from 68.Fn write , 69the pointer is incremented by the number of bytes which were written. 70.Pp 71Objects that are not capable of seeking always write from the current 72position. The value of the pointer associated with such an object 73is undefined. 74.Pp 75If the real user is not the super-user, then 76.Fn write 77clears the set-user-id bit on a file. 78This prevents penetration of system security 79by a user who 80.Dq captures 81a writable set-user-id file 82owned by the super-user. 83.Pp 84When using non-blocking I/O on objects such as sockets that are subject 85to flow control, 86.Fn write 87and 88.Fn writev 89may write fewer bytes than requested; 90the return value must be noted, 91and the remainder of the operation should be retried when possible. 92.Sh RETURN VALUES 93Upon successful completion the number of bytes which were written 94is returned. Otherwise a -1 is returned and the global variable 95.Va errno 96is set to indicate the error. 97.Sh ERRORS 98.Fn Write 99and 100.Fn writev 101will fail and the file pointer will remain unchanged if: 102.Bl -tag -width Er 103.It Bq Er EBADF 104.Fa D 105is not a valid descriptor open for writing. 106.It Bq Er EPIPE 107An attempt is made to write to a pipe that is not open 108for reading by any process. 109.It Bq Er EPIPE 110An attempt is made to write to a socket of type 111.DV SOCK_STREAM 112that is not connected to a peer socket. 113.It Bq Er EFBIG 114An attempt was made to write a file that exceeds the process's 115file size limit or the maximum file size. 116.It Bq Er EFAULT 117Part of 118.Fa iov 119or data to be written to the file 120points outside the process's allocated address space. 121.It Bq Er EINVAL 122The pointer associated with 123.Fa d 124was negative. 125.It Bq Er ENOSPC 126There is no free space remaining on the file system 127containing the file. 128.It Bq Er EDQUOT 129The user's quota of disk blocks on the file system 130containing the file has been exhausted. 131.It Bq Er EIO 132An I/O error occurred while reading from or writing to the file system. 133.It Bq Er EAGAIN 134The file was marked for non-blocking I/O, 135and no data could be written immediately. 136.El 137.Pp 138In addition, 139.Fn writev 140may return one of the following errors: 141.Bl -tag -width Er 142.It Bq Er EINVAL 143.Fa Iovcnt 144was less than or equal to 0, or greater than 145.Dv UIO_MAXIOV . 146.It Bq Er EINVAL 147One of the 148.Fa iov_len 149values in the 150.Fa iov 151array was negative. 152.It Bq Er EINVAL 153The sum of the 154.Fa iov_len 155values in the 156.Fa iov 157array overflowed a 32-bit integer. 158.El 159.Sh SEE ALSO 160.Xr fcntl 2 , 161.Xr lseek 2 , 162.Xr open 2 , 163.Xr pipe 2 , 164.Xr select 2 165.Sh STANDARDS 166.Fn Write 167is expected to conform to IEEE Std 1003.1-1988 168.Pq Dq Tn POSIX . 169.Sh HISTORY 170The 171.Fn writev 172function call 173appeared in 174.Bx 4.2 . 175A 176.Nm write 177function call 178appeared in 179Version 6 AT&T UNIX. 180