WRITE(2) | System Calls Manual | WRITE(2) |
pwrite
, write
,
pwritev
, writev
—
write output
Standard C Library (libc, -lc)
#include
<unistd.h>
ssize_t
pwrite
(int fildes,
const void *buf, size_t nbyte,
off_t offset);
ssize_t
write
(int fildes,
const void *buf, size_t
nbyte);
#include
<sys/uio.h>
ssize_t
writev
(int fildes,
const struct iovec *iov, int
iovcnt);
ssize_t
pwritev
(int fildes,
const struct iovec *iov, int
iovcnt, off_t offset);
write
()
attempts to write nbyte of data to the object
referenced by the descriptor fildes 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 { char *iov_base; /* Base address. */ size_t iov_len; /* Length. */ };
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
fildes, 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.
write
()
and
pwrite
()
will fail if the parameter nbyte exceeds
INT_MAX
, and they do not attempt a partial
write.
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.
The write
(),
writev
(), pwrite
(), and
pwritev
() system calls will fail and the file
pointer will remain unchanged if:
EDQUOT
]EFAULT
]EINVAL
]The write
() and
pwrite
() system calls will fail and the file pointer
will remain unchanged if:
EAGAIN
]EBADF
]ECONNRESET
]EFBIG
]EFBIG
]EINTR
]EINVAL
]INT_MAX
.EIO
]ENETDOWN
]ENETUNREACH
]ENOSPC
]ENXIO
]EPIPE
]EPIPE
]SOCK_STREAM
that is not connected to a peer
socket.EDEADLK
]The write
() and
writev
() calls may also return the following
errors:
EAGAIN
]EWOULDBLOCK
]In addition, writev
() may return one of
the following errors:
EDESTADDRREQ
]ENOBUFS
]The writev
() and
pwritev
() calls may also return the following
errors:
EINVAL
]UIO_MAXIOV
.EINVAL
]EINVAL
]The pwrite
() and
pwritev
() calls may also return the following
errors:
#include
<sys/types.h>
#include
<sys/uio.h>
#include
<unistd.h>
These include files are needed for all three functions.
The write
() function call is expected to
conform to IEEE Std 1003.1-1990
(“POSIX.1”). The writev
() and
pwrite
() functions are expected to conform to
X/Open Portability Guide Issue 4, Version 2
(“XPG4.2”). pwritev
() is
nonstandard.
The pwrite
() function call appeared in
AT&T System V Release 4 UNIX. The
writev
() function call appeared in
4.2BSD. A write
() function
call appeared in Version 6 AT&T UNIX.
June 3, 2021 | macOS 14.6 |