aio(5) File Formats Manual aio(5)
NAME
aio - POSIX asynchronous I/O facility
SYNOPSIS
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 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 notifica-
tion 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 computation 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 asyn-
chronous 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 successfully
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 designate 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 deter-
mine the status of the operation and any error conditions, including those normally reported by and The request remains enqueued and con-
sumes 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:
o The I/O transfer is performed successfully.
o An error is detected in one or more parameters of the operation.
o 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 interfaces. The parameters for each operation are provided in the used to
start the operation. A list of pointers can be provided to the function 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
initiated 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 pro-
vided in the POSIX Asynchronous I/O facility.
Waiting for Completion
The POSIX Asynchronous I/O facility supports both polling and notification 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 completes.
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 asynchronous I/O operation. The used to start the operation may be used
as a handle to identify it for cancellation. Cancellation of all operations pending for a file may also be requested. Not all asynchro-
nous 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 synchro-
nization operation.
File Offsets
Asynchronous I/O operations are not inherently sequential. Each operation 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
simultaneously 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 asynchronous 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 mechanism 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 during 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
available on the system. By default, it is set to 10% of the physical memory. 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
reason, 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 maximum 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 produce unpredictable results.
EXAMPLES
The following code sequence illustrates an asynchronous read operation and polling for completion.
SEE ALSO
aio_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 CONFORMANCE
aio(5)