WRITE(2)WRITE(2)NAME
write - write output
BSD SYNOPSIS
int write(int fd, char *buf, int nbytes);
#include <sys/types.h>
#include <sys/uio.h>
int writev(int fd, struct iovec *iov, int iovcnt);
POSIX SYNOPSIS
size_t write(int fd, const void *buf, size_t nbytes);
DESCRIPTION
The write function attempts to write nbytes of data to the object
referenced by the descriptor fd from the buffer pointed to by buf.
With objects capable of seeking, write starts at a position given by
the seek pointer associated with fd (see lseek(2)). Upon return, the
seek pointer for fd is incremented by the number of bytes actually
written.
Objects that are not capable of seeking always write from the current
position. The value of the pointer associated with such an object is
undefined.
If the real user is not the super-user, then write clears the set-user-
id bit on a file. This prevents penetration of system security by a
user who “captures” a writable set-user-id file owned by the super-
user.
When using non-blocking I/O on objects such as sockets that are subject
to flow control, write may write fewer bytes than requested; the return
value must be noted, and the remainder of the operation should be
retried when possible.
The writev function performs a scattered write, writing output data
from the iovcnt buffers specified by the members of the iov array:
iov[0], iov[1], iov[ iovcnt - 1]. The return value of writev is the
same as that for write.
The iovec structure is defined as
struct iovec {
caddr_t iov_base;
int iov_len;
};
Each iovec entry specifies the base address and length of an area in
memory where data should be written from. Writev will always write all
data from an area before proceeding to the next. POSIX applications
should not use writev.
POSIX applications may expect the following additional behavior when
attempting to write (but not writev) to a pipe or FIFO:
(1) There is no file offset associated with a pipe, hence each write
request will append to the end of the pipe.
(2) Write requests of {PIPE_BUF} bytes or less are not interleaved
with data from any other processes doing writes on the same pipe.
Writes of greater than {PIPE_BUF} bytes may have data interleaved,
on arbitrary boundaries, with writes by other processes, whether
or not the O_NONBLOCK flag of the file status flags is set.
(3) If the O_NONBLOCK flag is clear, a write request may cause the
process to block, but on normal completion if will return nbyte.
(4) If the O_NONBLOCK flag is set, write requests will be handled
differently, in the following ways:
(a) The write function will not block the process.
(b) A write request for {PIPE_BUF} or fewer bytes will:
[1] If there is sufficient space available in the pipe,
transfer all the data and return the number of bytes
requested.
[2] If there is not sufficient space available in the pipe,
transfer no data and return -1 with errno set to EAGAIN.
(c) A write request for more than {PIPE_BUF} bytes will either:
[1] When at least one byte can be written, transfer what it
can and return the number of bytes written. When all
data previously written to the pipe has been read, it
will transfer at least {PIPE_BUF} bytes.
[2] When no data can be written, transfer no data and return
-1 with errno set to EAGAIN.
POSIX applications may also expect the following when attempting to
write to a file descriptor (other than a pipe or FIFO) that supports
nonblocking writes and cannot accept the data immediately:
(1) If the O_NONBLOCK flag is clear, write will not block the process.
If some data can be written without blocking the process, write
will write what it can and return the number of bytes written.
Otherwise, it will return -1 and errno will be set to EAGAIN.
(2) If the O_NONBLOCK flag is set, write will block until the data can
be accepted.
RETURN VALUE
Upon successful completion the number of bytes actually written is
returned. Otherwise a -1 is returned and the global variable errno is
set to indicate the error.
ERRORS
Write will fail and the file pointer will remain unchanged if one or
more of the following are true:
[EAGAIN] The O_NONBLOCK flag is set for the file descriptor and
the process would be delayed in the write operation.
[EBADF] fd is not a valid descriptor open for writing.
[EPIPE] An attempt is made to write to a pipe that is not open
for reading by any process; or, an attempt is made to
write to a socket of type SOCK_STREAM that is not
connected to a peer socket.
[EFBIG] An attempt was made to write a file that exceeds the
process's file size limit or the maximum file size.
[EFAULT] Part of the data to be written to the file lies outside
the process's allocated address space.
[EINVAL] The pointer associated with fd was negative.
[ENOSPC] There is no free space remaining on the file system
containing the file.
[EINTR] The write operation was interrupted by a signal, and no
data was transferred.
[EDQUOT] The user's quota of disk blocks on the file system
containing the file has been exhausted.
[EIO] An I/O error occurred while reading from or writing to
the file system; or, the process is in the background
process group and is attempting to write to its
controlling terminal, TOSTOP is set, the process is
neither ignoring nor blocking SIGTTOU signals, and the
process group of the process is orphaned.
[EWOULDBLOCK] The file was marked for non-blocking I/O, and no data
could be written immediately.
In addition, writev may return one of the following errors:
[EINVAL] Iovcnt was less than or equal to 0, or greater than 16;
or, one of the iov_len values in the iov array was
negative; or, the sum of the iov_len values in the iov
array overflowed a 32-bit integer.
SEE ALSOcreat(2), dup(2), fcntl(2), lseek(2), open(2), pipe(2)
August 1, 1992 WRITE(2)