write(2) write(2)
NAME
write, writev - write on a file
SYNOPSIS
ssize_t write (fildes, buf, nbyte)
int fildes;
char *buf;
size_t nbyte;
SYNOPSIS (4.2BSD)
#include <sys/types.h>
#include <sys/uio.h>
int writev (fildes, iov, iovcnt)
int fildes;
struct iovec *iov;
int iovcnt;
DESCRIPTION
Fildes is a file descriptor obtained from a creat, open,
dup, fcntl, or pipe system call.
write attempts to write nbyte bytes from the buffer pointed
to by buf to the file associated with the fildes. Writev
performs the same action, but gathers the output data from
the iovcnt buffers specified by the members of the iovec
array: iov[0], iov[1], ... , iov[iovcnt-1].
The iovec structure is defined as
struct iovec {
caddr_t iov_base;
int iov_len;
};
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 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 disk files, if the O_DSYNC bit of the file
status flags is set, all I/O operations on the file descrip-
tor complete as defined by synchronized I/O data integrity
completion. If the O_SYNC bit of the file status flags is
Page 1 CX/UX Programmer's Reference Manual
write(2) write(2)
set, all I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion (refer
to the open(2) man page for the definitions of synchronized
I/O data and file integrity completions). For files other
than regular disk files the O_DSYNC flag will have no
effect, for block special files the O_SYNC flag will force
the data to be physically updated before returning.
If a write requests that more bytes be written than 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, 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 or O_NONBLOCK 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 and O_NONBLOCK clear), writes to a
full pipe (or FIFO) will block until space becomes avail-
able.
When attempting to write to an ordinary file with enforced
record locking enabled, and all or part of the file segment
to be written has a read or write lock owned by another pro-
cess (i.e., a blocking lock):
If O_NDELAY or O_NONBLOCK is set the function write
will return -1 and errno will be set to EAGAIN .
If O_NDELAY and O_NONBLOCK are clear, the function
write will sleep until all blocking locks are removed,
or the function write is terminated by a signal.
For STREAMS [see intro(2)] files, the operation of write and
writev is determined by the values of the minimum and max-
imum 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 top-
most 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 non-zero, write
will fail with errno set to ERANGE. Writing a zero-length
buffer (nbyte is zero) sends zero bytes with zero returned.
Page 2 CX/UX Programmer's Reference Manual
write(2) write(2)
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 and writev 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
and writev 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 and writev will
terminate and return the number of bytes written.
When attempting to write a file that has been opened in
direct mode (i.e. O_DIRECT is set) the buffer pointed to by
buf or iov->iov_base must be longword aligned. Additionally
nbyte or iov->iov_len must be a multiple of the longword
length (4 bytes) and less than the maximum physical transfer
size (see CX/UX Programmer's Guide for details). Lastly,
the file pointer associated with fildes should be aligned to
a multiple of the disk block size (1 Kbyte) before the write
request is issued.
For pipes, FIFOs or character special devices, if the write
is interrupted by a signal, the number of bytes transferred
before the signal will be returned. If no bytes were
transferred, -1 will be returned and errno will be set to
EINTR.
For sockets, write has the same semantics as send(2) except
that the options associated the flags parameter of send are
not available for write.
write will fail and the file pointer will remain unchanged
if one or more of the following are true:
[EAGAIN] Attempt to write to a stream that can not
accept data with the O_NDELAY flag set.
[EAGAIN] Enforced record locking was enabled (see
chmod(2)), O_NDELAY or O_NONBLOCK was set,
and there were record locks on the file.
[EBADF] Fildes is not a valid file descriptor open
for writing.
[EDEADLK] Enforced record locking was enabled, O_NDELAY
and O_NONBLOCK were clear, and a deadlock
condition was detected.
[EFAULT] Buf or iov or points outside the process's
allocated address space.
[EFAULT] The file is opened for direct mode and the
Page 3 CX/UX Programmer's Reference Manual
write(2) write(2)
buffer is not aligned on a longword (4-byte)
boundary or the byte count is not a longword
multiple.
[EFAULT] The file is opened for direct mode and the
file pointer associated with fildes is not
aligned to a multiple of the disk block size
(1 Kbyte).
[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).
[EINTR] A signal was caught during the system call.
For a pipe, FIFO or character special device,
no data will have been transferred.
[EINVAL] Attempt to write to a stream linked below a
multiplexor.
[EIO] The process is in a background process group
and is attempting to write to its controlling
terminal, TOSTOP is set, and the process is
neither ignoring nor blocking SIGTTOU signals
and the process group of the process is
orphaned.
[ENOLCK] Enforced record locking was enabled and
{LOCK_MAX} regions are already locked in the
system.
[ENOSPC] There is no free space remaining on the dev-
ice containing the file.
[ENXIO] The file is opened for direct mode and the
byte count was greater than the maximum phy-
sical transfer size.
[EPIPE and SIGPIPE signal]
An attempt is made to write to a pipe that is
not open for reading by any process.
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.
RETURN VALUE
Upon successful completion the number of bytes actually
written is returned. Otherwise, -1 is returned and errno is
set to indicate the error.
Page 4 CX/UX Programmer's Reference Manual
write(2) write(2)
NOTE
The read function is defined in the 88open Binary and Object
Compatibility Standards (BCS/OCS) for use in BCS/OCS compli-
ant applications. Both functions are defined in the 88open
BCS and OCS Networking Supplements (BCSNS/OCSNS) for use in
BCS/OCS compliant networking applications. OCS/OCSNS-
defined functions may be accessed by passing OCS options to
cc(1) and ld(1).
SEE ALSO
creat(2), dup(2), lseek(2), open(2), pipe(2), send(2),
ulimit(2).
termio(7) and termios(7) in the CX/UX Administrator's Refer-
ence Manual.
Page 5 CX/UX Programmer's Reference Manual