WRITE(2) SysV WRITE(2)
NAME
write - write on a file
SYNOPSIS
int write (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
DESCRIPTION
fildes is a file descriptor obtained from a creat(2), open(2), dup(2),
fcntl(2), or pipe(2) system call.
write attempts to write nbyte bytes from the buffer pointed to by buf to
the file associated with the fildes.
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 incremented by the number of bytes actually
written.
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(2)), 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.
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 can not 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 can not 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 can not 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 can not accept additional data occurs, write will
terminate and return the number of bytes written.
DIAGNOSTICS
Upon successful completion the number of bytes actually written is
returned. Otherwise, -1 is returned and errno is set to indicate the
error.
ERRORS
write will fail and the file pointer will remain unchanged if one or more
of the following are true:
[EAGAIN] Mandatory file/record locking was set, O_NDELAY was set, and
there was a blocking 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 can not 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 cause a deadlock
situation to occur.
[EFAULT] buf points outside the process' allocated address space.
[EFBIG] An attempt was made to write a file that exceeds the process'
file size limit or the maximum file size (see ulimit(2)).
[EINTR] A signal was caught during the write system call.
[EINVAL] Attempt to write to a Stream linked below a multiplexor.
[ENOLCK] The system record lock table was full, so the write could not
go to sleep until the blocking record lock was removed.
[ENOSPC] During a write to an ordinary file, there is no free space
left on the device.
[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.
If a write requests that more bytes be written than there is room for
(for example, 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, suppose 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 message.
SEE ALSO
creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2), pipe(2),
ulimit(2)
NOTES
Under other implementations, write fails if the following is true:
[ENOLINK] fildes is on a remote machine and the link to that machine is
no longer active.