write(2P) INTERACTIVE UNIX System (POSIX) write(2P)
NAME
write - write on a file
SYNOPSIS
int write (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
DESCRIPTION
The write system call attempts to write nbyte bytes from the
buffer pointed to by buf to the file associated with the
fildes.
fildes is a file descriptor obtained from a creat(2),
open(2P), dup(2), fcntl(2), or pipe(2) system call.
If nbyte is zero, the write() function returns zero and has
no other results.
On devices capable of seeking, the actual writing of data
proceeds from the position in the file indicated by the file
pointer. Upon return from write, the file pointer is incre-
mented 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.
On 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 flags is set, the
file pointer will be set to the end of the file prior to
each write.
For regular files, if the O_SYNC flag of the file status
flags is set, the write will not return until both the file
data and file status have been physically updated. This
function is for special applications that require extra
reliability at the cost of performance. For block special
files, if O_SYNC is set, the write will not return until the
data has been physically updated.
A write to a regular file will be blocked if mandatory
file/record locking is set (see chmod(2P)) and there is a
record lock owned by another process on the segment of the
file to be written. If O_NDELAY is not set, the write will
sleep until the blocking record lock is removed.
If write() is interrupted by a signal after it successfully
writes some data, it returns the number of bytes written. A
Rev. 1.1 Page 1
write(2P) INTERACTIVE UNIX System (POSIX) write(2P)
write() 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}.
The maximum value of nbytes is UINT_MAX.
write requests to a pipe (or FIFO) are handled in the same
manner as write requests to a regular file, with the follow-
ing exceptions:
1. There is no file offset associated with a pipe,
hence each write request appends to the end of the
pipe.
2. write requests of {PIPE_BUF} bytes or less are not
interleaved with data from other processes doing
writes on the same pipe. writes of greater than
{PIPE_BUF} bytes may have data interleaved (on arbi-
trary boundaries) with writes by other processes,
whether or not the O_NONBLOCK flag of the file
status flags 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 does not 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 write() 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 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() 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, it returns -1, and errno is
set to [EAGAIN].
Rev. 1.1 Page 2
write(2P) INTERACTIVE UNIX System (POSIX) write(2P)
Upon successful completion, the write() function marks
for update the st_ctime and st_mtime fields of the
file.
For STREAMS (see intro(2)) 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(7)) the topmost module, these values cannot be
set or tested from user level. If nbyte falls within
the packet size range, nbyte bytes will be written. If
nbyte does not fall within the range and the minimum
packet size value is zero, write will break 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 nonzero,
write will fail with errno set to [ERANGE]. Writing a
zero-length buffer (nbyte is zero) sends zero bytes
with zero returned.
For STREAMS files, if O_NDELAY is not set and the
stream cannot accept data (the stream write queue is
full due to internal flow control conditions), write
will block until data can be accepted. O_NDELAY will
prevent a process from blocking due to flow control
conditions. If O_NDELAY is set and the stream cannot
accept data, write will fail. If O_NDELAY is set and
part of the buffer has been written when a condition in
which the stream cannot accept additional data occurs,
write will terminate and return the number of bytes
written.
The write system call will fail and the file pointer
will remain unchanged if one or more of the following
is true:
[EAGAIN] Mandatory file/record locking was set,
O_NDELAY was set, and there was a block-
ing record lock.
[EAGAIN] Total amount of system memory available
when reading via raw I/O is temporarily
insufficient.
[EAGAIN] Attempt to write to a stream that cannot
accept data with the O_NDELAY flag set.
[EBADF] fildes is not a valid file descriptor
open for writing.
[EDEADLK] The write was going to go to sleep and
Rev. 1.1 Page 3
write(2P) INTERACTIVE UNIX System (POSIX) write(2P)
cause a deadlock situation to occur.
[EFAULT] buf points outside the process's allo-
cated address space.
[EFBIG] An attempt was made to write a file that
exceeds the process's file size limit or
the maximum file size (see ulimit(2)).
[EIO] The implementation supports job control,
the process is in a background process
group and is attempting to write to its
controlling terminal, TOSTOP is set, the
process is neither ignoring nor blocking
SIGTTOU signals, and the process group
of the process is orphaned. This error
may also be generated for
implementation-defined reasons.
[EINTR] A signal was caught during the write
system call.
[EINVAL] Attempt to write to a stream linked
below a multiplexer.
[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 dev-
ice.
[ENXIO] A hangup occurred on the stream being
written to.
[EPIPE and SIGPIPE signal]
An attempt is made to write to a pipe
that is 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
nonzero.
[EIO] A physical I/O error has occurred.
If a write requests that more bytes be written than
Rev. 1.1 Page 4
write(2P) INTERACTIVE UNIX System (POSIX) write(2P)
there is room for (e.g., the ulimit (see ulimit(2)) or
the physical end of a medium), only as many bytes as
there is room for will be written. For example, sup-
pose there is space for 20 bytes more in a file before
reaching a limit. A write of 512-bytes will return 20.
The next write of a nonzero number of bytes will give a
failure return (except as noted below).
If the file being written is a pipe (or FIFO) and the
O_NDELAY flag of the file flag word is set, then write
to a full pipe (or FIFO) will return a count of 0.
Otherwise (O_NDELAY clear), writes to a full pipe (or
FIFO) will block until space becomes available.
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 mes-
sage.
SEE ALSO
creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2P),
pipe(2), ulimit(2).
DIAGNOSTICS
Upon successful completion the number of bytes actually
written is returned. Otherwise, -1 is returned, and errno
is set to indicate the error.
Rev. 1.1 Page 5