HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

w
write(2) write(2)
- The write() function will not block the process.
- A write request for {PIPE_BUF} or fewer bytes will have the following effect: If there is
sufficient space available in the pipe,
write() will transfer all the data and return the
number of bytes requested. Otherwise,
write() will transfer no data and return −1 with
errno set to [EAGAIN].
- A write request for more than
{PIPE_BUF} bytes will case one of the following:
a. 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 is read, it will transfer at least
{PIPE_BUF} bytes.
b. When no data can be written, transfer no data and return −1 with
errno set to [EAGAIN].
When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes
and cannot accept the data immediately:
• If the
O_NONBLOCK flag is clear,
write() will block until the data can be accepted.
• If the
O_NONBLOCK flag is set,
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].
Upon successful completion, where nbyte is greater than 0, write() will mark for update the st_ctime
and st_mtime fields of the file, and if the file is a regular file, the
S_ISUID and S_ISGID bits of the file
mode may be cleared.
If fildes refers to a STREAM, 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 determined by the top-
most STREAM module. If nbyte falls within the packet size range, nbyte bytes will be written. If nbyte does
not fall within the range and the minimum packet size value is 0,
write() will break the buffer into max-
imum packet size segments prior to sending the data downstream (the last segment may contain less than
the maximum packet size). If nbyte does not fall within the range and the minimum value is non-zero,
write() will fail with errno set to [ERANGE]. Writing a zero-length buffer ( nbyte is 0) to a STREAMS
device 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
I_SWROPT ioctl() to enable
zero-length messages to be sent across the pipe or FIFO.
When writing to a STREAM, data messages are created with a priority band of 0. When writing to a
STREAM that is not a pipe or FIFO:
• If
O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is full
due to internal flow control conditions), write() will block until data can be accepted.
• If O_NONBLOCK is set and the STREAM cannot accept data, write() will return −1 and set
errno to [EAGAIN].
• If O_NONBLOCK is set and part of the buffer has been written while a condition in which the
STREAM cannot accept additional data occurs, write() will terminate and return the number of
bytes written.
In addition, write() 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() or writev() but
reflects the prior error.
The writev() function is equivalent to 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]. iovcnt is valid if greater than 0
and less than or equal to {IOV_MAX} , defined in <limits.h> .
Each iovec entry specifies the base address and length of an area in memory from which data should be
written. The writev() function will always write a complete area before proceeding to the next.
If fildes refers to a regular file and all of the iov_len members in the array pointed to by iov are 0, wri-
tev()
will return 0 and have no other effect. For other file types, the behaviour is unspecified.
If the sum of the iov_len values is greater than SSIZE_MAX, the operation fails and no data is transferred.
The pwrite() function performs the same action as write(), except that it writes into a given position
without changing the file pointer. The first three arguments to pwrite() are the same as write()
with the addition of a fourth argument offset for the desired position inside the file.
HP-UX 11i Version 1: September 2005 − 2 − Hewlett-Packard Company Section 2−−481