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).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004