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
)
)
attempts to write
nbytes
of data to the object referenced by the descriptor
d
from the buffer pointed to by
buf
.
writev(
)
performs the same action, but gathers the output data
from the
iovcnt
buffers specified by the members of the
iov
array: iov[0], iov[1], ..., iov[iovcnt-1].
pwrite(
)
and
pwritev(
)
perform the same functions, but write to the specified position in
the file without modifying the file pointer.
For
writev()
and
pwritev(
),
the
iovec
structure is defined as:
struct iovec {
void *iov_base;
size_t iov_len;
};
Each
iovec
entry specifies the base address and length of an area
in memory from which data should be written.
writev()
and
pwritev(
)
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
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.
If
write()
succeeds it will update the st_ctime and st_mtime fields of the file's
meta-data (see
stat(2)).
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.
),
writev(
),
pwrite(
),
and
pwritev(
)
will fail and the file pointer will remain unchanged if:
EBADF
]
d
is not a valid descriptor open for writing.
EPIPE
]
EPIPE
]
SOCK_STREAM
that is not connected to a peer socket.
EFBIG
]
EFAULT
]
iov
or data to be written to the file
points outside the process's allocated address space.
EINVAL
]
d
was negative.
EINVAL
]
ENOSPC
]
EDQUOT
]
EIO
]
EINTR
]
EAGAIN
]
In addition,
writev()
and
pwritev(
)
may return one of the following errors:
EINVAL
]
iovcnt
was less than or equal to 0, or greater than
{IOV_MAX}
.
EINVAL
]
iov_len
values in the
iov
array was negative.
EINVAL
]
iov_len
values in the
iov
array overflowed a 32-bit integer.
pwrite()
and
pwritev(
)
calls may also return the following errors:
EINVAL
]
ESPIPE
]
)
function is expected to conform to
IEEE Std 1003.1-1988 (``POSIX.1'') .
The
writev(
)
and
pwrite(
)
functions conform to
X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'') .
)
function call
appeared in
NetBSD1.4.
The
pwrite(
)
function call
appeared in
AT&T
System V.4 UNIX
.
The
writev(
)
function call
appeared in
4.2BSD.
The
write(
)
function call appeared in
Version 6 AT&T UNIX
.
while ((nr = write(fd, buf, sizeof(buf))) > 0)
is not maximally portable, as some platforms allow for
nbytes
to range between
SSIZE_MAX
and
SIZE_MAX
- 2, in which case the return value of an error-free
write()
may appear as a negative number distinct from -1.
Proper loops should use
while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0)