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