#include <sys/types.h>
#include <sys/uio.h>
#include <unistd.h> ssize_t
write (int d const void *buf size_t nbytes); ssize_t
pwrite (int d const void *buf size_t nbytes off_t offset); ssize_t
writev (int d const struct iovec *iov int iovcnt); ssize_t
pwritev (int d const struct iovec *iov int iovcnt off_t offset);
DESCRIPTION
The
write ();
system call
attempts to write
Fa nbytes
of data to the object referenced by the descriptor
Fa d
from the buffer pointed to by
Fa buf .
The
writev ();
system call
performs the same action, but gathers the output data
from the
Fa iovcnt
buffers specified by the members of the
Fa iov
array: iov[0], iov[1], ..., iov[iovcnt-1].
The
pwrite ();
and
pwritev ();
system calls
perform the same functions, but write to the specified position in
the file without modifying the file pointer.
For
writev ();
and
pwritev (,);
the
Fa iovec
structure is defined as:
Each
Fa iovec
entry specifies the base address and length of an area
in memory from which data should be written.
The
writev ();
system call
will always write a complete area before proceeding
to the next.
On objects capable of seeking, the
write ();
starts at a position
given by the pointer associated with
Fa d ,
see
lseek(2).
Upon return from
write (,);
the pointer is incremented by the number of bytes which were written.
Objects that are not capable of seeking always write from the current
position.
The value of the pointer associated with such an object
is undefined.
If the real user is not the super-user, then
write ();
clears the set-user-id bit on a file.
This prevents penetration of system security
by a user who
``captures''
a writable set-user-id file
owned by the super-user.
When using non-blocking I/O on objects such as sockets that are subject
to flow control,
write ();
and
writev ();
may write fewer bytes than requested;
the return value must be noted,
and the remainder of the operation should be retried when possible.
RETURN VALUES
Upon successful completion the number of bytes which were written
is returned.
Otherwise a -1 is returned and the global variable
errno
is set to indicate the error.
ERRORS
The
write (,);
writev (,);
pwrite ();
and
pwritev ();
system calls
will fail and the file pointer will remain unchanged if:
Bq Er EBADF
The
Fa d
argument
is not a valid descriptor open for writing.
Bq Er EPIPE
An attempt is made to write to a pipe that is not open
for reading by any process.
Bq Er EPIPE
An attempt is made to write to a socket of type
SOCK_STREAM
that is not connected to a peer socket.
Bq Er EFBIG
An attempt was made to write a file that exceeds the process's
file size limit or the maximum file size.
Bq Er EFAULT
Part of
Fa iov
or data to be written to the file
points outside the process's allocated address space.
Bq Er EINVAL
The pointer associated with
Fa d
was negative.
Bq Er ENOSPC
There is no free space remaining on the file system
containing the file.
Bq Er EDQUOT
The user's quota of disk blocks on the file system
containing the file has been exhausted.
Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
Bq Er EINTR
A signal interrupted the write before it could be completed.
Bq Er EAGAIN
The file was marked for non-blocking I/O,
and no data could be written immediately.
Bq Er EROFS
An attempt was made to write over a disk label area at the beginning
of a slice.
Use
disklabel(8)
-W
to enable writing on the disk label area.
Bq Er EINVAL
The value
Fa nbytes
is greater than
INT_MAX
In addition,
writev ();
and
pwritev ();
may return one of the following errors:
Bq Er EDESTADDRREQ
The destination is no longer available when writing to a
UNIX
domain datagram socket on which
connect(2)
had been used to set a destination address.
Bq Er EINVAL
The
Fa iovcnt
argument
was less than or equal to 0, or greater than
IOV_MAX
Bq Er EINVAL
One of the
Fa iov_len
values in the
Fa iov
array was negative.
Bq Er EINVAL
The sum of the
Fa iov_len
values in the
Fa iov
array overflowed a 32-bit integer.
Bq Er ENOBUFS
The mbuf pool has been completely exhausted when writing to a socket.
The
pwrite ();
and
pwritev ();
system calls may also return the following errors:
Bq Er EINVAL
The
Fa offset
value was negative.
Bq Er ESPIPE
The file descriptor is associated with a pipe, socket, or FIFO.
The
write ();
system call is expected to conform to
St -p1003.1-90 .
The
writev ();
and
pwrite ();
system calls are expected to conform to
St -xpg4.2 .
HISTORY
The
pwritev ();
system call appeared in
Fx 6.0 .
The
pwrite ();
function appeared in
AT&T System
V.4 .
The
writev ();
system call appeared in
BSD 4.2
The
write ();
function appeared in
AT&T System
v6 .
