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