aio man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

aio(5)									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  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 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)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net