WRITE(2,L) AIX Technical Reference WRITE(2,L)
-------------------------------------------------------------------------------
write, writex
PURPOSE
Writes to a file or socket.
SYNTAX
int write (d, buf, nbytes) int writex (d, buf, nbytes, ext)
int d; int d;
char *buf; char *buf;
unsigned int nbytes; unsigned int nbytes;
int ext;
DESCRIPTION
The write system call writes the number of bytes specified by the nbyte
parameter from the buffer pointed to by the buf parameter to the object
associated with the d parameter.
The d parameter is a file descriptor obtained from a creat, open, dup, fcntl,
or pipe system call, or a socket descriptor from a socket or socketpair system
call.
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 the write
system call, the file pointer increments 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.
When the O_APPEND flag of the file status is set, the file pointer is set to
the end of the file prior to each write.
If a file is opened with the O_DEFERC flag, changes made to it with write can
later be undone with the fabort system call. Changes are not made permanent
until the file is committed explicitly by calling fsync or implicitly some time
after calling close or exiting, at which time all files are closed. (See
"fabort," "fsync, fcommit," and "close, closex.")
If this file is open for writing using more than one file descriptor, an fabort
operation will undo uncommitted changes made to the file by any of these
processes. Also, the implicit commit of the changes will not occur until all
Processed November 7, 1990 WRITE(2,L) 1
WRITE(2,L) AIX Technical Reference WRITE(2,L)
of these file descriptors are closed. If one wants to guarantee that the
changes are made permanent immediately, the use of fcommit is recommended.
Also, locking such as that provided by the lockf system call is recommended if
more than one process will be writing to the same file.
If the real user is not the superuser, the write system call clears the
set-group-id and set-user-id bits on a file. This prevents penetration of
system security by a user who obtains a writable set-user-id file owned by the
superuser.
If the write system call requests that more bytes be written than there is room
for, only as many bytes as there is room for are written and the write system
call returns an integer equal to the number of bytes written. The next attempt
to write a nonzero number of bytes will fail (except as noted following). The
limit reached can be either the ulimit (see "ulimit") or the end of the
physical medium. A partial write is not permitted for the following:
o If the file being written is a pipe (or FIFO) and unless O_NDELAY or
O_NONBLOCK is set in the file flag word, a write to a full pipe (or FIFO)
blocks until space becomes available.
o If the file being written is a pipe (or FIFO) and O_NDELAY is set in the
file flag word, a write to a full pipe (or FIFO) returns a count of 0.
o If the file being written is a pipe (or FIFO) and O_NONBLOCK is set in the
file flag word, a write to a full pipe (or FIFO) returns -1 and errno is
set to EAGAIN.
o An attempt to write data to a pipe when the read end of the pipe has been
closed will cause the signal SIGPIPE to be raised. If this signal is
caught or ignored, the error EPIPE is returned.
When attempting to write to a socket and the socket is not ready to accept
data:
o Unless O_NDELAY or O_NONBLOCK is set, the write blocks until the socket is
ready to accept data.
o If O_NDELAY is set, the write returns 0.
o If O_NONBLOCK is set, the write returns -1 and errno is set to EAGAIN.
If the file to be written supports enforcement mode record locks and all or
part of the region to be written is currently locked by another process:
o If O_NDELAY or O_NONBLOCK is set, write returns -1 and sets errno to
EAGAIN.
o If O_NDELAY and O_NONBLOCK are not set, the calling process blocks until
the lock is released.
For more information about record locks, see "fcntl, flock, lockf" .
Processed November 7, 1990 WRITE(2,L) 2
WRITE(2,L) AIX Technical Reference WRITE(2,L)
The SIGTTOU signal will be sent to the writer's process group if the process:
o is writing to its controlling terminal
o has the TOSTOP terminal attribute set
o is not ignoring or blocking SIGTTOU, and
o is in the foreground process group of the terminal
Otherwise, output to a terminal is permitted, even by processes which are not
in the foreground process group of the terminal.
If the Transparent Computing Facility is installed on your system, when writing
to a file which is stored on a site other than where the process is running, it
is possible for the out-of-space condition to go unnoticed until after the
write system call has returned. If this situation arises, the ENOSPC error
will be reported on subsequent write, fcommit, and fabort calls. The system
attempts to minimize the likelihood of out-of-space problems getting reported
in this way by using a less efficient, synchronous procedure for writing to a
remote file system when that file system is low on space. Thus, writing to a
remote file system is most efficient when the file system is less than 90%
full.
The writex system call performs the same function as write, except that it
provides communication with character device drivers that require more
information or return more status than write can handle.
For files, directories, sockets, or special files with drivers that do not
handle extended operations, the writex system call does exactly what the write
system call does, and the ext parameter is ignored.
Each driver interprets the ext parameter in a device-dependent way, either as a
value or as a pointer to a communication area. The nonextended write system
call is equivalent to the extended writex system call with an ext parameter
value of 0. Drivers must apply reasonable defaults when the ext parameter
value is 0.
RETURN VALUE
Upon successful completion, the number of bytes actually written is returned.
If the write or writex system call fails, a value of -1 is returned and errno
is set to indicate the error.
ERROR CONDITIONS
The write and writex system calls fail and the file pointer remains unchanged
if one or more of the following are true:
Processed November 7, 1990 WRITE(2,L) 3
WRITE(2,L) AIX Technical Reference WRITE(2,L)
EBADF The d parameter is not a valid file descriptor open for writing or
valid socket descriptor.
EAGAIN An enforcement mode record lock is outstanding in the portion of the
file that is to be written.
EAGAIN The object is a socket or pipe and is marked for non-blocking I/O,
and the socket or pipe was not ready to accept data.
EPIPE An attempt is made to write to a pipe that is not open for reading by
any process or to write to a socket of type SOCK_STREAM that is not
connected to a peer socket. A SIGPIPE signal is also sent to the
calling process.
EFBIG An attempt is made to write a file that exceeds the process's file
size limit or the maximum file size (see "ulimit").
EFAULT buf points to a location outside of the process's allocated address
space.
EDEADLK A deadlock would occur if the calling process were to sleep until the
region to be written was unlocked.
EINTR A signal was caught during the write system call.
ENOSPC There is no more space left on the device.
EIO A physical I/O error occurred.
If the Transparent Computing Facility is installed on your system, write or
writex can also fail if one or more of the following are true:
ESITEDN1 The file cannot be written because the file storage site went down.
If the file is replicated, this indicates the loss of the site where
the primary copy of the file is stored.
ESITEDN2 The operation was terminated because a site failed.
RELATED INFORMATION
In this book: "dup," "fcntl, flock, lockf," "lseek," "open, openx, creat,"
"pipe," "ulimit," and "writev."
Processed November 7, 1990 WRITE(2,L) 4