pwrite(S)
pwrite, pwrite64 --
atomic position and write
Synopsis
#include <unistd.h>
ssize_t pwrite(int fd, const void *buf, size_t nbytes, off_t offset);
ssize_t pwrite64(int fd, const void *buf, size_t nbytes, off64_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.
Note that when pwrite is called on a file that was opened with the
open(S)
system call's O_APPEND flag,
the offset argument to pwrite is ignored; the data
is written to the end of the file.
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 fails and sets errno to:
EFBIG-
The file is a regular file, nbyte is greater than 0, and
the starting position is greater than or equal to the offset
maximum established in the open file descriptor associated
with fd.
There is no data transfer.
In the following conditions, pwrite and pwrite64
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.
EBADF-
fd
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(S)
and
ulimit(S)).
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.
fd 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-
fd 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-
fd 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-
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-
fd
is associated with a pipe or fifo.
ENOSYS-
The device for fstype does not support lseek.
References
creat(S),
dup(S),
fcntl(S),
intro(S),
lseek(S),
open(S),
pread(S),
write(S)
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.
Considerations for large file support
pwrite64 supports large files, but is otherwise identical
to pwrite.
For details on programming for large file capable applications, see
``Large File Support''
on intro(S).
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005