WRITE(S) UNIX System V WRITE(S)
Name
write - write on a file
Syntax
int write (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
Description
fildes is a file descriptor obtained from a creat(S),
open(S), dup(S), fcntl(S), or pipe(S) system call.
The write system call 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_.PEND 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(S)), 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(S)) 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 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 non-zero, 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 blocking
record lock.
[EAGAIN] Total amount of system memory available when
reading via raw IO 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 cause
a deadlock situation to occur.
[EFAULT] buf 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 (see ulimit(S)).
[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 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 non-zero.
[EIO] A physical I/O error has occurred.
If a write requests that more bytes be written than there is
room for (for example, the ulimit (see ulimit(S)) 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
non-zero 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(S), dup(S), fcntl(S), intro(S), lseek(S), open(S),
pipe(S), ulimit(S)
Diagnostics
Upon successful completion the number of bytes actually
written is returned. Otherwise, -1 is returned, and errno
is set to indicate the error.
Standards Conformance
write is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
The X/Open Portability Guide II of January 1987;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)