hpux man page for aio

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)