write(2)write(2)Name
write, writev - write on a file
Syntax
write (fd, buf, nbytes)
int fd;
char *buf;
int nbytes;
#include <sys/types.h>
#include <sys/uio.h>
writev (fd, iov, ioveclen)
int fd;
struct iovec *iov;
int ioveclen;
Arguments
fd Descriptor returned by a or system call.
buf Points to the buffer containing the data to be written.
nbytes Positive integer defining the number of bytes to be written
from the buffer.
iov Points to a data structure of type which defines the start‐
ing location of the set of vectors forming the array and
the length of each individual vector in the array to be
written.
This structure is defined in as follows:
struct iovec {
caddr_t iov_base ;
int iov_len ;
} ;
The data type is defined in and is the recommended way to
define an address for a character value. In any case, the
address is the starting address of the set of vectors. The
integer value is the length of each individual vector, in
bytes.
ioveclen Defines the number of vectors in the array of data to be
written. Note that the numbering of the vectors begins
with 0 and proceeds through ioveclen -1.
Description
The system call attempts to write a buffer of data to a file. The sys‐
tem call attempts to write an array of buffers of data to a file.
When a file is opened to a device capable of seeking (such as a disk or
tape), the write starts at the position given by the file pointer asso‐
ciated with the file descriptor, fd. This file pointer is the offset,
in bytes, from the beginning of the file where the write is to begin.
When the file is first opened, the file pointer is set at 0. It can be
modified by the and system calls. When the call returns, the file
pointer is incremented by the number of bytes actually written.
When the file is opened to a device not capable of seeking (such as
sockets, pipes, or terminals), the write starts at the current posi‐
tion. The value of the pointer associated with such an object is unde‐
fined.
By default, does asynchronous writes. That is, after the data is writ‐
ten to a buffer cache, control returns to the program. The actual
write to a device takes place after control returns. However, if you
use an or call to open a file for synchronous writes, control does not
return to the program until after the buffer cache has been written to
the device.
If a program is using to a remote file over NFS, and an asynchronous
write error occurs, then all subsequent requests will return -1 and
errno will be set to the asynchronous error code. Also, a subsequent or
will likewise fail. The return code from should be inspected by any
program that can over NFS.
Write requests to a pipe (or FIFO) are handled the same as a regular
file, with the following exceptions:
· A file offset is not associated with a pipe. Therefore, each
request appends to the end of the pipe.
· Write requests less than or equivalent to {PIPE_BUF} bytes are not
interleaved with data from other processes doing writes on the
same pipe. Write requests greater than {PIPE_BUF} bytes can
interleave on arbitrary boundaries with writes by other processes.
· If the O_NDELAY and O_NONBLOCK flags are clear, a write can cause
the process to block, but, under normal completion, it returns
nbytes.
· If the O_NDELAY or O_NONBLOCK flag is set, the function does not
block the process. Write requests less than or equal to
{PIPE_BUF} bytes either succeed and return nbytes or -1, and errno
is set to [EWOULDBLOCK]. Write requests that exceed {PIPE_BUF}
bytes can return complete success, partial write, or no success,
and errno is to [EWOULDBLOCK].
Environment
SYSTEM V
When your program is compiled using the System V environment, and the
file was opened with the O_NDELAY flag set, a to a full pipe (or FIFO)
returns a zero (0), rather than an error, as for the ULTRIX non-System
V environment.
Differs from the System V definition in that the value nbytes is int,
rather than unsigned.
When your program is compiled using POSIX environment, EAGAIN is returned
in errno, in place of EWOULDBLOCK.
Return Values
Upon successful completion, the number of bytes actually written is
returned. Otherwise, a -1 is returned, and errno is set to indicate
the error.
Diagnostics
The system call fails and the file pointer will remain unchanged, if
any of the following is true:
[EACCESS] The file does not permit writing. NFS only.
[EBADF] The fd argument is not a valid descriptor open for writ‐
ing.
[EPIPE] An attempt was made to write to a pipe that is not open
for reading by any process.
[EPIPE] An attempt was made to write to a socket of type
SOCK_STREAM that is not connected to a peer socket.
[EFBIG] An attempt was made to write a file that exceeds the
process's file size limit, set by or the maximum file
size (approximately 2 Gigabytes).
[EFAULT] Part of the array pointed to by iov or data to be writ‐
ten to the file points outside the process's allocated
address space.
[EWOULDBLOCK] The O_NDELAY or O_NONBLOCK flag is set for the file
descriptor and the process would be delayed in the write
operation.
[ENOSPC] There is no free space remaining on the file system con‐
taining the file.
[EDQUOT] The user's quota of disk blocks on the file system con‐
taining the file has been exhausted.
[EIO] An I/O error occurred while reading from or writing to
the file system.
[EINTR] The write operation was interrupted, no data was trans‐
ferred.
[EINVAL] The nbytes argument is negative.
[EROFS] The file is on a read-only file system. NFS only.
[ESTALE] The fd argument is invalid because the file referred to
by that file handle no longer exists or has been
revoked. NFS only.
[ETIMEDOUT] A write operation failed because the server did not
properly respond after a period of time that is depen‐
dent on the options. NFS only.
See Alsoclose(2), creat(2), dup(2), fcntl(2), fsync(2), lseek(2), open(2),
pipe(2), socket(2)write(2)