write(2) SDK R4.11 write(2)
NAME
write, pwrite - write to an object
SYNOPSIS
#include <unistd.h>
ssize_t write (fildes, buffer, nbyte)
int fildes;
const void * buffer;
size_t nbyte;
ssize_t pwrite (fildes, buffer, nbyte,offset)
int fildes;
const void * buffer[];
size_t nbyte;
off_t offset;
where:
fildes An active, valid file descriptor.
buffer User data buffer.
nbyte Size (in bytes) of the write request.
offset Byte position in the object where the write is to begin.
DESCRIPTION
Write transfers nbyte bytes of data from the buffer pointed to by
buffer into the object associated with fildes.
Pwrite does an atomic seek and write, eliminating the necessity of
using a locking mechanism when both operations are desired and file
descriptors are shared. The behavior of pwrite is identical to write
except for the handling of the object's position attribute. Pwrite
does not operate on pipe or socket type objects.
If fildes refers to an object pointer having a current position
attribute and the O_APPEND flag is clear, the write starts at a
position in the object given by that attribute.
If fildes refers to an object pointer having a current position
attribute and the O_APPEND flag is set, the position attribute of the
object is set equal to the object's current size, where the write
will start.
If the object pointer has no position attribute, then the starting
write position depends on the type of object being written.
Pwrite does not use the position attribute of the object, nor does it
affect it. The I/O begins at the position in the object specified by
offset. The O_APPEND flag has no affect on pwrite. An error is
returned if the specified offset is past the two gigabyte file size
limit.
The behavior of the write call is affected by the object attribute
flag O_NDELAY [see open(2)] associated with fildes.
The behavior of writes to a pipe or FIFO depends on whether or not
the request is for more than PIPE_BUF bytes. 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
boundaries, with writes by other processes, whether or not the
ONONBLOCK or ONDELAY flags are set. Also, if a request is greater
than PIPEBUF bytes and all data previously written to the pipe has
been read, write will transfer at least PIPEBUF bytes.
If a write of nbyte bytes to a pipe (or FIFO) is requested, and nbyte
is less than PIPE_BUF bytes, but nbyte of free space is currently not
available in the pipe, then the following occurs:
If the O_NDELAY and O_NONBLOCK flags are clear, the process
will block until at least nbyte bytes of free space becomes
available in the pipe, and the write will take place.
If the O_NONBLOCK flag is set, -1 is returned and errno is set
to EAGAIN. If both O_NONBLOCK and O_NDELAY are set,
O_NONBLOCK has precedence.
If the O_NDELAY flag is set, 0 is returned.
If a write of more than PIPE_BUF bytes is requested, the following
occurs:
If the O_NDELAY and O_NONBLOCK flags are clear, the process
will block if the pipe is full. As space becomes available in
the pipe, the data from the write request will be written
piecemeal--in multiple smaller amounts until the request is
fulfilled. Thus, data from a write request of more than
PIPE_BUF bytes may be interleaved on arbitrary byte boundaries
with data written by other processes.
If the O_NONBLOCK flag is set and the pipe is full, the
process will not block, -1 is returned with errno set to
EAGAIN. If both O_NONBLOCK and O_NDELAY are set, O_NONBLOCK
has precedence.
If the O_NONBLOCK flag is set and the pipe is not full, the
process will not block, and as much data as will currently fit
in the pipe will be written and that number of bytes is
returned.
If the O_NDELAY is set and the pipe is full, the process will
not block, and 0 is returned.
If the O_NDELAY flag is set and the pipe is not full, the
process will not block, and as much data as will currently fit
in the pipe will be written and that number of bytes is
returned.
For STREAMS files [see intro(2)], 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. 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 segments 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. However, 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(2) to enable zero-length
messages to be sent across the pipe or FIFO [see streamio(7)].
When writing to a stream, data messages are created with a priority
band of zero.
The behavior of the write call is affected by the object attribute
flag O_SYNC associated with fildes. This flag causes the write call
to block until both the file data and file status are physically
updated.
When write completes, the position attribute, if it exists, is
incremented by the number of bytes actually written. Pwrite does not
affect the position attribute of the object in any way. The
modification time for the file and the changed time for the file
status are updated to reflect the time the write occurred.
If an error occurs, any changes to the object associated with fildes
is defined by the object's type. The default situation is that the
object associated with fildes is unchanged. This may not be the case
for some errors on some types of objects.
If write is successful and O_SYNC is not specified, the data
transferred may not be transferred to long term storage (in the case
of an `ordinary-disk-file' for example). To ensure this is the case,
the fsync operation should be used.
ACCESS CONTROL
Fildes must be open for writing.
RETURN VALUE
0..nbyte Completed successfully. nbyte is the number of bytes
actually written.
-1 An error occurred. errno is set to indicate the
error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EBADF Fildes is not a valid file descriptor open for writing.
ERANGE if attempts to write to a stream with nbyte are outside the
specified minimum and maximum write range, and the minimum
value is non-zero. if the process is a member of a
background process group and is attempting to write to its
controlling terminal, TOSTOP is set, the process is neither
ignoring nor blocking SIGTTOU and the process group of the
process is orphaned.
EAGAIN The write request was greater than PIPE_BUF bytes,
O_NONBLOCK was set and there was no room to write any bytes
in the pipe.
EAGAIN The write request was less than PIPE_BUF bytes, O_NONBLOCK
was set and there was not enough room in the pipe to write
the entire request.
EPIPE and SIGPIPE signal
An attempt is made to write to a pipe not open for reading
or a socket of type SOCK_STREAM that is not connected to a
peer socket.
EFBIG An attempt was made to write a file that exceeds the
process's file size limit or the maximum file size.
EFAULT Buffer points outside the process's allocated address
space.
EINTR A signal was caught during the write system call.
EINVAL For pwrite, an invalid offset was specified. An example of
an invalid offset would be a value past the two gigabyte
file size limit.
ENOLCK A lock required to complete the call cannot be allocated
from the system lock table.
EOPNOTSUPP
The pwrite system call does not support writing to a
socket.
ESPIPE Pwrite was attempted on a pipe type object.
EDEADLK fildes refers to a file that has mandatory record locking
enabled and the write would produce a deadlock condition.
SEE ALSO
creat(2), dup(2), dup2(2), fcntl(2), ioctl(2), lseek(2), open(2),
pipe(2), select(2), socket(2), socketpair(2), ulimit(2), writev(2).
Licensed material--property of copyright holder(s)