Technical Reference: Base Operating System and Extensions , Volume 2

write, writex, writev, writevx or pwrite Subroutines

Syntax

#include <unistd.h>

ssize_t write (FileDescriptor, Buffer, NBytes) int FileDescriptor; const void * Buffer; size_t NBytes;

int writex (FileDescriptor, Buffer, NBytes, Extension) int FileDescriptor; char *Buffer; unsigned int NBytes; int Extension;

#include <sys/uio.h>

ssize_t writev (FileDescriptor, iov, iovCount) int FileDescriptor; const struct iovec * iov; int iovCount;

int writevx (FileDescriptor, iov, iovCount, Extension)
int FileDescriptor;
struct iovec *iov;
int iovCount;
int  Extension;

ssize_t pwrite (FileDescriptor, Buffer, NBytes, Offset) int FileDescriptor; const void * Buffer; size_t NBytes; off_t Offset;

The write subroutine attempts to write the number of bytes of data specified by the NBytes parameter to the file associated with the FileDescriptor parameter from the buffer pointed to by the Buffer parameter.

The writev subroutine performs the same action but gathers the output data from the iovCount buffers specified by the array of iovec structures pointed to by the iov parameter. Each iovec entry specifies the base address and length of an area in memory from which data should be written. The writev subroutine always writes a complete area before proceeding to the next.

The writex and writevx subroutines are the same as the write and writev subroutines, respectively, with the addition of an Extension parameter, which is used when writing to some device drivers.

With regular files and devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file pointer. Upon return from the write subroutine, the file pointer increments by the number of bytes actually written.

With devices incapable of seeking, writing always takes place starting at the current position. The value of a file pointer associated with such a device is undefined.

If a write requests that more bytes be written than there is room for (for example, the ulimit or the physical end of a medium), only as many bytes as there is room for will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20. The next write of a non-zero number of bytes will give a failure return (except as noted below) and the implementation will generate a SIGXFSZ signal for the thread.

Fewer bytes can be written than requested if there is not enough room to satisfy the request. In this case the number of bytes written is returned. The next attempt to write a nonzero number of bytes is unsuccessful (except as noted in the following text). The limit reached can be either that set by the ulimit subroutine or the end of the physical medium.

Successful completion of a write subroutine clears the SetUserID bit (S_ISUID) of a file if all of the following are true:

The calling process does not have root user authority.
The effective user ID of the calling process does not match the user ID of the file.
The file is executable by the group (S_IXGRP) or other (S_IXOTH).

The write subroutine clears the SetGroupID bit (S_ISGID) if all of the following are true:

The calling process does not have root user authority.
The group ID of the file does not match the effective group ID or one of the supplementary group IDs of the process.
The file is executable by the owner (S_IXUSR) or others (S_IXOTH).

Note: Clearing of the SetUserID and SetGroupID bits can occur even if the write subroutine is unsuccessful, if file data was modified before the error was detected.

If the O_APPEND flag of the file status is set, the file offset is set to the end of the file prior to each write.

If the FileDescriptor parameter refers to a regular file whose file status flags specify O_SYNC, this is a synchronous update (as described in the open subroutine).

If the FileDescriptor parameter refers to a regular file that a process has opened with the O_DEFER file status flag set, the data and file size are not updated on permanent storage until a process issues an fsync subroutine or performs a synchronous update. If all processes that have the file open with the O_DEFER file status flag set close the file before a process issues an fsync subroutine or performs a synchronous update, the data and file size are not updated on permanent storage.

Write requests to a pipe (or first-in-first-out (FIFO)) are handled the same as a regular file with the following exceptions:

