write(S) 6 January 1993 write(S) Name write - write on a file Syntax cc ... -lc int write (fildes, buf, nbyte) int fildes; char *buf; unsigned nbyte; Description The write function attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the fildes descriptor. fildes is a file descriptor obtained from a creat(S), open(S), dup(S), fcntl(S), or pipe(S) system call. If nbyte is zero, write returns zero and has no other results if the file is a regular file. 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. If this incremented file offset is greater than the length of the file, the length of the file is set to this file offset. If the OSYNC flag of the file status flags is set and fildes refers to a regular file, a successful write does not return until the data is delivered to the underlying hardware. Upon successful return from write, the file offset is incremented by the number of bytes actually written. On a file not capable of seeking, writing always takes place starting at the current position. This value of a file offset associated with such a device is undefined. If the OAPPEND flag of the file status flags is set, the file offset is set to the end of the file prior to each write. If a write requests that more bytes be written than there is room for (for example, the ulimit or physical end of a medium), only as many bytes as there is room for are written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes returns 20. The next write of a nonzero number of bytes gives a failure return (except as noted later). On successful completion, the write function returns the actual number of bytes written to the file associated with fildes. This number is never greater than nbyte. If a call to write is interrupted by a signal before it writes any data, write returns -1 with errno set to EINTR. If write is interrupted by a signal after it successfully writes some data, either write returns -1 with errno set to EINTR, or write returns the number of bytes written. A write to a pipe or FIFO (first in first out) never returns with errno set to EINTR if it has transferred any data and nbyte is less than or equal to PIPEBUF. If the value of nbyte is greater than INTMAX, the result is implementa- tion defined. Write requests to a pipe or FIFO are handled the same as a regular file with the following exceptions: + There is no file offset associated with a pipe, hence each write request is appended to the end of the pipe. + Write requests of PIPEBUF bytes or less are not interleaved with data from other processes doing writes on the same pipe. Writes of greater than PIPEBUF bytes may have data interleaved on arbitrary boundaries with writes by other processes. This can occur whether or not the ONONBLOCK flag of the file status flags is set. + If the ONONBLOCK flag is clear, a write request may cause the process to block, but on normal completion it returns nbyte. + If the ONONBLOCK flag is set, write requests are handled differently, in the following ways: the write function does not block the process; write requests for PIPEBUF or fewer bytes either succeeds completely and returns nbyte, or returns -1 with errno set to EAGAIN. A write request for greater than PIPEBUF bytes, either transfers what it can and returns the number of bytes written, or transfers no data and returns -1 with errno set to EAGAIN. Also, if a request is greater than PIPEBUF bytes and all data previously written to the pipe has been read, write transfers at least PIPEBUF bytes. When attempting to write to a file descriptor (other than a pipe or FIFO) that supports nonblocking writes and cannot accept the data immediately: + If the ONONBLOCK flag is clear, write blocks until the data is accepted. + If the ONONBLOCK flag is set, write does not block the process. If some data can be written without blocking the process, write writes what it can and returns the number of bytes written. Otherwise, write returns -1 with errno set to EAGAIN. Upon successful completion, the write function marks for update the stctime and stmtime fields of the file, and if the file is a regular file, the SISUID and SISGID bits of the file mode may be cleared. A write to a STREAMS file can fail if an error message has been received at the stream head. In this case, errno is set to the value included in the error message. Errors The write system call fails and the file pointer remains unchanged if one or more of the following is true: [EAGAIN] The ONONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation, or an attempt was made to write to a stream that cannot accept data with the ONONBLOCK flag set. [EBADF] fildes is not a valid file descriptor open for writing. [EDEADLK] The write was going to go to sleep and cause a deadlock situation to occur. [EFBIG] An attempt was made to write a file that exceeds the pro- cess's file size limit or the maximum file size (see ulimit(S)). [EINTR] The write operation was terminated due to the receipt of a signal and either no data was transferred or the implementa- tion does not report partial transfers for this file. [EINVAL] Attempt to write to a stream linked below a multiplexer. [EIO] The implementation supports job control, the process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the process is nei- ther ignoring not blocking SIGTTOU and the process group of the process is orphaned. [ENOLCK] The system record lock table was full, so the write could not go to sleep until the blocking record lock was removed. [ENOLINK] fildes is on a remote machine and the link to that machine is no longer active. [ENOSPC] During a write to an ordinary file, there is no free space left on the device. [EPIPE] (With a SIGPIPE signal.) An attempt is made to write to a pipe or FIFO not open for reading by any process. [ERANGE] Attempt to write to a stream with nbyte outside specified minimum and maximum write range, and the minimum value is non-zero. [ENXIO] A hangup occurred on the stream being written to, a request was made to a nonexistent device, or the request was outside the capabilities of the device. Note ONONBLOCK previously described on this manual page has been replaced in XPG3 and POSIX by ONONBLOCK. ONONBLOCK caused 0 (zero) to be returned if a write request would block; ONONBLOCK causes -1 to be returned with errno set to EINTR. Diagnostics 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(S), dup(S), fcntl(S), lseek(S), open(S), pipe(S), ulimit(S) Standards conformance write is conformant with: AT&T SVID Issue 2; X/Open Portability Guide, Issue 3, 1989; Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2); IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); and NIST FIPS 151-1.