./_Man_NeXT_html/html2/write.2.html

Manual page for WRITE(2)

write - write output

BSD SYNOPSIS

int write(int fd, char *buf, int nbytes);

#include <sys/types.h> #include <sys/uio.h>

int writev(int fd, struct iovec *iov, int iovcnt);

POSIX SYNOPSIS

size_t write(int fd, const void *buf, size_t nbytes);

DESCRIPTION

The write function attempts to write nbytes of data to the object referenced by the descriptor fd from the buffer pointed to by buf.

With objects capable of seeking, write starts at a position given by the seek pointer associated with fd (see lseek.2 Upon return, the seek pointer for fd is incremented by the number of bytes actually written.

Objects that are not capable of seeking always write from the current position. The value of the pointer associated with such an object is undefined.

If the real user is not the super-user, then write clears the set-user-id bit on a file. This prevents penetration of system security by a user who ``captures'' a writable set-user-id file owned by the super-user.

When using non-blocking I/O on objects such as sockets that are subject to flow control, write may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible.

The writev function performs a scattered write, writing output data from the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], iov[ iovcnt - 1]. The return value of writev is the same as that for write.

The iovec structure is defined as

struct iovec {
	caddr_t	iov_base;
	int	iov_len;
};

Each iovec entry specifies the base address and length of an area in memory where data should be written from. Writev will always write all data from an area before proceeding to the next. POSIX applications should not use writev.

POSIX applications may expect the following additional behavior when attempting to write (but not writev) to a pipe or FIFO:

(1): There is no file offset associated with a pipe, hence each write request will append to the end of the pipe.
(2): Write requests of {PIPE_BUF} bytes or less are not interleaved with data from any 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 of the file status flags is set.
(3): If the O_NONBLOCK flag is clear, a write request may cause the process to block, but on normal completion if will return nbyte.
(4): If the O_NONBLOCK flag is set, write requests will be handled differently, in the following ways:

(a): The write function will not block the process.
(b): A write request for {PIPE_BUF} or fewer bytes will:

[1]: If there is sufficient space available in the pipe, transfer all the data and return the number of bytes requested.
[2]: If there is not sufficient space available in the pipe, transfer no data and return -1 with errno set to EAGAIN.

(c): A write request for more than {PIPE_BUF} bytes will either:

[1]: When at least one byte can be written, transfer what it can and return the number of bytes written. When all data previously written to the pipe has been read, it will transfer at least {PIPE_BUF} bytes.
[2]: When no data can be written, transfer no data and return -1 with errno set to EAGAIN.

POSIX applications may also expect the following when attempting to write to a file descriptor (other than a pipe or FIFO) that supports nonblocking writes and cannot accept the data immediately:

(1): If the O_NONBLOCK flag is clear, write will not block the process. If some data can be written without blocking the process, write will write what it can and return the number of bytes written. Otherwise, it will return -1 and errno will be set to EAGAIN.
(2): If the O_NONBLOCK flag is set, write will block until the data can be accepted.

RETURN VALUE

Upon successful completion the number of bytes actually written is returned. Otherwise a -1 is returned and the global variable errno is set to indicate the error.

ERRORS

Write will fail and the file pointer will remain unchanged if one or more of the following are true:

[EAGAIN]: The O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation.
[EBADF]: fd is not a valid descriptor open for writing.
[EPIPE]: An attempt is made to write to a pipe that is not open for reading by any process; or, an attempt is 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 or the maximum file size.
[EFAULT]: Part of the data to be written to the file lies outside the process's allocated address space.
[EINVAL]: The pointer associated with fd was negative.
[ENOSPC]: There is no free space remaining on the file system containing the file.
[EINTR]: The write operation was interrupted by a signal, and no data was transferred.
[EDQUOT]: The user's quota of disk blocks on the file system containing the file has been exhausted.
[EIO]: An I/O error occurred while reading from or writing to the file system; or, the process is in the background process group and is attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU signals, and the process group of the process is orphaned.
[EWOULDBLOCK]: The file was marked for non-blocking I/O, and no data could be written immediately.

In addition, writev may return one of the following errors: