NAME

write − write on a file

SYNOPSIS

int write (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte;

DESCRIPTION

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 

Write attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the fildes.

On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer.  Upon return from write, the file pointer is incremented by the number of bytes actually written.

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

If the O_APPEND flag of the file status flags is set, the file pointer will be set to the end of the file prior to each write. 

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

Fildes is not a valid file descriptor open for writing.  ­[EBADF]

An attempt is made to write to a pipe that is not open for reading by any process.  ­[EPIPE and SIGPIPE signal]

An attempt was made to write a file that exceeds the process’s file size limit or the maximum file size.  See ulimit(2). ­[EFBIG]

Buf points outside the process’s allocated address space.  ­[EFAULT]

If a write requests that more bytes be written than there is room for (e.g., the ulimit (see ulimit(2)) or the physical end of a medium), only as many bytes as there is room for will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512  bytes will return 20. The next write of a non-zero number of bytes will give a failure return (except as noted below).

If the file being written is a pipe (or FIFO), no partial writes will be permitted.  Thus, the write will fail if a write of nbyte bytes would exceed a limit. 

If the file being written is a pipe (or FIFO) and the O_NDELAY flag of the file flag word is set, then write to a full pipe (or FIFO) will return a count of 0.  Otherwise ( O_NDELAY clear), writes to a full pipe (or FIFO) will block until space becomes available. 

RETURN VALUE

Upon successful completion the number of bytes actually written is returned.  Otherwise, −1 is returned and errno is set to indicate the error. 

SEE ALSO

creat(2), dup(2), lseek(2), open(2), pipe(2), ulimit(2). 

May 16, 1980