WRITE(2) | System Calls Manual | WRITE(2) |
write
, writev
,
pwrite
, pwritev
—
#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);
#include
<sys/uio.h>
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);
write
() 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 the 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.
write
(), writev
(),
pwrite
(), and pwritev
() will
fail and the file pointer will remain unchanged if:
EAGAIN
]EBADF
]EDQUOT
]EFAULT
]EFBIG
]EINTR
]EINVAL
]EIO
]ENOSPC
]EPIPE
]SOCK_STREAM
that is not connected to a peer
socket.In addition, writev
() and
pwritev
() may return one of the following
errors:
EINVAL
]IOV_MAX
}; or one of the
iov_len values in the iov
array was negative; or the sum of the iov_len values
in the iov array overflowed a 32-bit integer.The pwrite
() and
pwritev
() calls may also return the following
errors:
write
() 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”).
pwritev
() function call appeared in
NetBSD 1.4. The pwrite
()
function call appeared in AT&T System V
Release 4 UNIX. The writev
() function
call appeared in 4.2BSD. The
write
() function call appeared in
Version 1 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)
September 2, 2019 | NetBSD 9.0 |