*** UNIX MANUAL PAGE BROWSER ***

write(2) System Calls Manual write(2) NAME write, pwrite, writev - Write to a file SYNOPSIS #include <unistd.h> ssize_t write( int filedes, const void *buffer, size_t nbytes); ssize_t pwrite( int filedes, const void *buffer, size_t nbytes); off_t offset); #include <sys/uio.h> ssize_t writev( int filedes, const struct iovec *iov, int iov_count); The following version of the writev() function does not conform to cur- rent standards and is supported only for backward compatibility: #include <sys/types.h> #include <sys/uio.h> ssize_t writev( int filedes , struct iovec *iov, int iov_count ); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: write(): XPG4, XPG4-UNIX pwrite(): POSIX.1c writev(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Identifies the file to which the data is to be written. Points to the buffer containing the data to be written. Specifies the number of bytes to write to the file associated with the filedes parameter. Specifies the desired start position inside the file associated with the filedes parameter. Points to an array of iovec structures, which identifies the buffers containing the data to be written. The iovec structure is defined in the sys/uio.h header file and contains the fol- lowing members: void iov_base; size_t iov_len; [Digital] The backward-compatible version of the iovec struc- ture contains the following members: caddr_t iov_base; int iov_len; Specifies the number of iovec structures pointed to by the iov parameter. DESCRIPTION The write() function attempts to write nbytes of data to the file asso- ciated with the filedes parameter from the buffer pointed to by the buffer parameter. If the nbytes parameter is 0 (zero), the write() function returns 0 (zero) and has no other results if the file is a regular file. [XPG4-UNIX] If filedes refers to a socket, write() is equivalent to send() with no flags set. The pwrite() function performs the same action as write(), except that it writes into a given position in the file (specified by the offset parameter) without changing the file pointer. The writev() function performs the same action as the write() function, but gathers the output data from the iov_count buffers specified by the array of iovec structures pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory from which data should be written. The iov_count parameter is valid if greater than 0 (zero) and less than or equal to IOV_MAX, which is de- fined in the limits.h header file. The writev() function always writes a complete area before proceeding to the next. If filedes refers to a regular file and all of the iov_len members in the array pointed to by iov are 0 (zero), writev() returns 0 and has no other effect. With regular files and devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. If this incremented file pointer is greater than the length of the file, the length of the file is set to this file offset. Upon return from the write() or pwrite() function, the file pointer incre- ments by the number of bytes actually written. If the O_SYNC flag of the file status flags is set and the filedes pa- rameter refers to a regular file, a successful write() or pwrite() function does not return until the data is delivered to the underlying hardware (as described in the open() function). With 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 is set, the file offset is set to the end of the file prior to each write and no intervening file mod- ification operation occurs between changing the file offset and the write operation. If a write() or pwrite() requests that more bytes be written than there is room for (for example, the ulimit() or the physical end of a medium), only as many bytes as there is room for are written. For ex- ample, suppose there is space for 20 bytes more in a file before reach- ing a limit. A write of 512 bytes returns 20. The next write of a nonzero number of bytes will give a failure return (except as noted be- low). [XPG4-UNIX] Also, a SIGXFSZ signal is generated for the process. If a write() or pwrite() function is interrupted by a signal before it writes any data, it returns -1 with errno set to [EINTR]. If a write() or pwrite() function is interrupted by a signal after it successfully writes some data, it returns the number of bytes written. After a write() or pwrite() to a regular file has successfully re- turned: Any successful read() from each byte position in the file that was modified by that write returns the data specified by the write() or pwrite() for that position until such byte positions are again modi- fied. Any subsequent successful write() or pwrite() to the same byte position in the file overwrites that file data. 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() or pwrite() request appends to the end of the pipe. If the size of the write() or pwrite() request is less than or equal to the value of the PIPE_BUF system variable, the write() or pwrite() function is guaranteed to be atomic. The data is not inter- leaved with data from other processes doing writes on the same pipe. Writes of greater than PIPE_BUF bytes can have data interleaved, on ar- bitrary boundaries, with writes by other processes, whether or not O_NONBLOCK is set. [Digital] This also applies whether or not O_NDELAY is set. If O_NONBLOCK is clear, a write() or pwrite() request to a full pipe causes the process to block until enough space becomes available to handle the entire request. [Digital] This also applies if O_NDELAY is clear. If the O_NONBLOCK flag is set, write() or pwrite() requests are handled differently in the following ways: the function does block the process; requests for PIPE_BUF or fewer bytes either succeed completely and return nbytes, or return -1 and set errno to [EA- GAIN]. A request for greater than PIPE_BUF bytes either trans- fers 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 PIPE_BUF bytes and all data previously written to the pipe has been read, write() or pwrite() transfers at least PIPE_BUF bytes. [Digital] This also applies if O_NDELAY is set. When attempting to write to a file descriptor (other than a pipe or a FIFO) that supports nonblocking writes and cannot accept data immedi- ately, the write() and pwrite() functions behave as follows: If O_NON- BLOCK is clear, the function blocks until the data can be accepted. [Digital] This also applies if O_NDELAY is clear. If O_NON- BLOCK is set, the function does not block the process. Instead, if some data can be written without blocking the process, it writes what it can and returns the number of bytes written. Oth- erwise, it returns -1 and errno is set to [EAGAIN]. [Digital] This also applies if O_NDELAY is set, except 0 (zero) is returned. [Digital] When attempting to write to a regular file with enforcement mode record locking enabled, and all or part of the region to be writ- ten is currently locked by another process, the write() and pwrite() functions behave as follows: If O_NDELAY and O_NONBLOCK are clear (the default), the calling process blocks until all the blocking locks are removed, or the function is terminated by a signal. If O_NDELAY or O_NONBLOCK is set, then the function returns -1 and sets errno to [EA- GAIN]. Upon successful completion, the write() or pwrite() function marks the st_ctime and st_mtime fields of the file for update, and clears its set-user ID and set-group ID attributes if the file is a regular file. The fcntl() function provides more information about record locks. Writing Data to STREAMS Files [XPG4-UNIX] For STREAMS files, the operation of write() and pwrite() is determined by the values of the minimum and maximum nbytes range ("packet size") accepted by the STREAM. These values are contained in the topmost STREAM module. Unless the user pushes the topmost module, these values cannot be set or tested from user level (see I_PUSH on the streamio(7)) reference page). If nbytes falls within the packet size range, nbytes bytes are written. If nbytes does not fall within the range and the minimum packet size value is 0 (zero), write() or pwrite() breaks the buffer into maximum packet size segments prior to sending the data downstream (the last segment may contain less than the maximum packet size). If nbytes does not fall within the range and the minimum value is nonzero, write() or pwrite() fails with errno set to [ERANGE]. Writing a zero-length buffer (nbytes is 0) sends 0 bytes with 0 returned. However, writing a zero-length buffer to a STREAMS- based pipe or FIFO sends no message and 0 is returned. The process may issue I_SWROPT ioctl() to enable zero-length messages to be sent across the pipe or FIFO. [XPG4-UNIX] When writing to a STREAM, data messages are created with a priority band of 0 (zero). When writing to a STREAM that is not a pipe or FIFO, the write() and pwrite() functions behave as follows: If O_NONBLOCK is clear and the STREAM cannot accept data (the STREAM write queue is full due to internal flow control conditions), the function blocks until data can be accepted. [Digital] This also applies if O_NDELAY is clear. If O_NON- BLOCK is set and the STREAM cannot accept data, the function re- turns -1 and sets errno to [EAGAIN]. [Digital] This also applies if O_NDELAY is set. If O_NONBLOCK is set and part of the buffer has been written when a condition in which the STREAM can not accept additional data occurs, the function terminates and returns the number of bytes written. [Digital] This also applies if O_NDELAY is set. [XPG4-UNIX] In addition, write(), pwrite() and writev() will fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of write(), pwrite(), or writev() but reflects the prior error. NOTES [Digital] The write(), pwrite(), and writev() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended. [Digital] When debugging a module that includes the writev() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ewritev to refer to the writev() call. See standards(5) for information on when the _XOPEN_SOURCE_EXTENDED macro is defined. When a read(), pread(), write(), or pwrite() system call on a pipe is interrupted by a signal and no bytes have been transferred through the pipe, a value of -1 is returned and errno is set to [EINTR]. This be- havior is different from previous releases, when both read() and write() either restarted the transfer or set errno to [EINTR], depend- ing on the setting of the SA_RESTART flag for the interrupting signal. As a result of this change, applications must now either handle the [EINTR] return or block any expected signals for the duration of the read(), pread(), write(), or pwrite() operation. RETURN VALUES Upon successful completion, the write() or pwrite() function returns the number of bytes actually written to the file associated with the filedes parameter. This number is never be greater than nbytes. Oth- erwise, a value of -1 is returned and errno is set to indicate the er- ror. Upon successful completion, the writev() function returns the number of bytes that were actually written. Otherwise, a value of -1 is re- turned, the file-pointer remains unchanged, and errno is set to indi- cate the error. End-of-Media Handling for Tapes If writing goes beyond the "early warning" EOT indicator while this in- dicator is disabled, the write(), pwrite(), and writev() functions will return the number of bytes actually written and placed into the buffer. The write(), pwrite(), and writev() functions return a value of -1, if: Attempting to write past the "real EOT". Attempting to write past "early warning" EOT indicator while this indicator is enabled. Refer to mtio(7) for information on enabling and disabling "early warn- ing" EOT. End-of-Media Handling for Disks Disk end-of-media handling is POSIX-compliant. Attempting to write at or beyond the end of a partition returns a value of -1. A partial write returns the number of bytes actually written. Note: A partial write is a request which spans the end of a partition. ERRORS The write(), pwrite(), and writev() functions set errno to the speci- fied values for the following conditions: The O_NONBLOCK flag is set on this file and the process would be delayed in the write operation. [Digital] An attempt was made to write to a STREAM that can not accept data with either the O_NDELAY or O_NONBLOCK flag set. [Digital] An enforcement mode record lock is outstanding in the portion of the file that is to be written. The filedes parame- ter does not specify a valid file descriptor open for writing. [Digital] Enforced record locking is enabled, O_NDELAY is clear, and a deadlock condition is detected. [Digital] The write has failed because the user's disk block quota is ex- hausted. [Digital] The buffer parameter or part of the iov pa- rameter points to a location outside of the allocated address space of the process. An attempt was made to write a file that exceeds the maximum file size. A write() or pwrite() on a pipe is interrupted by a signal and no bytes have been transferred through the pipe. [XPG4-UNIX] The STREAM or multiplexer refer- enced by filedes is linked (directly or indirectly) downstream from a multiplexer. [XPG4-UNIX] The iov_count parameter value was less than or equal to 0 or greater than IOV_MAX. [XPG4-UNIX] The sum of the iov_len values in the iov array would overflow an ssize_t. [Digital] The file position pointer associated with the filedes parameter was negative. [Digital] One of the iov_len values in the iov array was nega- tive or the sum overflowed a 32-bit integer. [XPG4-UNIX] A physical I/O error has occurred. These errors do not always oc- cur with the associated function, but can occur with the subse- quent function. [Digital] The file has enforcement mode file locking set and allocating another locked region would exceed the configurable system limit of NLOCK_RECORD. [XPG4-UNIX] No free space is left on the file system containing the file. [Digital] An attempt was made to write past the "early warning" EOT while this indicator was enabled. [Digital] An attempt was made to write at or beyond the end of a partition. [XPG4-UNIX] A hangup occurred on the STREAM being written to. The device associated with file descriptor (the filedes parame- ter) is a block special device or character special file and the file pointer is out of range. [Digital] An attempt was made to write to a socket or type SOCK_STREAM that is not connected to a peer socket. [XPG4-UNIX] An attempt was made to write to a pipe that has only one end open. An attempt was made to write to a pipe or FIFO that is not opened for reading by any process. A SIGPIPE signal is sent to the process. [XPG4-UNIX] The transfer request size was outside the range supported by the STREAMS file associated with filedes. In addition, the pwrite() function fails and the file pointer remains unchanged if the following is true: The file specified by fildes is as- sociated with a pipe or FIFO. [XPG4-UNIX] 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. For NFS file access, if the write(), pwrite(), or writev() function fails, errno may also be set to one of the following values: [Digi- tal] For filesystems mounted with the nfsv2 option, the process at- tempted to write beyond the 2 gigabyte boundary. [Digital] The named file is a directory and write access is requested. [Digital] Indicates insufficient resources, such as buffers, to complete the call. Typi- cally, a call used with sockets has failed due to a shortage of message or send/receive buffer space. [Digital] The named file resides on a read-only file system and write access is required. [Digital] Indi- cates a stale NFS file handle. An opened file was deleted by the server or another client; a client cannot open a file because the server has unmounted or unexported the remote directory; or the direc- tory that contains an opened file was either unmounted or unexported by the server. If the write(), pwrite(), or writev() function fails while in the Sys- tem V habitat, errno may also be set to one of the following errors: [Digital] A write to a pipe (FIFO) of {PIPE_BUF} bytes or less is re- quested, O_NONBLOCK is set, and less than nbytes bytes of free space is available. [Digital] Enforced record locking was enabled, O_NDELAY or O_NONBLOCK was set and there were record-locks on the file, or O_NONBLOCK was set, and data cannot be accepted immediately. [Digital] The sum of the iov_len values in the iov array over- flowed an integer. [Digital] Attempts to write to a STREAM with nbytes are outside the specified minimum and maximum range, and the minimum value is non-zero. RELATED INFORMATION Functions: open(2), fcntl(2), lseek(2), mtio(7), open(2), getmsg(2), lockf(3), pipe(2), poll(2), select(2) ulimit(3) Standards: standards(5) delim off write(2)