pwrite(2)                                                     pwrite(2)

  write()

  NAME

    write(), pwrite(), writev() - write output

  SYNOPSIS

    #include 

    ssize_t write (int d, const void *buf, size_t nbytes)
    ssize_t pwrite (int d, const void *buf, size_t nbytes, off_t offset)

    #include 

    ssize_t writev (int d, const struct iovec *iov, int iovcnt)

  DESCRIPTION

    The write(2) function attempts to write nbytes of data to the object
    referenced by the descriptor d from the buffer pointed to by buf. The
    writev(2) function performs the same action, 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(2), the iovec structure is defined as:

    struct iovec {
         void *iov_base;
         size_t iov_len;
    };

    Each iovec entry specifies the base address and length of an area in
    memory from which data should be written. The writev(2) function will
    always write a complete area before proceeding to the next.

    On objects capable of seeking, the write(2) starts at a position given by
    the pointer associated with d, (see lseek(2)). Upon return from write(2),
    the pointer is incremented by the number of bytes which were written.

    Objects that are not capable of seeking always write from the current
    position. The value of the pointer associated with such an object is
    undefined.

    The pwrite(2) function is identical to write(2), except that it begins
    writing at the byte position in the file specified by the offset argument
    and does not change the file pointer.

    When using non-blocking input/output (I/O) on objects such as sockets that
    are subject to flow control, these functions can write fewer bytes than
    requested; the return value must be noted, and the remainder of the
    operation should be retried when possible.

  RETURN VALUES

    Upon successful completion the number of bytes which were written is
    returned. Otherwise a -1 is returned and the global variable errno is set
    to indicate the error.

    When calling the write(2) or the pwrite(2) function on a file that is not
    a regular file with nbytes set to zero, the function returns 0.

    When the nbytes argument exceeds {SSIZE_MAX}, the return value is
    truncated to type ssize_t.

  ERRORS

    All three functions will fail and the file pointer will remain unchanged
    if:

    [EAGAIN]
        The file was marked for non-blocking I/O, and no data could be written
        immediately.

    [EBADF]
        D is not a valid descriptor open for writing.

    [EFAULT]
        Part of iov or data to be written to the file points outside the
        process's allocated address space.

    [EFBIG]
        An attempt was made to write a file that exceeds the process's file
        size limit or the maximum file size.

    [EINVAL]
        The pointer associated with d was negative, or d is on a device that
        doesn't support the operation.

    [EIO]
        An I/O error occurred while reading from or writing to the file
        system.

    [EPIPE]
        An attempt is made to write to a socket of type SOCK_STREAM that is
        not connected to a peer socket.

    [ENOSPC]
        There is no free space remaining on the file system containing the
        file.

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

    The pwrite(2) function can fail for the following reasons:

    [EINVAL]
        The offset argument is invalid (negative).

    [ESPIPE]
        The d argument is associated with a pipe or FIFO.

    In addition, writev(2) may return one of the following errors:

    [EINVAL]
        Iovcnt was less than or equal to 0, or greater than

    [EINVAL]
        One of the iov_len values in the iov array was negative.

    [EINVAL]
        The sum of the iov_len values in the iov array overflowed a 32-bit
        integer.

  SEE ALSO

    fcntl(2)

    lseek(2)

    open(2)

    pipe(2)

    select(2)

  USAGE NOTES

    All of these functions are thread safe.

    The write function is async-signal safe. The following functions are not
    async-signal safe: writev, pwrite.