aio(5)aio(5)NAMEaio - POSIX asynchronous I/O facility
SYNOPSISDESCRIPTION
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 Program
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 facil‐
ity is to allow a process or thread to overlap some elements of compu‐
tation and information processing with I/O processing.
Interface Functions
The POSIX Asynchronous I/O facility includes the following interface
functions:
Start an asynchronous read operation
Start an asynchronous write operation
Start a list of asynchronous I/O operations
Wait for completion of one or more asynchronous I/O operations
Retrieve the error status of an asynchronous I/O operation
Retrieve the return status of an asynchronous I/O operation
and free any associated system resources
Request cancellation of a pending asynchronous I/O operation
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 on
the compiler or linker command line.
Asynchronous I/O Control Block
The Asynchronous I/O Control Block is used as a parameter to all of the
asynchronous I/O functions. The specifies parameters for an asynchro‐
nous I/O operation in a call to or and then may be used as a "handle"
for the enqueued asynchronous I/O operation in a subsequent call to or
The structure contains the following members:
The supplied to or must contain the parameters that would be supplied
in a normal synchronous or function call, where corresponds to corre‐
sponds to and corresponds to the implicit file offset. The may also
specify a request priority delta value and signaling information to
satisfy unique realtime and asynchronous I/O requirements. For the
function, the field specifies whether the operation is a read or write.
Once an asynchronous I/O operation has been enqueued for a particular
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 structure are reserved for future use and
extension. They are all ignored by the asynchronous I/O facility.
Manifest Constants
Certain values as defined by the POSIX standard are declared in
The following values are returned by the function:
All specified asynchronous I/O operations were successfully
canceled.
At least one specified asynchronous I/O operations was not suc‐
cessfully
canceled.
All specified asynchronous I/O operations were
completed before the request was processed.
The following values are valid values of the field that controls return
from the function:
Wait for all specified operations to complete.
Return without waiting for operations to complete.
The following values are operation codes supplied in the field the des‐
ignate the type of an operation started with
The specifies an asynchronous read operation.
The specifies an asynchronous write operation.
The specifies no operation and is silently
ignored.
Enqueuing of Operations
If an error condition is detected that prevents an operation from being
started, and do not enqueue a request. Instead they immediately return
and set to indicate the cause of the failure. Once an operation has
been successfully enqueued, calls to and must be used to determine the
status of the operation and any error conditions, including those nor‐
mally reported by and The request remains enqueued and consumes process
and system resources until is called.
Error reporting of operations enqueued by may be less immediate than
that of operations enqueued by and With the exception of resource
shortages, errors for which and would immediately return -1 and an
value do not cause to stop enqueuing the current or subsequent requests
in its list. Instead, partial success occurs. In this case, the
application must use to determine which operations in its list have
been enqueued and which resulted in errors.
Asynchronous I/O operations are said to be complete when one of the
following is true:
· The I/O transfer is performed successfully.
· An error is detected in one or more parameters of the
operation.
· The operation is canceled.
If a valid is specified in the used to start the operation, then that
signal is delivered when the operation completes.
Reading and Writing Asynchronously
Asynchronous read and write operations are started using the and inter‐
faces. The parameters for each operation are provided in the used to
start the operation. A list of pointers can be provided to the func‐
tion call, in which case the type (read or write) of the operation is
determined from the field of the Once started, the I/O operations may
proceed concurrently with execution of the process or thread that ini‐
tiated the operation.
With the implementation of HP-UX kernel threads, an application may
achieve asynchronous I/O behavior by using synchronous and functions
from independent threads within the process. However, the application
may have to implement many of the status management facilities provided
in the POSIX Asynchronous I/O facility.
Waiting for Completion
The POSIX Asynchronous I/O facility supports both polling and notifica‐
tion models. The polling model is implemented by repeatedly calling
the function to test the status of an operation. The notification
model is implemented by designating a in the used to start the opera‐
tion. The specified notification, if any, is then performed when the
operation completes.
The function allows the application to wait for completion of one or
more asynchronous I/O operations. A timeout may be set so that the
process can again execute and take appropriate recovery actions if the
expected operations do not complete as expected. If the references
multiple operations, return is made when any one of the operations com‐
pletes.
Retrieving Errors
Once an asynchronous I/O operation has been started, its status can be
tested with the and functions, which return the current status of a
referenced For a polling implementation, the function is used to check
the status until a completion status is seen; then is used to free the
for re-use.
For a notification implementation, status of the completed I/O can be
determined and the freed with a single call to
The errors reported by and include all of the errors normally reported
by and plus errors unique to asynchronous I/O processing. After an
asynchronous I/O operation is started but before an error is detected
or the operation completes successfully, will return
Cancellation
The function allows an application to request cancellation of an asyn‐
chronous I/O operation. The used to start the operation may be used as
a handle to identify it for cancellation. Cancellation of all opera‐
tions pending for a file may also be requested. Not all asynchronous
I/O operations can be canceled.
Synchronizing Permanent Storage
The function supports synchronizing the contents of permanent storage
when multiple asynchronous I/O operations are outstanding for the file
or device. Only those requests already enqueued for the designated
file at the time of the function call are included in the synchroniza‐
tion operation.
File Offsets
Asynchronous I/O operations are not inherently sequential. Each opera‐
tion must specify an offset, and the file offset is never updated as a
result of an asynchronous I/O operation.
Setting the flag on a file limits the value of asynchronous I/O to that
file. When is set, operations on the file will be handled serially
with the ending file length after one request providing the starting
offset for the next. While there may be some advantage to allowing the
system to queue requests, care should be taken not to exhaust system or
process resources by enqueuing a large number of requests that must be
processed serially.
System Limitations and Restrictions
The operation of the POSIX Asynchronous I/O interfaces is subject to
certain system limitations and restrictions.
Since each enqueued asynchronous I/O operation requires allocation of
system memory for its internal control structure, the number of simul‐
taneously enqueued asynchronous I/O operations that the system can have
pending is limited. The maximum number of asynchronous I/O operations
that all active processes on the system may have enqueued concurrently
is tunable. The current maximum value can be obtained using the call
with the argument The default maximum value is 2048. In addition to
the system-wide limit, there is a per-process limit. It is controlled
using the argument to the and system calls. Even though an asynchro‐
nous I/O operation has completed, it still remains enqueued until is
called for that operation.
Asynchronous I/O operations which use the request and call back mecha‐
nism rather than the threads mechanism for I/O, are subject to a sys‐
tem-wide limit on the amount of physical memory that can be locked dur‐
ing asynchronous I/O transfers. This system-wide maximum number of
bytes of memory that can be locked simultaneously for aio requests is
tunable. This can be set as a percentage of the physical memory avail‐
able on the system. By default, it is set to 10% of the physical mem‐
ory. In addition to the system-wide limit, there is a per-process
limit which is controlled using the argument to the and system calls.
Further, the amount of memory that can be locked at a time for any rea‐
son, not just for asynchronous I/O, is controlled by the system-wide
limit Other system activity, including explicit memory locking with
and/or interfaces may affect the amount of lockable memory at any given
time.
The maximum priority change that can be specified in is limited. The
maximum priority change value is tunable. The current maximum value
can be obtained using the call with the argument The default value is
20.
The maximum number of asynchronous I/O operations that can be specified
in a single call is limited. This limit is tunable. The current maximum
value can be obtained using the call with the argument The default max‐
imum value is 256.
Some asynchronous I/O operations are also subject to both system-wide
and per-process limits on the number of simultaneously active threads.
See pthread(3T).
Programming Limitations and Restrictions
Altering the contents of or deallocating memory associated with the
referred to by or the buffer referred to by while an asynchronous read
operation is outstanding, that is has not been called for the may pro‐
duce unpredictable results.
EXAMPLES
The following code sequence illustrates an asynchronous read operation
and polling for completion.
SEE ALSOaio_cancel(2), aio_error(2), aio_fsync(2), aio_read(2), aio_return(2),
aio_suspend(2), aio_write(2), fsync(2), getrlimit(2), lio_listio(2),
read(2), write(2), pthread(3T).
STANDARDS CONFORMANCEaio(5)