write(2) write(2)NAME write, writev - write on a file SYNOPSIS int write(fildes, buf, nbytes) int fildes; char *buf; unsigned nbytes; #include <sys/types.h> #include <sys/uio.h> int writev(fildes, iov, ioveclen) int fildes; struct iovec *iov; int ioveclen; DESCRIPTION write attempts to write nbytes bytes from the buffer pointed to by buf to the file associated with fildes. writev per- forms the same action, but gathers the output data from the iovlen buffers specified by the members of the iovec array: iov[0], iov[1], and so on. The file descriptor fildes is obtained from a creat, open, dup, fcntl, pipe, or socket system call. On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. On return from write, the file pointer is incre- mented by the number of bytes actually written. On devices incapable of seeking, writing always starts at the current position. The value of a file pointer associat- ed with such a device is undefined. If the O_APPEND flag of the file status flags is set, the file pointer is set to the end of the file prior to each write. When writing to a pipe (or FIFO), write requests of PIPE_BUF bytes or less are not interleaved with data from other processes writing to the same pipe. Writes of greater than PIPE_BUF bytes may have data interleaved, on arbitrary boun- daries, with writes by other processes. RETURN VALUE On successful completion, the number of bytes actually writ- ten is returned. If the process compatibility flag COMPAT_SYSCALL is set (see setcompat(2)), as in the POSIX environment, and write-interrupted by a signal after suc- cessfully writing some data, it returns the number of bytes April, 1990 1
write(2) write(2)written. If nybytes is 0, write returns 0 and have no other result. Otherwise, -1 is returned and errno is set to indi- cate the error. ERRORS When attempting to write to a stream when buffer space is not currently available and if O_NDELAY or O_NONBLOCK is set, the write returns the number of bytes written before there were no buffers available. If O_NDELAY and O_NONBLOCK are clear, the write blocks until buffers become available. write fails and the file pointer remains unchanged if one or more of the following are true: [EIO] A physical I/O error has occurred or the process is in a background process group and is attempting to write to its controlling terminal (see termio(7P)). TOSTOP is set, the process is not blocking or ignoring SIGTTOU. The process group of the processes is orphaned or the write was to an open device after a modem disconnect or hangup occurred. [ENXIO] The device associated with the file descriptor is a block device file or character device file and the value of the file pointer is out of range. [EBADF] The file descriptor, fildes, is not valid and open for writing. [EPIPE] and SIGPIPE signal An attempt is made to write to a pipe that is not open for reading by any process. [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See ulimit(2). [EFAULT] Part of iov or data to be written to the file points outside the allocated address space of the process. [EFAULT] buf points outside the allocated address space of the process. [EINTR] A signal was caught during the write system call. [ENOSPC] Not enough space was left on the device containing the file. If the number of bytes specified in a write request exceeds the available space limit, that is, the per-process file 2 April, 1990
write(2) write(2)size (see ulimit(2)), or exceeds the size of the physical media, only as many bytes for which there is room will be written. For example, suppose there is space in a file for an additional 20 bytes before reaching a limit. A write of 512 bytes returns 20. The next write of a nonzero number of bytes gives a failure return with the following exceptions: If the file being written is a pipe (or FIFO) and if the O_NDELAY flag of the file-flag word is set, then writing to a full pipe (or FIFO) returns a count of 0. if O_NDELAY is clear, writes to a full pipe (or FIFO) blocks until space becomes available. If the file being written is a pipe (or FIFO) and if O_NONBLOCK is set, write requests for PIPE_BUF or fewer bytes either succeed completely or return -1 and set errno to EAGAIN. if O_NONBLOCK is clear, a write request may block until space is available. When writing to a file descriptor (other than a pipe or FIFO) that supports nonblocking writes and cannot accept data immediately and if O_NONBLOCK is set, write writes what data it can, returning -1 and setting errno to EAGAIN. If O_NONBLOCK is clear, write blocks until the data is accept- ed. SEE ALSO creat(2), dup(2), fcntl(2), lseek(2), open(2), pipe(2), select(2N), socket(2N), ulimit(2). April, 1990 3