write(), writev()

write bytes to a file

Synopsis:

#include <sys/uio.h>
#include <unistd.h>
ssize_t write( int fildes,
               const void *buf,
               size_t nbyte );
int writev( int fildes,
            const struct iovec *iov,
            int iovcnt );

Description:

The write() function attempts to write nbyte bytes to the file associated with the open file descriptor, fildes, from the buffer pointed to by buf.

If nbyte is zero, write() returns zero and has no other effect.

The writev() function performs the same action as write(), but gathers the output data from the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1].

For writev(), the iovec structure contains the following members:

caddr_t iov_base

base address of a memory area from which data should be written

long iov_len

the length of the memory area

writev() always writes a complete area before proceeding to the next.

The maximum number of entries in the iov array is UIO_MAXIOV.

On a regular file or other file capable of seeking, and if O_APPEND isn't set, write() starts at a position in the file given by the file offset associated with fildes. If O_APPEND is set, the file offset is set to the end of file before each write operation. Before successfully returning from write(), the file offset is incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length of the file, the length of the file is set to this file offset.

The write() call ignores advisory locks that may have been set by the fcntl(), lock(), or locking() functions.

On a file not capable of seeking, write() starts at the current position.

If write() requests that more bytes be written than there's room for (for example, all blocks on a disk are already allocated), only as many bytes as there is room for are written. For example, if there's only room for 80 more bytes in a file, a write of 512 bytes returns 80. The next write of a nonzero number of bytes gives a failure return (except as noted below).

When write() returns successfully, its return value is the number of bytes actually written to the file. This number is never greater than nbyte, although it may be less than nbyte under certain circumstances detailed below.

If write() is interrupted by a signal before it has written any data, it returns -1, and errno is set to EINTR. However, if write() is interrupted by a signal after it has successfully written some data, it returns the number of bytes written.

If the value of nbyte is greater than INT_MAX, write() returns -1 and sets errno to EINVAL. See <limits.h>.

Write requests to a pipe (or FIFO) are handled the same as a regular file, with the following exceptions:

1. There's no file offset associated with a pipe, therefore each write request appends to the end of the pipe.
2. Write requests of PIPE_BUF bytes or less aren't interleaved with data from other processes doing writes on the same pipe. Writes of greater than PIPE_BUF bytes may have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag is set.
3. If the O_NONBLOCK flag is clear, a write request may cause the process to block, but on normal completion it returns nbyte.
4. If the O_NONBLOCK flag is set, write requests are handled differently, in the following ways:
   • the write() function doesn't block the process
   • write requests for PIPE_BUF bytes or less either succeed completely and return nbyte, or return -1 and errno is set to EAGAIN.

   If nbyte is greater than PIPE_BUF bytes, write() either transfers what it can and returns the number of bytes written, or transfers no data, returning -1 and setting errno to EAGAIN. Also, if nbyte is greater than PIPE_BUF bytes and all data previously written to the pipe has been read (that is, the pipe is empty), write() transfers at least PIPE_BUF bytes.

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

1. If the O_NONBLOCK flag is clear, write() blocks until the data can be accepted.
2. If the O_NONBLOCK flag is set, write() doesn't block the process. If some data can be written without blocking the process, write() transfers what it can and returns the number of bytes written. Otherwise, it returns -1 and sets errno to EAGAIN.

If write() is called with the file offset beyond the end-of-file, the file is extended to the current file offset with the intervening bytes filled with zeroes. This is a useful technique for pre-growing a file.

If write() succeeds, the st_ctime and st_mtime fields of the file are marked for update.

When write() is called and either of the O_CACHE or O_TEMP flags (QNX extensions) is set, internal file system caching behavior may be modified. Also, if either of the O_SYNC or O_DSYNC flags is set, the behavior of write() in the presence of physical storage errors and the action of the file system in maintaining the data and information about it is modified. See the open() documentation for a discussion of the effect of these flags on I/O calls.

Returns:

The number of bytes actually written. If an error occurs, -1 is returned and errno is set to indicate the error.

Errors:

EAGAIN

The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed in the write operation.

EBADF

The file descriptor, fildes, isn't a valid file descriptor open for writing.

EFBIG

File is too big.

EINTR

The write operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file doesn't report partial transfers.

EINVAL

iovcnt was less than or equal to 0, or greater than UIO_MAXIOV.

EIO

A physical I/O error occurred (for example, a bad block on a disk). The precise meaning is device-dependent.

ENOSPC

There's no free space remaining on the device containing the file.

EPIPE

An attempt was made to write to a pipe (or FIFO) that isn't open for reading by any process. A SIGPIPE signal is also sent to the process.

Examples:

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>

char buffer[] = { "A text record to be written" };

void main()
  {
    int  fd;
    int  size_written;

    /* open a file for output          */
    /* replace existing file if it exists */
    fd = creat( "myfile.dat", S_IRUSR | S_IWUSR );

    /* write the text              */
    size_written = write( fd, buffer,
              sizeof( buffer ) );

    /* test for error              */
    if( size_written != sizeof( buffer ) ) {
      perror( "Error writing myfile.dat" );
    }

    /* close the file              */
    close( fd );
  }

Classification:

POSIX 1003.1

See also:

close(), creat(), dup(), dup2(), errno, fcntl(), lseek(), open(), pipe(), read(), readv(), select()