aio_write(3)aio_write(3)NAMEaio_write - Queues a single asynchronous write request (P1003.1b)
SYNOPSIS
#include <aio.h>
int aio_write (
struct aiocb *aiocbp );
LIBRARY
Asynchronous I/O Library (libaio, libaio_raw)
PARAMETERS
A pointer to an aiocb structure.
DESCRIPTION
The aio_write function allows the calling process to asynchronously
write aiocbp->aio_nbytes to the file, raw disk partition, or connected
socket associated with aiocbp->aio_fildes from the buffer pointed to by
aiocbp->aio_buf.
The aio_write function issues a write request and returns, even when
the data cannot be written immediately. If the request cannot be initi‐
ated, the function returns with an error status. If an error condition
occurs during queuing, the function call returns without initiating the
queue request.
The aiocbp argument points to an asynchronous control block structure,
aiocb, used in the asynchronous I/O interfaces. The aiocb structure
contains asynchronous operation information, such as the number of
bytes for the write operation and the buffer containing the data to be
written to the file descriptor specified in the aio_fildes member of
the aiocb structure.
The aiocbp value can be used as an argument to the aio_error and
aio_write functions to determine the error or return status of the
asynchronous write operation.
The aiocb structure has the following members: aio_fildes; aio_offset;
*aio_buf; aio_nbytes; aio_reqprio; aio_sigevent; aio_lio_opcode
The aio_fildes member is the file descriptor (file, raw disk partition,
or connected socket) on which the asynchronous operation is to be per‐
formed.
If the file descriptor is for a file or raw disk partition and O_APPEND
is set for the file descriptor, write operations append to the file in
the same order as the calls were made. If O_APPEND is not set, the
requested operation takes place at the position in the file given by
aio_offset (as if the lseek function were called prior to the operation
with an offset equal to aio_offset and a whence set to SEEK_SET).
After any asynchronous I/O operation, aio_offset member is undefined
and must be set explicitly for every asynchronous I/O request.
The aio_nbytes and aio_buf members are the same as the nbyte and buf
arguments defined by the read, write, and fsync functions.
The aio_sigevent member of the aiocb structure defines the signal gen‐
erated when the I/O operation is complete. If aio_sigevent.sigev_notify
equals SIGEV_SIGNAL and aio_sigevent.sigev_signo is non-zero, a signal
is generated when the asynchronous write operation has completed.
The aio_lio_opcode and the aio_reqprio members are ignored by
aio_write().
Pending I/O operations are handled as follows: On close, _exit, or
exec, any I/O that was directed to a file system file, a tty device, or
a streams device is canceled. Any I/O that was directed to any raw
character device, excluding terminal and streams devices, is not can‐
celed. On fork, no asynchronous I/O is inherited.
RETURN VALUES
On an unsuccessful call, a value of -1 is returned and errno is set to
indicate the type of error that occurred.
ERRORS
The aio_write function fails under the following conditions: The
requested asynchronous I/O operation was not queued due to system
resource limitations. The aiocbp->aio_fildes argument is not a valid
file descriptor open for writing. The file offset value implied by
aiocbp->aio_offset would be invalid, or aiocbp->aio_nbytes is an
invalid value.
If the I/O operation is successfully queued, a value of 0 (zero) is
returned. After successful queuing of aio_write, return and error val‐
ues are the same as for a call to the write function. One of the fol‐
lowing additional errors may occur: The operation was canceled by
aio_cancel. The offset in aio_offset is invalid for the file speci‐
fied.
SEE ALSO
Functions: close(2), exec(2), _exit(2), fork(2), lseek(2), read(2),
write(2), aio_cancel(3), aio_error(3), aio_group_completion_np(3),
aio_read(3), aio_results_np(3), aio_suspend(3), aio_return(3), lio_lis‐
tio(3)
Guide to Realtime Programming
aio_write(3)