HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

w
write(2) write(2)
• The system-dependent maximum number of bytes that a pipe or FIFO can store is
PIPSIZ as
defined in
<sys/inode.h>
.
• The minimum value of
PIPSIZ on any HP-UX system is 8192.
When writing a pipe with the O_NDELAY or
O_NONBLOCK file status flag set, the following apply:
• If nbyte is less than or equal to
PIPSIZ and sufficient room exists in the pipe or FIFO, the
write() succeeds and returns the number of bytes written.
• If nbyte is less than or equal to
PIPSIZ but insufficient room exists in the pipe or FIFO, the
write() returns having written nothing. If O_NONBLOCK is set,
-1 is returned and errno is
set to [EAGAIN]. If
O_NDELAY is set, 0
is returned.
• If nbyte is greater than
PIPSIZ and the pipe or FIFO is full, the write returns having written
nothing. If
O_NONBLOCK is set, -1 is returned and
errno is set to [EAGAIN]. If O_NDELAY is
set,
0 is returned.
• If nbyte is greater than PIPSIZ
, and some room exists in the pipe or FIFO, as much data as fits in
the pipe or FIFO is written, and
write() returns the number of bytes actually written, an
amount less than the number of bytes requested.
When writing a pipe and the
O_NDELAY and O_NONBLOCK file status flags are clear, the
write()
always executes correctly (blocking as necessary), and returns the number of bytes written.
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, the following apply:
• 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.
For character special devices, if the
stopio() call was used on the same device after it was opened,
write() returns -1, sets errno to [EBADF], and issues the SIGHUP signal to the process.
write()
also clears the potential and granted privilege vectors on the file.
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, the following apply:
• 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.
If the write is performed by any user other than the owner or a user who has appropriate privileges,
write() clears the set-user-ID, set-group-ID, and sticky bits on all nondirectory files. If the write is
HP-UX 11i Version 3: February 2007 − 2 − Hewlett-Packard Company 551