There is no file offset associated with a pipe; hence, each write request appends to the end of the pipe.
If the size of the write request is less than or equal to the value of the PIPE_BUF system variable (described in the pathconf routine), the write subroutine is guaranteed to be atomic. The data is not interleaved with data from other write processes on the same pipe. Writes of greater than PIPE_BUF bytes can have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NDELAY or O_NONBLOCK file status flags are set.
If the O_NDELAY and O_NONBLOCK file status flags are clear (the default), a write request to a full pipe causes the process to block until enough space becomes available to handle the entire request.
If the O_NDELAY file status flag is set, a write to a full pipe returns a 0.
If the O_NONBLOCK file status flag is set, a write to a full pipe returns a value of -1 and sets the errno global variable to EAGAIN.

When attempting to write to a character special file that supports nonblocking writes, such as a terminal, and no data can currently be written:

If the O_NDELAY and O_NONBLOCK flags are clear (the default), the write subroutine blocks until data can be written.
If the O_NDELAY flag is set, the write subroutine returns 0.
If the O_NONBLOCK flag is set, the write subroutine returns -1 and sets the errno global variable to EAGAIN if no data can be written.

When attempting to write to a regular file that supports enforcement-mode record locks, and all or part of the region to be written is currently locked by another process, the following can occur:

If the O_NDELAY and O_NONBLOCK file status flags are clear (the default), the calling process blocks until the lock is released.
If the O_NDELAY or O_NONBLOCK file status flag is set, then the write subroutine returns a value of -1 and sets the errno global variable to EAGAIN.

Note: The fcntl subroutine provides more information about record locks.

If fildes refers to a STREAM, the operation of write is determined by the values of the minimum and maximum nbyte range ("packet size") accepted by the STREAM. These values are determined by the topmost STREAM module. If nbyte falls within the packet size range, nbyte bytes will be written. If nbyte does not fall within the range and the minimum packet size value is 0, write will break the buffer into maximum packet size segments prior to sending the data downstream (the last segment may contain less than the maximum packet size). If nbyte does not fall within the range and the minimum value is non-zero, write will fail with errno set to ERANGE. Writing a zero-length buffer (nbyte is 0) to a STREAMS device sends 0 bytes with 0 returned. However, writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no message and 0 is returned. The process may issue I_SWROPT ioctl to enable zero-length messages to be sent across the pipe or FIFO.

When writing to a STREAM, data messages are created with a priority band of 0. When writing to a STREAM that is not a pipe or FIFO:

If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is full due to internal flow control conditions), write will block until data can be accepted.
If O_NONBLOCK is set and the STREAM cannot accept data, write will return -1 and set errno to EAGAIN.
If O_NONBLOCK is set and part of the buffer has been written while a condition in which the STREAM cannot accept additional data occurs, write will terminate and return the number of bytes written.

In addition, write and writev will fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno does not reflect the result of write or writev but reflects the prior error.

The writev function is equivalent to write, but gathers the output data from the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt - 1]. iovcnt is valid if greater than 0 and less than or equal to {IOV_MAX}, defined in limits.h.

Each iovec entry specifies the base address and length of an area in memory from which data should be written. The writev function will always write a complete area before proceeding to the next.

If fildes refers to a regular file and all of the iov_len members in the array pointed to by iov are 0, writev will return 0 and have no other effect. For other file types, the behaviour is unspecified.

If the sum of the iov_len values is greater than SSIZE_MAX, the operation fails and no data is transferred.

The behavior of an interrupted write subroutine depends on how the handler for the arriving signal was installed. The handler can be installed in one of two ways, with the following results:

If the handler was installed with an indication that subroutines should not be restarted, the write subroutine returns a value of -1 and sets the errno global variable to EINTR (even if some data was already written).
If the handler was installed with an indication that subroutines should be restarted, and:
- If no data had been written when the interrupt was handled, the write subroutine will not return a value (it is restarted).
- If data had been written when the interrupt was handled, this write subroutine returns the amount of data already written.

Note: A write to a regular file is not interruptible. Only writes to objects that may block indefinitely, such as FIFOs, sockets, and some devices, are generally interruptible.

The pwrite function performs the same action as write, except that it writes into a given position without changing the file pointer. The first three arguments to pwrite are the same as write with the addition of a fourth argument offset for the desired position inside the file.

