pwrite(2)

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(2) 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(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.
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(2), dup(2), fcntl(2), intro(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.

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(2).