writev()

Write bytes to a file

Synopsis:

#include <sys/uio.h>

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

Arguments:

fildes: 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: 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, fildes, 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