Content-type: text/html
write, pwrite, writev - Write to a file
#include <unistd.h>
ssize_t write(
int filedes,
const void *buffer,
size_t nbytes);
ssize_t pwrite(
int filedes,
const void *buffer,
size_t nbytes);
off_t offset);
#include <sys/uio.h>
ssize_t writev(
int filedes,
const struct iovec *iov,
int iov_count);
The following version of the writev() function does not conform to current standards and is supported only for backward compatibility:
#include <sys/types.h> #include <sys/uio.h>
ssize_t writev(
int filedes ,
struct iovec *iov,
int iov_count );
Interfaces documented on this reference page conform to industry standards as follows:
write(): XPG4, XPG4-UNIX
pwrite(): POSIX.1c
writev(): XPG4-UNIX
Refer to the standards(5) reference page for more information about industry standards and associated tags.
Identifies the file to which the data is to be written.
Points to the buffer containing the data to be
written.
Specifies the number of bytes to write to the file
associated with the filedes parameter.
Specifies the desired start position inside the file
associated with the filedes parameter.
Points to an array of iovec structures,
which identifies the buffers containing the data to be written. The
iovec structure is defined in the sys/uio.h header file
and contains the following members:
void iov_base;
size_t iov_len;
The write() function attempts to write nbytes of data to the file associated with the filedes parameter from the buffer pointed to by the buffer parameter.
If the nbytes parameter is 0 (zero), the write() function returns 0 (zero) and has no other results if the file is a regular file.
[XPG4-UNIX] If filedes refers to a socket, write() is equivalent to send() with no flags set.
The pwrite() function performs the same action as write(), except that it writes into a given position in the file (specified by the offset parameter) without changing the file pointer.
The writev() function performs the same action as the write() function, but gathers the output data from the iov_count buffers specified by the array of iovec structures pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory from which data should be written. The iov_count parameter is valid if greater than 0 (zero) and less than or equal to IOV_MAX, which is defined in the limits.h header file. The writev() function always writes a complete area before proceeding to the next.
If filedes refers to a regular file and all of the iov_len members in the array pointed to by iov are 0 (zero), writev() returns 0 and has no other effect.
With regular files and devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. If this incremented file pointer is greater than the length of the file, the length of the file is set to this file offset. Upon return from the write() or pwrite() function, the file pointer increments by the number of bytes actually written.
If the O_SYNC flag of the file status flags is set and the filedes parameter refers to a regular file, a successful write() or pwrite() function does not return until the data is delivered to the underlying hardware (as described in the open() function).
With devices incapable of seeking, writing always takes place starting at the current position. The value of a file pointer associated with such a device is undefined.
If the O_APPEND flag of the file status is set, the file offset is set to the end of the file prior to each write and no intervening file modification operation occurs between changing the file offset and the write operation.
If a write() or pwrite() requests that more bytes be written than there is room for (for example, the ulimit() or the physical end of a medium), only as many bytes as there is room for are written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes returns 20. The next write of a nonzero number of bytes will give a failure return (except as noted below). [XPG4-UNIX] Also, a SIGXFSZ signal is generated for the process.
If a write() or pwrite() function is interrupted by a signal before it writes any data, it returns -1 with errno set to [EINTR].
If a write() or pwrite() function is interrupted by a signal after it successfully writes some data, it returns the number of bytes written.
After a write() or pwrite() to a regular file has successfully returned: Any successful read() from each byte position in the file that was modified by that write returns the data specified by the write() or pwrite() for that position until such byte positions are again modified. Any subsequent successful write() or pwrite() to the same byte position in the file overwrites that file data.
Write requests to a pipe (or FIFO) are handled the same as a regular file with the following exceptions: There is no file offset associated with a pipe; hence each write() or pwrite() request appends to the end of the pipe. If the size of the write() or pwrite() request is less than or equal to the value of the PIPE_BUF system variable, the write() or pwrite() function is guaranteed to be atomic. The data is not interleaved with data from other processes doing writes on the same pipe. Writes of greater than PIPE_BUF bytes can have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not O_NONBLOCK is set.
When attempting to write to a file descriptor (other than a pipe or a FIFO) that supports nonblocking writes and cannot accept data immediately, the write() and pwrite() functions behave as follows: If O_NONBLOCK is clear, the function blocks until the data can be accepted.
[Digital] When attempting to write to a regular file with enforcement mode record locking enabled, and all or part of the region to be written is currently locked by another process, the write() and pwrite() functions behave as follows: If O_NDELAY and O_NONBLOCK are clear (the default), the calling process blocks until all the blocking locks are removed, or the function is terminated by a signal. If O_NDELAY or O_NONBLOCK is set, then the function returns -1 and sets errno to [EAGAIN].
Upon successful completion, the write() or pwrite() function marks the st_ctime and st_mtime fields of the file for update, and clears its set-user ID and set-group ID attributes if the file is a regular file.
The fcntl() function provides more information about record locks.
[XPG4-UNIX] When writing to a STREAM, data messages are created with a priority band of 0 (zero). When writing to a STREAM that is not a pipe or FIFO, the write() and pwrite() functions behave as follows: If O_NONBLOCK is clear and the STREAM cannot accept data (the STREAM write queue is full due to internal flow control conditions), the function blocks until data can be accepted.
[XPG4-UNIX] In addition, write(), pwrite() and writev() will fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of write(), pwrite(), or writev() but reflects the prior error.
[Digital] The write(), pwrite(), and writev() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended.
[Digital] When debugging a module that includes the writev() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ewritev to refer to the writev() call. See standards(5) for information on when the _XOPEN_SOURCE_EXTENDED macro is defined.
When a read(), pread(), write(), or pwrite() system call on a pipe is interrupted by a signal and no bytes have been transferred through the pipe, a value of -1 is returned and errno is set to [EINTR]. This behavior is different from previous releases, when both read() and write() either restarted the transfer or set errno to [EINTR], depending on the setting of the SA_RESTART flag for the interrupting signal.
As a result of this change, applications must now either handle the [EINTR] return or block any expected signals for the duration of the read(), pread(), write(), or pwrite() operation.
Upon successful completion, the write() or pwrite() function returns the number of bytes actually written to the file associated with the filedes parameter. This number is never be greater than nbytes. Otherwise, a value of -1 is returned and errno is set to indicate the error.
Upon successful completion, the writev() function returns the number of bytes that were actually written. Otherwise, a value of -1 is returned, the file-pointer remains unchanged, and errno is set to indicate the error.
Refer to mtio(7) for information on enabling and disabling "early warning" EOT.
Note: A partial write is a request which spans the end of a partition.
The write(), pwrite(), and writev() functions set errno to the specified values for the following conditions: The O_NONBLOCK flag is set on this file and the process would be delayed in the write operation.
In addition, the pwrite() function fails and the file pointer remains unchanged if the following is true: The file specified by fildes is associated with a pipe or FIFO.
[XPG4-UNIX] A write to a STREAMS file can fail if an error message has been received at the STREAM head. In this case, errno is set to the value included in the error message.
For NFS file access, if the write(), pwrite(), or writev() function fails, errno may also be set to one of the following values: [Digital] For filesystems mounted with the nfsv2 option, the process attempted to write beyond the 2 gigabyte boundary. [Digital] The named file is a directory and write access is requested. [Digital] Indicates insufficient resources, such as buffers, to complete the call. Typically, a call used with sockets has failed due to a shortage of message or send/receive buffer space. [Digital] The named file resides on a read-only file system and write access is required. [Digital] Indicates a stale NFS file handle. An opened file was deleted by the server or another client; a client cannot open a file because the server has unmounted or unexported the remote directory; or the directory that contains an opened file was either unmounted or unexported by the server.
If the write(), pwrite(), or writev() function fails while in the System V habitat, errno may also be set to one of the following errors: [Digital] A write to a pipe (FIFO) of {PIPE_BUF} bytes or less is requested, O_NONBLOCK is set, and less than nbytes bytes of free space is available.
Functions: open(2), fcntl(2), lseek(2), mtio(7), open(2), getmsg(2), lockf(3), pipe(2), poll(2), select(2) ulimit(3)
Standards: standards(5) delim off