write(2)
NAME
write, writev − write on a file
SYNOPSIS
#include <unistd.h>
ssize_t write(int fildes, const void *buf, size_t nbyte);
#include <sys/uio.h>
ssize_t writev(
int fildes,
const struct iovec *iov,
size_t iovcnt
);
DESCRIPTION
write() attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the file descriptor fildes. writev() performs the same action, but gathers the output data from the iovlen buffers specified by the elements of the iovec array: iov[0], iov[1], ..., iov[iovcnt−1].
The iovec structure for writev() is defined as follows:
struct iovec {
caddr_t iov_base;
int iov_len;
};
Each iovec entry specifies the base address and length of an area in memory from which data should be copied. The iovec array can be at most MAXIOV long.
On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file offset. Upon return from write(), the file offset is incremented by the number of bytes actually written.
On devices incapable of seeking, writing always takes place starting at the device’s current position. The value of a file offset associated with such a device is undefined.
If the O_APPEND file status flag is set, the file offset is set to the end of the file prior to each write.
For ordinary files, if the O_SYNC flag of the file status flags is set, the write does not return until both the file data and the file status are physically updated. For block special files, if O_SYNC is set, the write does not return until the data is physically updated. How the data reaches the physical media is implementation- and hardware-dependent.
If the number of bytes requested by write() exceeds the allotted capacity (see ulimit(2)) or the physical end of a medium, only the allotted number of bytes are actually written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes returns 20. The next write of a non-zero number of bytes fails (except as noted below).
A write to an ordinary file is prevented if enforcement-mode file and record locking is set, and another process owns a lock on the segment of the file being written:
If O_NDELAY or O_NONBLOCK is set, the write returns −1 and sets errno to EAGAIN.
If O_NDELAY and O_NONBLOCK are clear, the write does not complete until the blocking record lock is removed.
If the file being written is a pipe (or FIFO), the system-dependent maximum number of bytes that it can store is given by PIPSIZ (defined in <sys/inode.h>). The minimum value of PIPSIZ on any HP-UX system is 8192. When writing a pipe, the following conditions apply:
If the O_NDELAY or O_NONBLOCK file status flag is set:
If nbyte is less than or equal to PIPSIZ and sufficient room exists in the pipe or FIFO, the write() succeeds and returns the number of bytes written;
If nbyte is less than or equal to PIPSIZ but insufficient room exists in the pipe or FIFO, the write() returns having written nothing. If O_NONBLOCK is set, −1 is returned and errno is set to EAGAIN. If O_NDELAY is set, 0 is returned.
If nbyte is greater than PIPSIZ and the pipe or FIFO is full, the write returns having written nothing. If O_NONBLOCK is set, −1 is returned and errno is set to EAGAIN. If O_NDELAY is set, 0 is returned.
If nbyte is greater than PIPSIZ, and some room exists in the pipe or FIFO, as much data as fits in the pipe or FIFO is written, and write() returns the number of bytes actually written, an amount less than the number of bytes requested.
If the O_NDELAY and O_NONBLOCK file status flags are clear:
The write() always executes correctly (blocking as necessary), and returns the number of bytes written.
If write() is interrupted by a signal after it successfully writes some data, it returns the number of bytes written before the interrupt occurred. If write() is interrupted before any bytes are written, write() returns −1 and sets errno to EINTR.
write() clears the SUID, SGID, and sticky bits on all non-directory type files if the write is performed by any user other than the owner or a user who has appropriate privileges. For directories, write() does not clear the SUID, SGID, and sticky bits.
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.
ERRORS
write() fails and the file offset remains unchanged if any of the following conditions is true:
[EBADF] fildes is not a valid file descriptor open for writing.
[EPIPE and SIGPIPE signal]
An attempt is made to write to a pipe that is not open for reading by any process.
[EINTR] A signal was caught before any data was transferred (see sigvector(2).
[EDEADLK] A resource deadlock would occur as a result of this operation (see lockf(2) and fcntl(2)).
[EDQUOT] User’s disk quota block limit has been reached for this file system.
[EAGAIN] Enforcement-mode file and record locking was set, O_NDELAY was set, and there was a blocking record lock.
[ENOLCK] The system record lock table is full, preventing the write from sleeping until the blocking record lock is removed.
[EIO] The process is in a background process group and is attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring or blocking the SIGTTOU signal, and the process group of the process is orphaned.
[EIO] An I/O error occurred while writing to the device corresponding to fildes.
[ENOSPC] Not enough space on the file system.
In addition, writev() might return one of the following errors:
[EFAULT] iov_base or iov points outside of the allocated address space. The reliable detection of this error is implementation dependent.
[EINVAL] iovcnt is less than or equal to 0, or greater than MAXIOV.
[EINVAL] One of the iov_len values in the iov array was negative.
[EINVAL] The sum of iov_len values in the iov array overflowed a 32-bit integer.
write() or writev() fails, the file offset is updated to reflect the amount of data transferred, and errno is set accordingly if one of the following conditions is true:
[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).
[EFAULT] buf points outside the process’s allocated address space. The reliable detection of this error is implementation dependent.
EXAMPLES
Assuming a process opened a file for writing, the following call to write(2) attempts to write mybufsize bytes to the file from the buffer to which mybuf points.
#include <string.h>
int mybufsize, nbytes, fildes;
char ∗mybuf = "aeiou and sometimes y";
mybufsize = strlen (mybuf);
nbytes = write (fildes, mybuf, mybufsize);
WARNINGS
Check all references to signal(5) for appropriateness on systems that support sigvector(2). sigvector(2) can affect the behavior described on this page.
Character special devices, and raw disks in particular, apply constraints on how write() can be used. See specific Section (7) manual entries for details on particular devices.
AUTHOR
write() was developed by HP, AT&T, and the University of California, Berkeley.
SEE ALSO
creat(2), dup(2), lockf(2), lseek(2), open(2), pipe(2), ulimit(2), ustat(2).
STANDARDS CONFORMANCE
write(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company — HP-UX Release 9.0: August 1992