writev() write to file from vector of buffers	Function
	SYNOPSIS DESCRIPTION PARAMETERS RETURN VALUES CONFORMANCE MULTITHREAD SAFETY LEVEL PORTING ISSUES AVAILABILITY SEE ALSO

---

SYNOPSIS

#include <unistd.h>

#include <sys/uio.h>

ssize_t writev(int fildes, const struct iovec *iov, int iovcnt);

---

DESCRIPTION

The write() function attempts to write data to the specified file descriptor from the specified vector of buffers. The iovec structure contains two fields: iov_base, which specifies the base address for the buffer, and iov_len, which specifies the size of the buffer. Each buffer is filled completely before proceeding to the next.

On a regular file or other file capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file offset associated with the specified file descriptor. Before successful return from writev(), the file offset is incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length of the file, the length of the file is set to this file offset.

On a file not capable of seeking, writing always takes place starting at the current position. The value of a file offset associated with such a device is undefined.

If the O_APPEND flag is set for the file descriptor, 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 writev() requests more bytes be written than there is room for (for example, the physical end of the medium), only as many bytes as there is room for are written.

If writev() is interrupted by a signal before it writes any data, it returns -1 with errno set to EINTR. If writev() is interrupted by a signal after it successfully writes some data, it returns the number of bytes written.

Writes larger than SSIZE_MAX are unsupported.

After a writev() 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 writev() for that position until such byte positions are again modified.
• Any subsequent writev() to the same byte position in the file overwrites that file data.

Write requests to a pipe or FIFO is handled the same as a regular file with the following exceptions:

• There is no file offset associated with a pipe, hence each write request appends to the end of the pipe.
• Write requests of PIPE_BUF bytes or less are not interleaved with data from other processes doing writes on the same pipe. Writes of greater than PIPE_BUF bytes may have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag is set.
• If the O_NONBLOCK flag is clear, a write request may cause the thread to block, but on normal completion, it returns the request size, indicating that all data has been written.
• If the O_NONBLOCK flag is set, writev() requests are handled as follows:

  • The writev() function does not block the thread.
  • For a write request of PIPE_BUF or fewer bytes, if there is sufficient space available in the pipe, writev() transfers all the data and returns the number of bytes requested. Otherwise, writev() transfers no data and returns -1 with errno set to EAGAIN.
  • For a write request of more than PIPE_BUF bytes, when at least one byte can be written, as much data as possible is transferred, and the number of bytes written is returned. Otherwise, no data is transferred, and writev() returns -1 with errno set to EAGAIN.

When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes and cannot accept data immediately:

• If the O_NONBLOCK flag is clear, writev() blocks the calling thread until data can be accepted.
• If the O_NONBLOCK flag is set, writev() does not block the process. If some data can be written without blocking the process, writev() writes what it can and return the number of bytes written. Otherwise, it returns -1 with errno set to EAGAIN.

If the O_SYNC bit has been set, write I/O operations on the file descriptor complete only after the data has been flushed to the mass storage device.

Upon successful completion, writev() marks for update the st_ctime and st_mtime fields of the file.

---

PARAMETERS

fildes 

Is the file descriptor of an open file to write to.

iov 

Points to an array of iovec structures defining buffers to be written out.

iovcnt 

Is the number of entries in the iov array. This must be greater than 0 and less than or equal to IOV_MAX.

---

RETURN VALUES

If successful, writev() returns the number of bytes written to the open file descriptor fildes. The number of bytes written never exceeds nbyte. Otherwise, writev() returns -1 and sets errno to one of the following values:

EAGAIN 

The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the writev() operation.

EBADF 

The fildes parameter is not a valid file descriptor open for writing.

EFAULT 

The buf parameter is not a valid pointer.

EFAULT 

buf points outside the allocated address space of the process.

EFBIG 

An attempt is made to write a file that exceeds the file size limit of the process.

EFBIG 

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 fildes.

EINTR 

A signal interrupted the call to writev().

EINVAL 

The iovcnt parameter is less than 1 or greater than IOV_MAX.

The sum of the iov_len values in the iov array overflowed an ssize_t.

EIO 

A physical I/O error has occurred.

ENOMEM 

Insufficient memory exists to complete the request.

ENOSPC 

There is no more free space on the device that fildes refers to.

ENXIO 

A request was made of a non-existent device, or the request was outside the capabilities of the device.

EPIPE 

An attempt is made to write to a pipe or FIFO that is not open for reading by any process, or that has only one end open. A SIGPIPE is also sent to the thread.

---

CONFORMANCE

UNIX 98, with exceptions.

---

MULTITHREAD SAFETY LEVEL

MT-Safe.

---

PORTING ISSUES

Refer to File Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide for a detailed discussion of file handling, including a discussion of text mode and binary mode for files.

The test which causes the EFBIG error condition to be returned can be disabled by using the _NutConf() function to turn off the _NC_SET_FULL_LFS_SEMANTICS flag.

---

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

---

SEE ALSO

Functions:

creat(), dup(), dup2(), fcntl(), ioctl(), open(), pipe(), read(), readv(), socket(), write()

---

PTC MKS Toolkit 10.4 Documentation Build 39.