pwrite(2) pwrite(2)
NAME
pwrite - atomic position and write
SYNOPSIS
#include <unistd.h>
ssizet pwrite(int dk, const void *buf, sizet nbyte, offt offset);
DESCRIPTION
The pwrite() system call does an atomic position-and-write, eliminat-
ing the necessity of using a locking mechanism when both operations
are desired and file descriptors are shared. pwrite() is analogous to
write() but takes a fourth argument, offset. The write is done as if
an lseek() to offset (from the beginning of the file) were done first.
Note that (though the semantics are analogous) an lseek() is not actu-
ally performed; the file pointer is not affected by pwrite(). The
write of nbytes then starts at the specified offset.
The atomicity of pwrite() enables processes or threads that share file
descriptors to write to the shared file at a particular offset without
using a locking mechanism that would be necessary to achieve the same
result in separate lseek() and write() system calls. Atomicity is
required as the file pointer is shared and one thread might move the
pointer using lseek() after another process completes an lseek() but
prior to the write().
RETURN VALUES
Upon successful completion, pwrite() returns the number of bytes actu-
ally written from buf. Otherwise a -1 and an error is returned.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
In the following conditions, pwrite() fail and set errno to:
EAGAIN Mandatory file/record locking is set, ONDELAY or ONONBLOCK
is set, and there is a blocking record lock.
EAGAIN Total amount of system memory available when reading via raw
I/O is temporarily insufficient.
EAGAIN An attempt is made to write to a stream that can not accept
data with the ONDELAY or ONONBLOCK flag set.
EAGAIN If a pwrite() to a pipe or FIFO of PIPEBUF bytes or less is
requested and less than nbytes of free space is available.
EBADF fildes is not a valid file descriptor open for writing.
EDEADLK The pwrite() is sleeping and causes a deadlock situation to
occur.
Page 1 Reliant UNIX 5.44 Printed 11/98
pwrite(2) pwrite(2)
EFAULT buf points outside the process' allocated address space.
EFBIG An attempt is made to write a file that exceeds the process'
file size limit or the maximum file size [see getrlimit(2)
and ulimit(2)].
EINTR A signal was caught during the pwrite() system call.
EINVAL An attempt is made to write to a stream linked below a multi-
plexer.
EIO The process is in the background and is attempting to write
to its controlling terminal whose TOSTOP flag is set; the
process is neither ignoring nor blocking SIGTTOU signals, and
the process group of the process is orphaned.
ENOLCK The system record lock table was full, so the pwrite() could
not go to sleep until the blocking record lock was removed.
ENOLINK fildes is on a remote machine and the link to that machine is
no longer active.
ENOSR An attempt is made to write to a stream with insufficient
STREAMS memory resources available in the system.
ENOSPC During a pwrite() to an ordinary file, there is no free space
left on the device.
ENXIO A hangup occurred on the stream being written to.
EPIPE An attempt is made to write to a pipe or a FIFO file that is
not open for reading by any process or that has only one end
open. A SIGPIPE signal is sent to the process.
ERANGE An attempt is made to write to a stream with nbyte outside
the specified minimum and maximum write range, and the
minimum value is non-zero.
ENOLCK Enforced record locking was enabled, and there are no more
record locks available (too many file segments locked)
because the system maximum has been exceeded.
SEE ALSO
creat(2), dup(2), fcntl(2), lseek(2), open(2), pread(2), write(2),
unistd(4).
Page 2 Reliant UNIX 5.44 Printed 11/98