writev()

Updated: October 28, 2024

Write bytes to a file

Synopsis:

#include <sys/uio.h>

ssize_t writev( int filedes,
                const iov_t* iov,
                int nparts );

Arguments:

filedes
The file descriptor for the file you want to write in.
iov
An array of iov_t objects that contain the data that you want to write. The combined size (i.e., the sum of the length values) of the objects must not exceed SSIZE_MAX - sizeof(io_write_t) (see <limits.h>), or the function fails and sets errno. If the size is greater than SSIZE_MAX - sizeof(io_write_t) but less than or equal to SSIZE_MAX, errno is set to EOVERFLOW. If the size is greater than SSIZE_MAX, errno is set to EINVAL.
nparts
The number of entries in the iov array. The maximum number of entries is UIO_MAXIOV.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The writev() function performs the same action as write(), but gathers the output data from the nparts buffers specified by the members of the iov array: iov[0], iov[1], … iov[nparts-1].

For writev(), the iov_t structure contains the following members:

iov_base, iov_base_const
Base address of a memory area from which data should be written.
iov_len
The length of the memory area.

The writev() function always writes a complete area before proceeding to the next.

Note: Note that writev() ignores advisory locks that may have been set by the fcntl() function.

If writev() is interrupted by a signal before it has written any data, it returns -1 and sets errno to EINTR. However, if writev() is interrupted by a signal after it has successfully written some data, it will return the number of bytes written.

For more details, see the write() function.

Returns:

The number of bytes written, or -1 if an error occurs (errno is set).

Errors:

EAGAIN
The O_NONBLOCK flag is set for the file descriptor and the write operation would block.
EBADF
The file descriptor, filedes, isn't a valid file descriptor open for writing.
EFBIG
The file is a regular file, the combined size of the iov_t objects is greater than 0, and the starting position is greater than or equal to the offset maximum associated with the file.
EINTR
The write operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file doesn't report partial transfers.
EINVAL
The nparts argument is less than or equal to 0, or greater than UIO_MAXIOV. Or, an attempt was made to write a number bytes that exceeds the allowable limit.
EIO
A physical I/O error occurred (for example, a bad block on a disk). The precise meaning is device-dependent.
ENOSPC
There is no free space remaining on the device containing the file.
ENOSYS
The write() function isn't implemented for the filesystem specified by filedes.
EOVERFLOW
An attempt was made to write a number of bytes that when added to the size of the write message structure exceeds the allowable limit.
EPIPE
An attempt was made to write to a pipe (or FIFO) that isn't open for reading by any process. A SIGPIPE signal is also sent to the process.

Classification:

POSIX 1003.1 XSI

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes