NAME

write, writev − Writes to a file. 

SYNOPSIS

#include <unistd.h>
ssize_t write(
int filedes ,
const char ∗buffer,
size_t nbytes ); #include <sys/types.h>
#include <sys/uio.h> ssize_t writev(
int filedes ,
struct iovec ∗iov,
int iov_count );

PARAMETERS

filedesIdentifies the file to which the data is to be written. 

bufferPoints to the buffer containing the data to be written. 

nbytesSpecifies the number of bytes to write to the file associated with the filedes parameter. 

iovPoints 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 following members:

caddr_t  iov_base;
int      iov_len;

iov_countSpecifies the number of iovec structures pointed to by the iov parameter. 

DESCRIPTION

The write() function attempts to write nbytes of data to the file associated with the filedes parameter from the buffer pointed to by the buffer parameter. 

If the nbyte parameter is 0 (zero), the write() function returns 0 (zero) and has no other results if the file is a regular file. 

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 UIO_MAXIOV, which is defined in the sys/uio.h header file.  The writev() function always writes a complete area before proceeding to the next. 

The write() and writev() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended. 

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() function, the file pointer increments by the number of bytes actually written. 

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. 

Fewer bytes than requested can be written if there is not enough room to satisfy the request. In this case the number of bytes written is returned. The next attempt to write a nonzero number of bytes fails (except as noted in the following text). The limit reached can be either the ulimit() or the end of the physical medium.  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 will give a failure return (except as noted below). 

Upon successful completion, the write() function returns the number of bytes actually written to the file associated with the fildes parameter.  This number is never be greater than the nbyte parameter. 

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. 

If the O_SYNC flag of the file status flags is set and the fildes parameter refers to a regular file, a successful write() function does not return until the data is delivered to the underlying hardware (as described in the open() function). 

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 appends to the end of the pipe. 

       •If the size of the write() request is less than or equal to the value of the PIPE_BUF system variable, the write() function is guaranteed to be atomic. The data is not interleaved with data from other processes doing writes on the same pipe.  Writes of greater than PIPE_BUF bytes can have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not O_NONBLOCK or O_NDELAY are set. 

       •If neither O_NONBLOCK nor O_NDELAY are set, a write() request to a full pipe causes the process to block until enough space becomes available to handle the entire request. 

       •If the O_NONBLOCK or O_NDELAY flag is set, write() requests are handled differently in the following ways: the write() function does block the process; write() requests for PIPE_BUF or fewer bytes either succeed completely and return nbyte, or return −1 and set errno to [EAGAIN]. A write() request for greater than PIPE_BUF 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 PIPE_BUF bytes and all data previously written to the pipe has been read, write() transfers at least PIPE_BUF bytes. 

When attempting to write to a file descriptor (other than a pipe or a FIFO) that supports nonblocking writes and cannot accept data immediately:

       •If O_NDELAY and O_NONBLOCK are clear, the write() function blocks until the data can be accepted. 

       •If O_NDELAY or O_NONBLOCK are set, the write() 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. Otherwise, if O_NDELAY is set, it returns 0; if O_NONBLOCK is set, it returns -1 and errno is set to [EAGAIN]. 

When attempting to write to a regular file with enforcement mode record locking enabled, and all or part of the region to be written is currently locked by another process:

       •If O_NDELAY and O_NONBLOCK are clear (the default), the calling process blocks until all the blocking locks are removed, or the write() function is terminated by a signal. 

       •If O_NDELAY or O_NONBLOCK is set, then the write() function returns -1 and sets errno to [EAGAIN]. 

Upon successful completion, the write() 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. 

The behavior of an interrupted write() function depends on how the handler for the arriving signal was installed:

       •If a write() function is interrupted by a signal before it writes any data, it returns −1 with errno set to [EINTR]. 

       •If a write() function is interrupted by a signal after it successfully writes some data, it returns the number of bytes written.  A write() request to a pipe or FIFO never returns with errno set to [EINTR] if it has transferred any data and nbyte is less than or equal to PIPE_BUF.

       •If the handler was installed with an indication that functions should not be restarted, the write() function returns a value of -1 and sets errno to [EINTR] (even if some data was already written). 

       •If the handler was installed with an indication that functions should be restarted:

−If no data was written when the interrupt was handled, the write() function does not return a value (it is restarted). 

−If data was written when the interrupt was handled, the write() function returns the amount of data already written. 

For STREAMS files, the operation of write() is determined by the values of the minimum and maximum nbyte range ("packet size") accepted by the stream.  These values are contained in the topmost stream module.  Unless the user pushes [see I_PUSH in streamio()] the topmost module, these values can not be set or tested from user level.  If nbyte falls within the packet size range, nbyte bytes are written.  If nbyte does not fall within the range and the minimum packet size value is zero, write() 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 nbyte does not fall within the range and the minimum value is non-zero, write() fails with errno set to ERANGE.  Writing a zero-length buffer (nbyte is zero) sends zero bytes with zero returned. 

For STREAMS files, if either O_NDELAY or O_NONBLOCK is clear and the stream can not accept data (the stream write queue is full due to internal flow control conditions), write blocks until data can be accepted.  O_NDELAY or O_NONBLOCK prevents a process from blocking due to flow control conditions.  If either O_NDELAY or O_NONBLOCK is set and the stream can not accept data, write() fails.  If either O_NDELAY or 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, write() terminates and return the number of bytes written. 

NOTES

AES Support Level:
Full use (write())

RETURN VALUES

Upon successful completion, the write() and writev() functions return the number of bytes that were actually written.  If the write() and writev() functions fail, a value of -1 is returned, errno is set to indicate the error, and the content of the buffer pointed to by the buffer parameter is indeterminate. 

End-of-Media Handling for Tapes

If writing goes beyond the "early warning" EOT indicator while this indicator is disabled, the write() and writev() functions will return the number of bytes actually written and placed into the buffer. The write() 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 warning" 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

If the write() or writev() function fails, errno may be set to one of the following values:

[EAGAIN]Attempt to write to a stream that can not accept data with either the O_NDELAY or O_NONBLOCK flag set. 

The O_NONBLOCK flag is set on this file and the process would be delayed in the write operation. 

An enforcement mode record lock is outstanding in the portion of the file that is to be written. 

[EBADF]The filedes  parameter does not specify a valid file descriptor open for writing. 

[EDEADLK]Enforced record locking is enabled, O_NDELAY is clear, and a deadlock condition is detected. 

[EDQUOT]The write has failed because the user’s disk block quota is exhausted. 

[EFAULT]The buffer parameter or part of the iov parameter points to a location outside of the allocated address space of the process. 

[EFBIG]An attempt was made to write a file that exceeds the maximum file size. 

[EINTR]A signal was caught during the write() operation, and the signal handler was installed with an indication that functions are not to be restarted. 

[EINVAL]Attempt to write to a stream linked below a multiplexor. 

The file position pointer associated with the filedes parameter was negative. 

The iov_count parameter value was less than or equal to 0 or greater than UIO_MAXIOV. 

One of the iov_len values in the iov array was negative or the sum overflowed a 32-bit integer. 

[EIO]A read or write physical I/O error.  These errors do not always occur with the associated function, but can occur with the subsequent function. 

[ENOLCK]The file has enforcement mode file locking set and allocating another locked region would exceed the configurable system limit of NLOCK_RECORD. 

[ENOSPC]Attempted to write past the "early warning" EOT while this indicator was enabled. 

Attempted to write at or beyond the end of a partition. 

No free space is left on the file system containing the file. 

[ENXIO]A hang up occurred on the stream being written to. 

The device associated with file descriptor (the fildes parameter) is a block special device or character special file and the file pointer is out of range. 

[EPERM]An attempt was made to write to a socket or type SOCK_STREAM that is not connected to a peer socket. 

[EPIPE]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. 

An attempt was made to write to a pipe that has only one end open. 

[ERANGE]Attempt to write to a stream with nbyte outside specified minimum and maximum write range, and the minimum value is non-zero. 

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() or writev() function fails, errno may also be set to one of the following values:

[EFBIG]For filesystems mounted with the nfsv2 option, the process attempted to write beyond the 2 gigabyte boundary. 

[EISDIR]The named file is a directory and write access is requested. 

[ENOBUFS]Indicates insufficient resources, such as buffers, to complete the call.  Typically, a call used with sockets has failed due to a shortage of message or send/receive buffer space. 

[EROFS]The named file resides on a read-only file system and write access is required. 

[ESTALE]Indicates 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 directory that contains an opened file was either unmounted or unexported by the server. 

If the write() or writev() function fails while in the System V habitat, errno may also be set to one of the following errors:

[EAGAIN]A write to a pipe (FIFO) of {PIPE_BUF} bytes or less is requested, O_NONBLOCK is set, and less than nbytes bytes of free space is available. 

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. 

[EINVAL]The sum of the iov_len values in the iov array overflowed an integer. 

[ERANGE]Attempts to write to a stream with nbyte 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)