HP-UX Reference (11i v3 07/02) - 5 Miscellaneous Topics (vol 9)

a
aio(5) aio(5)
NAME
aio - POSIX asynchronous I/O facility
SYNOPSIS
#include <aio.h>
DESCRIPTION
The POSIX Asynchronous I/O facility implements Section 6.7 of IEEE Standard 1003.1b-1993, Standard for
Information Technology, Portable Operating System Interface (POSIX), Part 1: System Application Pro-
gram Interface (API), Amendment 1: Realtime Extensions (C Language). It allows a process or thread to
start multiple simultaneous read and/or write operations to multiple files, to wait for or obtain notification
of completion of requested operations, and to retrieve the status of completed operations. The purpose of
the POSIX Asynchronous I/O facility is to allow a process or thread to overlap some elements of computa-
tion and information processing with I/O processing.
Interface Functions
The POSIX Asynchronous I/O facility includes the following interface functions:
aio_read() Start an asynchronous read operation
aio_write() Start an asynchronous write operation
lio_listio() Start a list of asynchronous I/O operations
aio_suspend()
Wait for completion of one or more asynchronous I/O operations
aio_error() Retrieve the error status of an asynchronous I/O operation
aio_return() Retrieve the return status of an asynchronous I/O operation and free any associated sys-
tem resources
aio_cancel() Request cancellation of a pending asynchronous I/O operation
aio_fsync() Request synchronization of the media image of a file to which asynchronous operations
have been addressed
To use these functions, link in the realtime library by specifying -lrt on the compiler or linker command
line.
Asynchronous I/O Control Block
The Asynchronous I/O Control Block (aiocb) is used as a parameter to all of the asynchronous I/O func-
tions. The aiocb specifies parameters for an asynchronous I/O operation in a call to
aio_read() ,
aio_write() ,orlio_listio() and then may be used as a "handle" for the enqueued asynchronous
I/O operation in a subsequent call to aio_cancel() , aio_suspend()
, aio_fsync() ,
aio_error() ,oraio_return() .
The aiocb structure contains the following members:
int aio_fildes; /* file descriptor */
off_t aio_offset; /* file offset */
void *aio_buf; /* location of buffer */
size_t aio_nbytes; /* length of transfer */
int aio_reqprio; /* request priority offset */
struct sigevent aio_sigevent; /* signal number and value */
int aio_lio_opcode; /* operation to be performed */
The aiocb supplied to aio_read() , aio_write() ,orlio_listio() must contain the parame-
ters that would be supplied in a normal synchronous read() or write() function call, where
aio_fildes corresponds to fildes, aio_nbytes corresponds to nbytes, and aio_offset
corresponds to the implicit file offset. The aiocb may also specify a request priority delta value
(aio_reqprio ), and signaling information to satisfy unique realtime and asynchronous I/O require-
ments. For the lio_listio() function, the aio_lio_opcode field specifies whether the operation is
a read or write.
Once an asynchronous I/O operation has been enqueued for a particular aiocb, its address is used as a
handle for other asynchronous I/O functions and can only be used to refer to a single enqueued operation.
Other fields defined in the aiocb structure are reserved for future use and extension. They are all
ignored by the asynchronous I/O facility.
38 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007