Note: The pwrite64 subroutine applies to AIX 4.3 and later.

ssize_t pwrite64(int fd , const void *buf , size_t nbytes , off64_t offset)

The pwrite64 subroutine performs the same action as pwrite but the limit of offset to the maximum file size for the file associated with the fileDescriptor and DEV_OFF_MAX if the file associated with fileDescriptor is a block special or character special file.

Parameters

Buffer	Identifies the buffer containing the data to be written.
Extension	Provides communication with character device drivers that require additional information or return additional status. Each driver interprets the Extension parameter in a device-dependent way, either as a value or as a pointer to a communication area. Drivers must apply reasonable defaults when the Extension parameter value is 0.
FileDescriptor	Identifies the object to which the data is to be written.
iov	Points to an array of iovec structures, which identifies the buffers containing the data to be written. The iovec structure is defined in the sys/uio.h file and contains the following members: caddr_t iov_base; size_t iov_len;
iovCount	Specifies the number of iovec structures pointed to by the iov parameter.
NBytes	Specifies the number of bytes to write.

Return Values

Upon successful completion, the write, writex, writev, and writevx subroutines return the number of bytes that were actually written. The number of bytes written is never greater than the value specified by the NBytes parameter. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The write, writex, writev, and writevx subroutines are unsuccessful when one of the following is true:

EAGAIN	The O_NONBLOCK flag is set on this file and the process would be delayed in the write operation; or an enforcement-mode record lock is outstanding in the portion of the file that is to be written.
EBADF	The FileDescriptor parameter does not specify a valid file descriptor open for writing.
EDQUOT	New disk blocks cannot be allocated for the file because the user or group quota of disk blocks has been exhausted on the file system.
EFAULT	The Buffer parameter or part of the iov parameter points to a location outside of the allocated address space of the process.
EFBIG	(AIX 4.2 and later) An attempt was made to write a file that exceeds the process' file size limit or the maximum file size. If the user has set the environment variable XPG_SUS_ENV=ON prior to execution of the process, then the SIGXFSZ signal is posted to the process when exceeding the process' file size limit.
EINVAL	The file position pointer associated with the FileDescriptor parameter was negative; the iovCount parameter value was not between 1 and 16, inclusive; or one of the iov_len values in the iov array was negative or the sum overflowed a 32-bit integer.
EINVAL	The STREAM or multiplexer referenced by FileDescriptor is linked (directly or indirectly) downstream from a multiplexer.
EINTR	A signal was caught during the write operation, and the signal handler was installed with an indication that subroutines are not to be restarted.
EIO	An I/O error occurred while writing to the file system; or the process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the process group has no parent process.
ENOSPC	No free space is left on the file system containing the file.
ENXIO	A hangup occurred on the STREAM being written to.
EPIPE	An attempt was made to write to a file that is not opened for reading by any process, or to a socket of type SOCK_STREAM that is not connected to a peer socket; or an attempt was made to write to a pipe or FIFO that is not open for reading by any process. If this occurs, a SIGPIPE signal will also be sent to the process.
ERANGE	The transfer request size was outside the range supported by the STREAMS file associated with FileDescriptor.

The write, writex, writev, and writevx subroutines may be unsuccessful if the following is true:

ENXIO	A request was made of a nonexistent device, or the request was outside the capabilities of the device.
EFBIG	An attempt was made to write to a regular file where NBytes greater than zero and the starting offset is greater than or equal to the offset maximum established in the open file description associated with FileDescriptor.
EINVAL	The offset argument is invalid. The value is negative.
ESPIPE	fildes is associated with a pipe or FIFO.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The fcntl, dup, or dup2 subroutine, fsync subroutine, ioctl subroutine, lockfx subroutine, lseek subroutine, open, openx, or creat subroutine, pathconf subroutine, pipe subroutine, poll subroutine, select (select Subroutine) subroutine, ulimit (ulimit Subroutine) subroutine.

The limits.h file, unistd.h file.

The Input and Output Handling Programmer's Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.