writev()
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.
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:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |