pwrite(2) pwrite(2)
NAME
pwrite - atomic position and write
SYNOPSIS
#include <unistd.h>
ssize_t pwrite(int fd, const void *buf, size_t nbytes, off_t offset);
DESCRIPTION
The pwrite system call does an atomic position-and-write,
eliminating 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 actually 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
actually written from buf. Otherwise a -1 and an error is
returned.
Errors
In the following conditions, pwrite fail and set errno to:
EAGAIN Mandatory file/record locking is set, O_NDELAY
or O_NONBLOCK 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
cannot accept data with the O_NDELAY or
O_NONBLOCK flag set.
Copyright 1994 Novell, Inc. Page 1
pwrite(2) pwrite(2)
EBADF fildes is not a valid file descriptor open for
writing.
EDEADLK The pwrite was going to go to sleep and cause a
deadlock to occur.
EFAULT buf points outside the process's allocated
address space.
EFBIG An attempt is made to write a file that exceeds
the process's 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 multiplexor.
EINVAL The resulting file pointer would be negative.
fildes is a remote file descriptor accessed
using NFS, the Network File System, and the
resulting file pointer would be negative.
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.
EIO fildes points to a device special file that is
in the closing state.
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.
Copyright 1994 Novell, Inc. Page 2
pwrite(2) pwrite(2)
ENOSPC During a pwrite to an ordinary file, there is
no free space left on the device.
ENXIO The device associated with the file descriptor
is a block-special or character-special file
and the file-pointer value is out of range.
ERANGE An attempt is made to write to a stream with
nbyte outside specified minimum and maximum
write range, and the minimum value is non-zero.
ENOLCK Enforced record locking was enabled and
{LOCK_MAX} regions are already locked in the
system.
ESPIPE fildes is associated with a pipe or fifo.
ENOSYS The device for fstype does not support lseek.
REFERENCES
creat(2), dup(2), fcntl(2), lseek(2), open(2), pread(2),
write(2)
NOTICES
Considerations for Threads Programming
Open file descriptors are a process resource and available to
any sibling thread; if used concurrently, actions by one
thread can interfere with those of a sibling.
While one thread is blocked, siblings might still be
executing.
Copyright 1994 Novell, Inc. Page 3