👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for aio (netbsd section 3)

AIO(3)				   BSD Library Functions Manual 			   AIO(3)

NAME
     aio -- asynchronous I/O (REALTIME)

LIBRARY
     POSIX Real-time Library (librt, -lrt)

SYNOPSIS
     #include <aio.h>

DESCRIPTION
     The IEEE Std 1003.1-2001 (``POSIX.1'') standard defines an interface for asynchronous input
     and output.  Although in NetBSD this is provided as part of the POSIX Real-time Library
     (librt, -lrt), the implementation largely resides in the kernel.

   Rationale
     The rationale can be roughly summarized with the following points.

       1.   To increase performance by providing a mechanism to carry out I/O without blocking.
	    Theoretically, if I/O would never block, neither at the software nor at the hardware
	    level, the overhead of I/O would become zero, and processes would no longer be I/O
	    bound.

       2.   To segregate the different I/O operations into logically distinctive procedures.
	    Unlike with the standard stdio(3), the aio interface separates queuing and submitting
	    I/O operations to the kernel, and receiving notifications of operation completion
	    from the kernel.

       3.   To provide an uniform and standardized framework for asynchronous I/O.  For instance,
	    aio avoids the need for (and the overhead of) extra worker threads sometimes used to
	    perform asynchronous I/O.

   Asynchronous I/O Control Block
     The Asynchronous I/O Control Block is the basic operational unit behind aio.  This is
     required since an arbitrary number of operations can be started at once, and because each
     operation can be either input or output.  This block is represented by the aiocb structure,
     which is defined in the <aio.h> header.  The following fields are available for user appli-
     cations:

	   off_t	    aio_offset;
	   void 	   *aio_buf;
	   size_t	    aio_nbytes;
	   int		    aio_fildes;
	   int		    aio_lio_opcode;
	   int		    aio_reqprio;
	   struct sigevent  aio_sigevent;

     The fields are:

	   1.	The aio_offset specifies the implicit file offset at which the I/O operations are
		performed.  This cannot be expected to be the actual read/write offset of the
		file descriptor.

	   2.	The aio_buf member is a pointer to the buffer to which data is going to be writ-
		ten or to which the read operation stores data.

	   3.	The aio_nbytes specifies the length of aio_buf.

	   4.	The aio_fildes specifies the used file descriptor.

	   5.	The aio_lio_opcode is used by the lio_listio() function to initialize a list of
		I/O requests with a single call.

	   6.	The aio_reqprio member can be used to lower the scheduling priority of an aio
		operation.  This is only available if _POSIX_PRIORITIZED_IO and
		_POSIX_PRIORITY_SCHEDULING are defined, and the associated file descriptor sup-
		ports it.

	   7.	The aio_sigevent member is used to specify how the calling process is notified
		once an aio operation completes.

     The members aio_buf, aio_fildes, and aio_nbytes are conceptually similar to the parameters
     'buf', 'fildes', and 'nbytes' used in the standard read(2) and write(2) functions.  For
     example, the caller can read aio_nbytes from a file associated with the file descriptor
     aio_fildes into the buffer aio_buf.  All appropriate fields should be initialized by the
     caller before aio_read() or aio_write() is called.

   File Offsets
     Asynchronous I/O operations are not strictly sequential; operations are carried out in arbi-
     trary order and more than one operation for one file descriptor can be started.  The
     requested read or write operation starts from the absolute position specified by aio_offset,
     as if lseek(2) would have been called with SEEK_SET immediately prior to the operation.  The
     POSIX standard does not specify what happens after an aio operation has been successfully
     completed.  Depending on the implementation, the actual file offset may or may not be
     updated.

   Errors and Completion
     Asynchronous I/O operations are said to be complete when:

       o   An error is detected.

       o   The I/O transfer is performed successfully.

       o   The operation is canceled.

     If an error condition is detected that prevents an operation from being started, the request
     is not enqueued.  In this case the read and write functions, aio_read() and aio_write(),
     return immediately, setting the global errno to indicate the cause of the error.

     After an operation has been successfully enqueued, aio_error() and aio_return() must be used
     to determine the status of the operation and to determine any error conditions.  This
     includes the conditions reported by the standard read(2), write(2), and fsync(2).	The
     request remains enqueued and consumes process and system resources until aio_return() is
     called.

   Waiting for Completion
     The aio interface supports both polling and notification models.  The first can be imple-
     mented by simply repeatedly calling the aio_error() function to test the status of an opera-
     tion.  Once the operation has completed, aio_return() is used to free the aiocb structure
     for re-use.

     The notification model is implemented by using the aio_sigevent member of the Asynchronous
     I/O Control Block.  The operational model and the used structure are described in
     sigevent(3).

     The aio_suspend() function can be used to wait for the completion of one or more operations.
     It is possible to set a timeout so that the process can continue the execution and take
     recovery actions if the aio operations do not complete as expected.

   Cancellation and Synchronization
     The aio_cancel() function can be used to request cancellation of an asynchronous I/O opera-
     tion.  Note however that not all of them can be canceled.	The same aiocb used to start the
     operation may be used as a handle for identification.  It is also possible to request can-
     cellation of all operations pending for a file.

     Comparable to fsync(2), the aio_fsync() function can be used to synchronize the contents of
     permanent storage when multiple asynchronous I/O operations are outstanding for the file or
     device.  The synchronization operation includes only those requests that have already been
     successfully enqueued.

FUNCTIONS
     The following functions comprise the API of the aio interface:

	   Function	   Description
	   aio_cancel(3)   cancel an outstanding asynchronous I/O operation
	   aio_error(3)    retrieve error status of asynchronous I/O operation
	   aio_fsync(3)    asynchronous data synchronization of file
	   aio_read(3)	   asynchronous read from a file
	   aio_return(3)   get return status of asynchronous I/O operation
	   aio_suspend(3)  suspend until operations or timeout complete
	   aio_write(3)    asynchronous write to a file
	   lio_listio(3)   list directed I/O

COMPATIBILITY
     Unfortunately, the POSIX asynchronous I/O implementations vary slightly.  Some implementa-
     tions provide a slightly different API with possible extensions.  For instance, the FreeBSD
     implementation uses a function 'aio_waitcomplete()' to wait for the next completion of an
     aio request.

STANDARDS
     The aio interface is expected to conform to the IEEE Std 1003.1-2001 (``POSIX.1'') standard.

HISTORY
     The aio interface first appeared in NetBSD 5.0.

CAVEATS
     Few limitations can be mentioned:

     o	 Undefined behavior results if simultaneous asynchronous operations use the same Asyn-
	 chronous I/O Control Block.

     o	 When an asynchronous read operation is outstanding, undefined behavior may follow if the
	 contents of aiocb are altered, or if memory associated with the structure, or the
	 aio_buf buffer, is deallocated.

BSD					   May 19, 2010 				      BSD


All times are GMT -4. The time now is 08:48 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?