write(2) write(2)
NAME
write, writev - write into a file
SYNOPSIS
#include <unistd.h>
ssizet write(int fildes, const void *buf, sizet nbyte);
#include <sys/types.h>
#include <sys/uio.h>
int writev(int fildes, const struct iovec *iov, int iovcnt);
DESCRIPTION
write() attempts to write nbyte bytes from the buffer pointed to by
buf to the file associated with fildes. If nbyte is zero and the file
is a regular file, write() returns zero and has no other results.
fildes is a file descriptor obtained from a creat(), open(), dup(),
fcntl(), or pipe() system call.
writev() performs the same action as write(), but gathers the output
data from the iovcnt buffers specified by the members of the iov
array: iov[0], iov[1], ..., iov[iovcnt-1]. The iovcnt is invalid if
greater than 0 and less than or equal to IOVMAX.
For writev(), the iovec structure contains the following members:
caddrt iovbase;
int iovlen;
Each iovec entry specifies the base address and length of an area in
memory from which data should be written. writev() always writes a
complete area before proceeding to the next.
On devices capable of positioning, the actual writing of data proceeds
from the position in the file indicated by the file pointer. On return
from write(), the file pointer is incremented by the number of bytes
actually written. On a regular file, if the incremented file pointer
is greater than the length of the file, the length of the file is set
to the new file pointer.
On devices incapable of positioning, writing always takes place start-
ing at the current position. The value of a file pointer associated
with such a device is undefined.
If the OAPPEND flag of the file status flags is set, the file pointer
is set to the end of the file prior to each write(). The file is not
modified between setting the file pointer and starting the write().
Page 1 Reliant UNIX 5.44 Printed 11/98
write(2) write(2)
For regular files, if the OSYNC flag of the file status flags is set,
write() does not return until both the file data and file status have
been physically updated. This function is for special applications
that require extra reliability at the cost of performance. For block
special files, if OSYNC is set, write() does not return until the
data has been physically updated.
A write() to a regular file is blocked if mandatory file/record lock-
ing is set [see chmod(2)], and there is a record lock owned by another
process on the segment of the file to be written:
- If ONDELAY or ONONBLOCK is set, write() returns -1 and sets errno
to EAGAIN.
- If ONDELAY and ONONBLOCK are clear, write() sleeps until all
blocking locks are removed or the write() is terminated by a sig-
nal.
If a write() requests that more bytes be written than there is room -
for example, if the write would exceed the process' file size limit
[see getrlimit(2) and ulimit(2)], the system file size limit, or the
free space on the device - only as many bytes as there is room for
will be written. 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 non-zero number of bytes gives a failure return
(except for pipes and FIFO files) and the implementation will generate
a SIGXFSZ signal for the process.
If nbyte is greater than SSIZEMAX, the result is implementation-
dependent.
After successful execution of write(), the data specified by write()
is returned for each call to read() from each byte position of the
modified file, until such byte positions are again modified. Any sub-
sequent write() to the same byte position in a file will overwrite
that file data.
Write requests to a pipe or FIFO are handled the same as a regular
file with the following exceptions:
- There is no file offset associated with a pipe, hence each write
request appends to the end of the pipe. Write requests of PIPEBUF
bytes or less are guaranteed not to be interleaved with data from
other processes doing writes on the same pipe. Writes of greater
than PIPEBUF bytes may have data interleaved, on arbitrary boun-
daries, with writes by other processes, whether or not the
ONONBLOCK or ONDELAY flags are set.
- If ONONBLOCK and ONDELAY are clear, a write request may cause the
process to block, but on normal completion it returns nbyte.
Page 2 Reliant UNIX 5.44 Printed 11/98
write(2) write(2)
- If ONONBLOCK is set, write() requests are handled in the following
way: write requests for PIPEBUF or fewer bytes either succeed com-
pletely and return nbyte, or return -1 and set errno to EAGAIN. A
write() request for greater than PIPEBUF 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 PIPEBUF bytes and all data previously written to
the pipe has been read, write() transfers at least PIPEBUF bytes.
- If ONDELAY is set, write() requests are handled in the following
way: the write() does not block the process; write requests for
PIPEBUF or fewer bytes either succeed completely and return nbyte,
or return 0. A write() request for greater than PIPEBUF bytes
either transfers what it can and returns the number of bytes writ-
ten, or transfers no data and returns 0. Also, if a request is
greater than PIPEBUF bytes and all data previously written to the
pipe has been read, write() transfers at least PIPEBUF bytes.
When attempting to write to a file descriptor (other than a pipe or
FIFO) that supports nonblocking writes and cannot accept the data
immediately:
- If ONONBLOCK and ONDELAY are clear, write() blocks until the data
can be accepted.
- If ONONBLOCK or ONDELAY is set, write() does not block the pro-
cess. If some data can be written without blocking the process,
write() writes what it can and returns the number of bytes written.
Otherwise, if ONONBLOCK is set, it returns -1 and sets errno to
EAGAIN, or, if ONDELAY is set, it returns 0.
For STREAMS files the operation of write() is determined by the values
of the minimum and maximum nbyte range ("packet size") accepted by the
stream. These values are contained in the topmost stream module.
Unless the user pushes the topmost module [see IPUSH in streamio(7)],
these values can not be set or tested from user level. If nbyte falls
within the packet size range, nbyte bytes are written.
If nbyte does not fall within the range and the minimum packet size
value is zero, write() breaks the buffer into maximum packet size seg-
ments prior to sending the data downstream (the last segment may be
smaller than the maximum packet size). If nbyte does not fall within
the range and the minimum value is non-zero, write() fails and sets
errno to ERANGE. Writing a zero-length buffer (nbyte is zero) to a
STREAMS device sends a zero length message with zero returned. How-
ever, writing a zero-length buffer to a pipe or FIFO sends no message
and zero is returned. The user program may issue the ISWROPT ioctl to
enable zero-length messages to be sent across the pipe or FIFO [see
streamio(7)].
Page 3 Reliant UNIX 5.44 Printed 11/98
write(2) write(2)
When writing to a stream, data messages are created with a priority
band of zero. When writing to a stream that is not a pipe or FIFO, the
effect is as follows:
- If ONDELAY and ONONBLOCK are not set, and the stream cannot
accept data (the stream write queue is full due to internal flow
control conditions), write() blocks until data can be accepted.
- If ONDELAY or ONONBLOCK is set and the stream cannot accept data,
write() returns -1 and sets errno to EAGAIN.
- If ONDELAY or ONONBLOCK is set and part of the buffer has already
been written when a condition occurs in which the stream cannot
accept additional data, write() terminates and returns the number
of bytes written.
For regular files, no data transfer will occur past the offset maximum
established in the open file description associated with fildes.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
write() and writev() fail and the file pointer remains unchanged if
one or more of the following apply:
EAGAIN Mandatory file/record locking is set, ONDELAY or ONONBLOCK
is set, and there is a blocking record lock.
EAGAIN Total amount of system memory available when reading via raw
I/O is temporarily insufficient.
EAGAIN An attempt is made to write to a stream that can not accept
data with the ONDELAY or ONONBLOCK flag set.
EAGAIN If a write() to a pipe or FIFO of PIPEBUF bytes or less is
requested and less than nbytes of free space is available.
EBADF fildes is not a valid file descriptor open for writing.
EDEADLK The write() is sleeping and causes a deadlock situation to
occur.
EFAULT buf points outside the process' allocated address space.
EFBIG An attempt is made to write a file that exceeds the process'
file size limit or the maximum file size [see getrlimit(2)
and ulimit(2)].
Page 4 Reliant UNIX 5.44 Printed 11/98
write(2) write(2)
The file is a regular file, nbyte is greater than 0 and the
starting position is greater than or equal to the offset
maximum established in the open file description associated
with fildes.
EINTR The write operation was terminated due to the receipt of a
signal, and no data was transferred.
EINVAL The STREAM or multiplexer referenced by fildes is linked
(directly or indirectly) downstream from a multiplexer.
EIO A physical I/O error has occurred.
EIO The process is in the background and is attempting to write
to its controlling terminal whose TOSTOP flag is set; the
process is neither ignoring nor blocking SIGTTOU signals,
and the process group of the process is orphaned.
ENOLCK The system record lock table was full, so the write() could
not go to sleep until the blocking record lock was removed.
ENOLINK fildes is on a remote machine and the link to that machine
is no longer active.
ENOSR An attempt is made to write to a stream with insufficient
STREAMS memory resources available in the system.
ENOSPC During a write() to an ordinary file, there is no free space
left on the device.
ENXIO A request was made of a non-existent device, or the request
was outside the capabilities of the device.
ENXIO A hangup occurred on the stream being written to.
EPIPE An attempt is made to write to a pipe or a FIFO file that is
not open for reading by any process or that has only one end
open. A SIGPIPE signal is sent to the process.
ERANGE An attempt is made to write to a stream with nbyte outside
the specified minimum and maximum write range, and the
minimum value is non-zero.
ENOLCK Enforced record locking was enabled, and there are no more
record locks available (too many file segments locked)
because the system maximum has been exceeded.
Page 5 Reliant UNIX 5.44 Printed 11/98
write(2) write(2)
In addition, writev() may return one of the following errors:
EINVAL iovcnt was less than or equal to 0, or greater than or equal
to 16, or one of the iovlen values in the iov array was
negative, or the sum of the iovlen values in the iov array
overflowed a 32-bit integer.
A write() to a STREAMS file can fail if an error message has been
received at the stream head. In this case, errno is set to the value
included in the error message.
Upon successful completion write() and writev() mark for update the
stctime and stmtime fields of the file.
RESULT
Upon successful completion, write() will return the number of bytes
actually written to the file associated with fildes. This number will
never be greater than nbyte. Otherwise, -1 is returned and errno is
set to indicate the error.
Upon successful completion, writev() returns the number of bytes actu-
ally written. Otherwise, it returns a value of -1, the file-pointer
remains unchanged, and errno is set to indicate an error.
NOTES
write() and writev() may do a "partial read or write" due to the
offset maximum. That is, the value returned may be less than nbyte if
the number of bytes remaining which may be transferred is less than
nbyte.
SEE ALSO
chmod(2), creat(2), dup(2), fcntl(2), getrlimit(2), lseek(2), open(2),
pipe(2), ulimit(2), limits(4), unistd(4), lfs(5), stropts(5),
types(5), uio(5).
Page 6 Reliant UNIX 5.44 Printed 11/98