WRITE(2) SysV WRITE(2)
NAME
write - write on a file
SYNOPSIS
int write (fildes, buf, nbyte)
int fildes;
const char *buf;
unsigned int nbyte;
DESCRIPTION
The write function attempts to write nbytes of data to the file
associated with the fildes parameter from the buffer pointed to by the
buffer parameter. fildes is a file descriptor obtained from a creat(2),
open(2), dup(2), fcntl(2), or pipe(2) system call.
With regular files and devices capable of seeking, the actual writing of
data proceeds from the position in the file indicated by the file
pointer. If this incremented file pointer is greater than the length of
the file, the length of the file is set to this file offset. Upon return
from the write function, the file pointer increments by the number of
bytes actually written.
With 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.
For programs compiled to expect an AES, XPG3 or POSIX environment, the
following behavior is true (otherwise, write fails with [EFBIG]):
Fewer bytes than requested can be written if there is not enough
room to satisfy the request. In this case the number of bytes
written is returned. The next attempt to write a nonzero number of
bytes fails (except as noted in the following text). The limit
reached can be either the ulimit(2) or the end of the physical
medium. For example, suppose there is space for 20 bytes more in a
file before reaching a limit. A write of 512 bytes returns 20. The
next write of a nonzero number of bytes will give a failure return
(except as noted below).
Upon successful completion, the write function returns the number of
bytes actually written to the file associated with the fildes parameter.
This number is never be greater than the nbyte parameter.
If the O_APPEND flag of the file status is set, the file offset is set to
the end of the file prior to each write.
If the O_SYNC flag of the file status flags is set and the fildes
parameter refers to a regular file, a successful write function does not
return until the data is delivered to the underlying hardware (as
described in the open function).
If a write is interrupted by a signal after it has successfully read some
data, the call retruns the number of bytes written.
Write requests to a pipe (or FIFO) are handled the same as a regular file
with the following exceptions:
+ There is no file offset associated with a pipe; hence each write
request appends to the end of the pipe.
+ If the size of the write request is less than or equal to the value of
the PIPE_BUF system variable, write requests will not be interleaved
with data from other processes doing writes on the same pipe (the
write function is guaranteed to be atomic.)
Writes of greater than PIPE_BUF bytes can have data interleaved, on
arbitrary boundaries, with writes by other processes, whether or not
O_NONBLOCK or O_NDELAY are set.
+ If neither O_NONBLOCK nor O_NDELAY are set, a write request to a full
pipe may cause the process to block until enough space becomes
available to handle the entire request.
+ If the O_NONBLOCK or O_NDELAY flag is set, write requests are handled
differently in the following ways: the write function does 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 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 regular file with enforcement mode record
locking enabled, and all or part of the region to be written is currently
locked by another process:
+ If O_NDELAY and O_NONBLOCK are clear (the default), the calling
process blocks until all the blocking locks are removed, or the
write function is terminated by a signal.
+ If O_NDELAY or O_NONBLOCK is set, then the write function returns -1
and sets errno to [EAGAIN].
Upon successful completion, the write function marks the st_ctime and
st_mtime fields of the file for update, and clears its set-user ID and
set-group ID attributes if the file is a regular 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 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.
If the nbyte argument is 0 (zero), the write function returns 0 (zero)
and has no other results if the file is a regular file, a pipe, or raw-
disk file.
If the nbyte argument is greater than {INT_MAX}, the write function
returns 0 (zero) and has no other results if the file is a regular file,
or pipe.
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.
[EIO] The process is a member of a background process group
attempting to write to its controlling terminal, TOSTOP is
set, the process is neither ignoring nor blocking SIGTTOU,
and the process group of the process is orphaned.
[EDQUOT] The user's quota of disk blocks on the file system containing
the file has been exhausted.
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.