write(2)write(2)NAME
write, pwrite, writev - Write to a file
SYNOPSIS
#include <unistd.h>
ssize_t write(
int filedes,
const void *buffer,
size_t nbytes ); ssize_t pwrite(
int filedes,
const void *buffer,
size_t nbytes,
off_t offset ); #include <sys/uio.h>
ssize_t writev(
int filedes,
const struct iovec *iov,
int iov_count );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
write(), writev(): XSH4.0, XSH4.2, XSH5.0, XNS5.0
pwrite(): POSIX.1, XSH5.0
Unless otherwise stated, when text is tagged with an indicator for a
particular revision of a standard, the information applies when the
application is built in a compilation environment that adheres to the
specified and higher revisions of that standard. Refer to the stan‐
dards(5) reference page for more information about industry standards
and associated tags.
PARAMETERS
Identifies the file to which the data is to be written. Points to the
buffer containing the data to be written. Specifies the number of
bytes to write to the file associated with the filedes parameter.
Specifies the desired start position inside the file associated with
the filedes parameter. 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 fol‐
lowing members:
void *iov_base; size_t iov_len; 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 asso‐
ciated with the filedes parameter from the buffer pointed to by the
buffer parameter.
If the nbytes parameter is 0 (zero), the write() function returns 0
(zero) and has no other results if the file is a regular file.
[XNS5.0] If filedes refers to a socket, a write() request is equiva‐
lent to a send() request with no options set.
The pwrite() function performs the same action as write(), except that
it writes into a given position in the file (specified by the offset
parameter) without changing the file pointer.
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 iov_count parameter is valid if
greater than 0 (zero) and less than or equal to IOV_MAX, which is
defined in the <limits.h> header file. The writev() function always
writes a complete area before proceeding to the next.
If filedes refers to a regular file and all of the iov_len members in
the array pointed to by iov are 0 (zero), writev() returns 0 and has no
other effect.
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() or pwrite() function, the file pointer incre‐
ments by the number of bytes actually written.
If the O_SYNC flag of the file status options is set and the filedes
parameter refers to a regular file, a successful write() or pwrite()
call does not return until the data is delivered to the underlying
hardware, as described in open(2).
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.
If the O_APPEND flag of the file status options is set, the file offset
is set to the end of the file prior to each write, and no intervening
file modification operation occurs between changing the file offset and
the write operation.
If a write() or pwrite() requests that more bytes be written than there
is space for (for example, the ulimit() or the physical end of a
medium), only as many bytes as there is space for are 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
nonzero number of bytes will give a failure return (except as noted
below) and [XSH4.2] a SIGXFSZ signal is generated for the process.
If a write() or pwrite() function is interrupted by a signal before it
writes any data, it returns -1 with errno set to [EINTR].
If a write() or pwrite() function is interrupted by a signal after it
successfully writes some data, it returns the number of bytes written.
After a write() or pwrite() to a regular file has successfully
returned: Any successful read() from each byte position in the file
that was modified by that write returns the data specified by the
write() or pwrite() for that position until such byte positions are
again modified. Any subsequent successful write() or pwrite() to the
same byte position in the file overwrites 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() or pwrite() request appends to the end
of the pipe. If the size of the write() or pwrite() request is less
than or equal to the value of the PIPE_BUF system variable, the write()
or pwrite() call is guaranteed to be atomic. The data is not inter‐
leaved 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 is set.
[Tru64 UNIX] This also applies whether or not O_NDELAY is set.
If O_NONBLOCK is clear, a write() or pwrite() request to a full
pipe causes the process to block until enough space becomes
available to handle the entire request.
[Tru64 UNIX] This also applies if O_NDELAY is clear. If the
O_NONBLOCK flag is set, write() or pwrite() requests are handled
differently in the following ways: the function does block the
process; requests for PIPE_BUF or fewer bytes either succeed
completely and return nbytes, or return -1 and set errno to
[EAGAIN]. A request for greater than PIPE_BUF bytes either
transfers as much as 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()
or pwrite() transfers at least PIPE_BUF bytes.
[Tru64 UNIX] This also applies if O_NDELAY is set.
When attempting to write to a file descriptor (other than a pipe or a
FIFO) that supports nonblocking writes and cannot accept data immedi‐
ately, the write() and pwrite() functions behave as follows: If O_NON‐
BLOCK is clear, the function blocks until the data can be accepted.
[Tru64 UNIX] This also applies if O_NDELAY is clear. If O_NON‐
BLOCK is set, the function does not block the process. Instead,
if some data can be written without blocking the process, it
writes as much as it can and returns the number of bytes writ‐
ten. Otherwise, it returns -1 and errno is set to [EAGAIN].
[Tru64 UNIX] This also applies if O_NDELAY is set, except 0
(zero) is returned.
[Tru64 UNIX] When attempting to write to a regular file with enforce‐
ment mode record locking enabled and all or part of the region to be
written is currently locked by another process, the write() and
pwrite() functions behave as follows: If O_NDELAY and O_NONBLOCK are
clear (the default), the calling process blocks until all of the block‐
ing locks are removed or until the function is terminated by a signal.
If O_NDELAY or O_NONBLOCK is set, the function returns --1 and sets
errno to [EAGAIN].
Upon successful completion, the write() or pwrite() function marks the
st_ctime and st_mtime fields of the file for update and, if the file is
a regular file, clears its set-user ID and set-group ID attributes.
The fcntl(2) reference page provides more information about record
locks.
Writing Data to STREAMS Files
[XSH4.2] For STREAMS files, the operation of write() and pwrite() is
determined by the values of the minimum and maximum nbytes range
(“packet size” accepted by the STREAM). These values are contained in
the topmost STREAM module. Unless the user pushes the topmost module,
these values cannot be set or tested from user level (see I_PUSH on the
streamio(7)) reference page). If nbytes falls within the packet size
range, nbytes bytes are written. If nbytes does not fall within the
range and the minimum packet size value is 0 (zero), write() or
pwrite() breaks the buffer into maximum packet size segments prior to
sending the data downstream (the last segment may contain less than the
maximum packet size). If nbytes does not fall within the range and the
minimum value is nonzero, write() or pwrite() fails with errno set to
[ERANGE]. Writing a zero-length buffer (nbytes is 0) sends 0 bytes
with 0 returned. However, writing a zero-length buffer to a STREAMS-
based pipe or FIFO sends no message and 0 is returned. The process may
issue the I_SWROPT ioctl() request to enable zero-length messages to be
sent across the pipe or FIFO.
[XSH4.2] When writing to a STREAM, data messages are created with a
priority band of 0 (zero). When writing to a STREAM that is not a pipe
or FIFO, the write() and pwrite() functions behave as follows: If
O_NONBLOCK is clear and the STREAM cannot accept data (that is, the
STREAM write queue is full due to internal flow control conditions),
the function blocks until data can be accepted.
[Tru64 UNIX] This also applies if O_NDELAY is clear. If O_NON‐
BLOCK is set and the STREAM cannot accept data, the function
returns -1 and sets errno to [EAGAIN].
[Tru64 UNIX] This also applies if O_NDELAY is set. If O_NON‐
BLOCK is set and part of the buffer has been written when a con‐
dition occurs in which the STREAM cannot accept additional data,
the function terminates and returns the number of bytes written.
[Tru64 UNIX] This also applies if O_NDELAY is set.
[XSH4.2] In addition, write(), pwrite(), and writev() will fail if the
STREAM head had processed an asynchronous error before the call. In
this case, the value of errno does not reflect the result of write(),
pwrite(), or writev(), but reflects the prior error.
NOTES
[Tru64 UNIX] For compatibility with earlier releases, values for
iov_len that are greater than or equal to 2^63 will be treated as zero.
[Tru64 UNIX] The write(), pwrite(), and writev() functions, which sus‐
pend the calling process until the request is completed, are redefined
so that only the calling thread is suspended.
[Tru64 UNIX] When debugging a module that includes the writev() func‐
tion, use _Ewritev to refer to the writev() call.
When a read(), pread(), write(), or pwrite() system call on a pipe is
interrupted by a signal and no bytes have been transferred through the
pipe, a value of -1 is returned and errno is set to [EINTR]. This
behavior is different from previous releases in which both read() and
write() either restarted the transfer or set errno to [EINTR], depend‐
ing on the setting of the SA_RESTART option for the interrupting sig‐
nal.
As a result of this change, applications must now either handle the
[EINTR] error or block any expected signals for the duration of the
read(), pread(), write(), or pwrite() operation.
RETURN VALUES
Upon successful completion, the write() or pwrite() function returns
the number of bytes actually written to the file associated with the
filedes parameter. This number is never greater than nbytes. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
Upon successful completion, the writev() function returns the number of
bytes that were actually written. Otherwise, a value of -1 is returned,
the file-pointer remains unchanged, and errno is set to indicate the
error.
End-of-Media Handling for Tapes
If writing goes beyond the “early warning” EOT indicator while this
indicator is disabled, the write(), pwrite(), and writev() functions
will return the number of bytes actually written. The write(),
pwrite(), and writev() functions return a value of -1, if: Attempting
to write past the “real” EOT. Attempting to write past “early warning”
EOT indicator while this indicator is enabled.
Refer to mtio(7) for information on enabling and disabling “early warn‐
ing” EOT.
End-of-Media Handling for Disks
Disk end-of-media handling is POSIX-compliant. Attempting to write at
or beyond the end of a partition returns a value of -1. A partial write
returns the number of bytes actually written.
Note: A partial write is a request that spans the end of a partition.
ERRORS
The write(), pwrite(), and writev() functions set errno to the speci‐
fied values for the following conditions: The O_NONBLOCK flag is set on
this file and the process would be delayed in the write operation.
[Tru64 UNIX] An attempt was made to write to a STREAM that can‐
not accept data with either the O_NDELAY or O_NONBLOCK flag set.
[Tru64 UNIX] An enforcement mode record lock is outstanding in
the portion of the file that is to be written. The filedes
parameter does not specify a valid file descriptor that is open
for writing. [Tru64 UNIX] Enforced record locking is enabled,
O_NDELAY is clear, and a deadlock condition is detected. [Tru64
UNIX] The write failed because the user's disk block quota is
exhausted. [Tru64 UNIX] The buffer parameter or part of the
iov parameter points to a location outside the allocated address
space of the process. An attempt was made to write a file that
exceeds the maximum file size. A write() or pwrite() on a pipe
is interrupted by a signal and no bytes have been transferred
through the pipe. [XSH4.2] The STREAM or multiplexer refer‐
enced by filedes is linked (directly or indirectly) downstream
from a multiplexer.
[XSH4.2] The iov_count parameter value was less than or equal
to 0 or greater than IOV_MAX.
[XSH4.2] The sum of the iov_len values in the iov array would
overflow an ssize_t buffer.
[Tru64 UNIX] The file position pointer associated with the
filedes parameter was negative.
[Tru64 UNIX] One of the iov_len values in the iov array was
negative or the sum overflowed a 32-bit integer. [XSH4.2] A
physical I/O error occurred. These errors do not always occur
with the associated function, but can occur with the subsequent
function. [Tru64 UNIX] The file has enforcement mode file
locking set, and allocating another locked region would exceed
the configurable system limit of NLOCK_RECORD. [XSH4.2] No
free space is left on the file system containing the file.
[Tru64 UNIX] An attempt was made to write past the “early warn‐
ing” EOT while this indicator was enabled.
[Tru64 UNIX] An attempt was made to write at or beyond the end
of a partition. [XSH4.2] A hangup occurred on the STREAM being
written to.
The device associated with file descriptor (the filedes parame‐
ter) is a block special device or character special file, and
the file pointer is out of range. [Tru64 UNIX] An attempt was
made to write to a socket or type SOCK_STREAM that is not con‐
nected to a peer socket. [XSH4.2] An attempt was made to write
to a pipe that has only one end open.
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. [XSH4.2] The transfer request size was outside
the range supported by the STREAMS file associated with filedes.
In addition, the pwrite() function fails and the file pointer remains
unchanged if the following is true: The file specified by fildes is
associated with a pipe or FIFO.
[XSH4.2] 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.
For NFS file access, if the write(), pwrite(), or writev() function
fails, errno may also be set to one of the following values: [Tru64
UNIX] For filesystems mounted with the nfsv2 option, the process
attempted to write beyond the 2 gigabyte boundary. [Tru64 UNIX] The
named file is a directory and write access is requested. [Tru64
UNIX] Insufficient resources, such as buffers, are available to com‐
plete the call. Typically, a call used with sockets has failed due to
a shortage of message or send/receive buffer space. [Tru64 UNIX] The
named file resides on a read-only file system and write access is
required. [Tru64 UNIX] The NFS file handle is stale. An opened file
was deleted by the server or another client, a client cannot open a
file because the server has unmounted or unexported the remote direc‐
tory, or the directory that contains an opened file was either
unmounted or unexported by the server.
If the write(), pwrite(), or writev() function fails while in the Sys‐
tem V habitat, errno may also be set to one of the following errors:
[Tru64 UNIX] 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.
[Tru64 UNIX] Enforced record locking was enabled, O_NDELAY or
O_NONBLOCK was set and there were record-locks on the file, or
O_NONBLOCK was set, and data cannot be accepted immediately.
[Tru64 UNIX] The sum of the iov_len values in the iov array
overflowed an integer. [Tru64 UNIX] Attempts to write to a
STREAM with nbytes are outside the specified minimum and maximum
range, and the minimum value is non-zero.
SEE ALSO
Functions: fcntl(2), getmsg(2), lseek(2), open(2), pipe(2), poll(2),
select(2), lockf(3), ulimit(3)
Files: mtio(7)
Standards: standards(5)write(2)
