aio_write - Queues a single asynchronous write request
(P1003.1b)
#include <aio.h>
int aio_write (
struct aiocb *aiocbp );
Asynchronous I/O Library (libaio, libaio_raw)
A pointer to an aiocb structure.
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 initiated, 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 performed.
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 generated 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 canceled. On
fork, no asynchronous I/O is inherited.
On an unsuccessful call, a value of -1 is returned and
errno is set to indicate the type of error that occurred.
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 values are the same as for a call to the
write function. One of the following additional errors may
occur: The operation was canceled by aio_cancel. The offset
in aio_offset is invalid for the file specified.
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_listio(3)
Guide to Realtime Programming
aio_write(3)
[ Back ] |
