pwrite() — Write data on a file or socket without file pointer change
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
Single UNIX Specification, Version 2 |
both | OS/390 V2R10 |
Format
#define _XOPEN_SOURCE 500
#include <unistd.h>
ssize_t pwrite(int fildes, const void *buf, size_t nbyte, off_t offset);
General description
The pwrite() function performs the same action as write(), except that it writes into a given position without changing the file pointer.
The first three arguments to pwrite() are the same as write() with the addition of a fourth argument offset for the desired position inside the file.
Returned value
If successful, pwrite() returns the number of bytes actually written to the file associated with fildes. This number will never be greater than nbyte.
If unsuccessful, pwrite() returns -1 and sets errno to one of the following values:
- Error Code
- Description
- EAGAIN
- Resources temporarily unavailable. Subsequent requests may complete normally.
- EBADF
- fildes is not a valid file or socket descriptor.
- ECONNRESET
- A connection was forcibly closed by a peer.
- EDESTADDRREQ
- The socket is not connection-oriented and no peer address is set.
- EFAULT
- Using the buf and nbyte parameters would result in an attempt to access storage outside the caller's address space.
- EFBIG
- An attempt was made to write a file that exceeds the system-established
maximum file size or the process's file size limit supported by the
implementation.
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 description associated with fields.
- EINTR
- pwrite() was interrupted by a signal before it had written any output.
- EINVAL
- The request is invalid or not supported. The STREAM or multiplexer
referenced by fildes is linked (directly
or indirectly) downstream from a multiplexer.
The offset argument is invalid. The value is negative.
- EIO
- The process is in a background process group and is attempting to write to its controlling terminal, but TOSTOP (defined in the termios.h header file) is set, the process is neither ignoring nor blocking SIGTTOU signals, and the process group of the process is orphaned. An I/O error occurred.
- EMSGSIZE
- The message was too big to be sent as a single datagram.
- ENOBUFS
- Buffer space is not available to send the message.
- ENOSPC
- There is no available space left on the output device.
- ENOTCONN
- The socket is not connected.
- ENXIO
- A hang-up occurred on the STREAM being written to.
- EPIPE
- pwrite() is trying to write to a pipe that is not open for reading by any other process. This error also generates a SIGPIPE signal. For a connected stream socket the connection to the peer socket has been lost.
- ERANGE
- The transfer request size was outside the range supported by the STREAMS file associated with fildes.
- ESPIPE
- fildes is associated with a pipe or FIFO.
- EWOULDBLOCK
- socket is in nonblocking mode and no data buffers are available or the SO_SNDTIMEO timeout value was reached before buffers became available.