NAME
write, writev - Writes to a file.
SYNOPSIS
ssize_t write(
int filedes ,
void **buffer,
size_t nbytes );
#include <sys/types.h>
#include <sys/uio.h>
int writev(
int filedes ,
struct iovec *iov,
int iov_count );
PARAMETERS
filedes Identifies the file to which the data is to be
written.
buffer Identifies the buffer containing the data to be
written.
nbytes Specifies the number of bytes to write.
iov Points to an array of iovec structures, which
identifies the buffers containing the data to be
written. The iovec structure is defined in the
sys/uio.h header file and contains the following
members:
caddr_t iov_base;
int iov_len;
iov_count Specifies the number of iovec structures pointed
to by the iov parameter.
DESCRIPTION
The write() function attempts to write nbytes of data to the
file associated with the filedes parameter from the buffer
pointed to by the buffer parameter.
If the nbyte parameter is 0 (zero), the write() function
returns 0 (zero) and has no other results if the file is a
regular file.
The writev() function performs the same action as the
write() function, but gathers the output data from the
iov_count buffers specified by the array of iovec structures
pointed to by the iov parameter. Each iovec entry specifies
the base address and length of an area in memory from which
data should be written. The writev() function always writes
a complete area before proceeding to the next.
The write() and writev() functions, which suspend the cal-
ling process until the request is completed, are redefined
so that only the calling thread is suspended.
With regular files and devices capable of seeking, the
actual writing of data proceeds from the position in the
file indicated by the file pointer. If this incremented
file pointer is greater than the length of the file, the
length of the file is set to this file offset. Upon return
from the write() function, the file pointer increments by
the number of bytes actually written.
With devices incapable of seeking, writing always takes
place starting at the current position. The value of a file
pointer associated with such a device is undefined.
Fewer bytes than requested can be written if there is not
enough room to satisfy the request. In this case the number
of bytes written is returned. The next attempt to write a
nonzero number of bytes fails (except as noted in the fol-
lowing text). The limit reached can be either the ulimit()
or the end of the physical medium. For example, suppose
there is space for 20 bytes more in a file before reaching a
limit. A write of 512 bytes returns 20. The next write of
a nonzero number of bytes will give a failure return (except
as noted below).
Upon successful completion, the write() function returns the
number of bytes actually written to the file associated with
the fildes parameter. This number is never be greater than
the nbyte parameter.
If the O_APPEND flag of the file status is set, the file
offset is set to the end of the file prior to each write.
If the O_SYNC flag of the file status flags is set and the
fildes parameter refers to a regular file, a successful
write() function does not return until the data is delivered
to the underlying hardware (as described in the open() func-
tion).
Write requests to a pipe (or FIFO) are handled the same as a
regular file with the following exceptions:
o There is no file offset associated with a pipe; hence
each write() request appends to the end of the pipe.
o If the size of the write() request is less than or
equal to the value of the PIPE_BUF system variable, the
write() function is guaranteed to be atomic. The data
is not interleaved with data from other processes doing
writes on the same pipe. Writes of greater than
PIPE_BUF bytes can have data interleaved, on arbitrary
boundaries, with writes by other processes, whether or
not O_NONBLOCK or O_NDELAY are set.
o If neither O_NONBLOCK nor O_NDELAY are set, a write()
request to a full pipe causes the process to block
until enough space becomes available to handle the
entire request.
o If the O_NONBLOCK or O_NDELAY flag is set, write()
requests are handled differently in the following ways:
the write() function does block the process; write()
requests for PIPE_BUF or fewer bytes either succeed
completely and return nbyte, or return -1 and set errno
to [EAGAIN]. A write() request for greater than
PIPE_BUF bytes either transfers what it can and returns
the number of bytes written, or transfers no data and
returns -1 with errno set to [EAGAIN]. Also, if a
request is greater than PIPE_BUF bytes and all data
previously written to the pipe has been read, write()
transfers at least PIPE_BUF bytes.
When attempting to write to a file descriptor (other than a
pipe or a FIFO) that supports nonblocking writes and cannot
accept data immediately:
o If O_NDELAY and O_NONBLOCK are clear, the write() func-
tion blocks until the data can be accepted.
o If O_NDELAY or O_NONBLOCK are set, the write() function
does not block the process. Instead, if some data can
be written without blocking the process, it writes what
it can and returns the number of bytes written. Other-
wise, if O_NDELAY is set, it returns 0; if O_NONBLOCK
is set, it returns -1 and errno is set to [EAGAIN].
When attempting to write to a regular file with enforcement
mode record locking enabled, and all or part of the region
to be written is currently locked by another process:
o If O_NDELAY and O_NONBLOCK are clear (the default), the
calling process blocks until all the blocking locks are
removed, or the write() function is terminated by a
signal.
o If O_NDELAY or O_NONBLOCK is set, then the write()
function returns -1 and sets errno to [EAGAIN].
Upon successful completion, the write() function marks the
st_ctime and st_mtime fields of the file for update, and
clears its set-user ID and set-group ID attributes if the
file is a regular file.
The fcntl() function provides more information about record
locks.
The behavior of an interrupted write() function depends on
how the handler for the arriving signal was installed:
o If a write() function is interrupted by a signal before
it writes any data, it returns -1 with errno set to
[EINTR].
o If a write() function is interrupted by a signal after
it successfully writes some data, it returns the number
of bytes written. A write() request to a pipe or FIFO
never returns with errno set to [EINTR] if it has
transferred any data and nbyte is less than or equal to
PIPE_BUF.
o If the handler was installed with an indication that
functions should not be restarted, the write() function
returns a value of -1 and sets errno to [EINTR] (even
if some data was already written).
o If the handler was installed with an indication that
functions should be restarted:
-- If no data was written when the interrupt was han-
dled, the write() function does not return a value
(it is restarted).
-- If data was written when the interrupt was han-
dled, the write() function returns the amount of
data already written.
NOTES
AES Support Level:
Full use (write())
RETURN VALUES
Upon successful completion, the write() and writev() func-
tions return the number of bytes that were actually written.
Otherwise, -1 is returned and errno is set to indicate the
error.
ERRORS
If the write() or writev() function fails, errno may be set
to one of the following values:
[EBADF] The filedes parameter does not specify a valid
file descriptor open for writing.
[EINVAL] The file position pointer associated with the
filedes parameter was negative.
The iov_count parameter value was not between 1
and 1024, inclusive.
The iovcnt parameter value was less than or equal
to 0, or greater than {IOV_MAX}.
One of the iov_len values in the iov array was
negative or the sum overflowed a 32-bit integer.
[EFAULT] The buffer parameter or part of the iov parameter
points to a location outside of the allocated
address space of the process.
[EPIPE] An attempt was made to write to a pipe or FIFO
that is not opened for reading by any process. A
SIGPIPE signal is sent to the process.
An attempt was made to write to a pipe that has
only one end open.
[EPERM] An attempt was made to write to a socket or type
SOCK_STREAM that is not connected to a peer
socket.
[EAGAIN] The O_NONBLOCK flag is set on this file and the
process would be delayed in the write operation.
An enforcement mode record lock is outstanding in
the portion of the file that is to be written, and
O_NDELAY or O_NONBLOCK is set.
[ENOLCK] Enforced record locking is enabled and LOCK_MAX
regions are already locked in the system.
[EDEADLK] Enforced record locking is enabled, O_NDELAY is
clear, and a deadlock condition is detected.
[EFBIG] An attempt was made to write a file that exceeds
the maximum file size.
[ENOSPC] No free space is left on the file system contain-
ing the file.
[EINTR] A signal was caught during the write() operation,
and the signal handler was installed with an indi-
cation that functions are not to be restarted.
[EIO] The process is a member of a background process
group attempting to write to its controlling ter-
minal, TOSTOP is set, the process is neither
ignoring nor blocking SIGTTOU, and the process
group of the process is orphaned.
[ENXIO] The device associated with file descriptor (the
fildes parameter) is a block special device or
character special file and the file pointer is out
of range.
The AT&T SVID III manpage contains the following error con-
ditions. Should we add these to our manpage?
[ERANGE] Attempts to write to a stream with nbyte are out-
side the specified minimum and maximum range, and
the minimum value is non-zero.
[EAGAIN] A write to a pipe (FIFO) of {PIPE_BUF} bytes or
less is requested, O_NONBLOCK is set, and less
than nbytes bytes of free space is available.
[EAGAIN] Enforced record locking was enabled, O_NDELAY or
O_NONBLOCK was set and there there were record-
locks on the file, or O_NONBLOCK was set, and data
cannot be accepted immediately.
[EINVAL] The sum of the iov_len values in the iov array
overflowed an integer.
RELATED INFORMATION
Functions: open(2), fcntl(2), fcntl(2), lseek(2), open(2),
pipe(2), poll(2), select(2), ulimit(3)
Acknowledgement and Disclaimer