write, pwrite, writev - Write to a file
#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 );
Interfaces documented on this reference page conform to
industry standards 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 standards(5) reference
page for more information about industry standards
and associated tags.
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 following members:
void *iov_base; size_t iov_len; Specifies the number
of iovec structures pointed to by the iov
parameter.
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 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 equivalent 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
increments 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 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 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 immediately, the write() and pwrite()
functions behave as follows: If O_NONBLOCK is clear, the
function blocks until the data can be accepted.
[Tru64 UNIX] This also applies if O_NDELAY is
clear. If O_NONBLOCK 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
written. 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 enforcement 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
blocking 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 [Toc] [Back]
[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_NONBLOCK 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_NONBLOCK is set and part of the buffer has
been written when a condition 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.
[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 suspend 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() function, 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], depending on the setting of the SA_RESTART option
for the interrupting signal.
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.
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 [Toc] [Back]
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 warning" EOT.
End-of-Media Handling for Disks [Toc] [Back]
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.
The write(), pwrite(), and writev() functions set errno to
the specified 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 cannot 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 referenced 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 warning" 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 parameter) 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
connected 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
complete 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 directory, 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 System 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.
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)
[ Back ] |
