The aio_suspend subroutine includes information for the POSIX AIO aio_suspend subroutine (as defined in the IEEE std 1003.1-2001), and the Legacy AIO aio_suspend subroutine.
POSIX AIO aio_suspend Subroutine
Waits for an asynchronous I/O request.
Standard C Library (libc.a)
#include <aio.h> int aio_suspend (list, nent, timeout) const struct aiocb * const list[]; int nent; const struct timespec *timeout;
The aio_suspend subroutine suspends the calling thread until at least one of the asynchronous I/O operations referenced by the list parameter has completed, until a signal interrupts the function, or, if timeout is not NULL, until the time interval specified by timeout has passed. If any of the aiocb structures in the list correspond to completed asynchronous I/O operations (the error status for the operation is not equal to EINPROGRESS) at the time of the call, the subroutine returns without suspending the calling thread. The list parameter is an array of pointers to asynchronous I/O control blocks. The nent parameter indicates the number of elements in the array. Each aiocb structure pointed to has been used in initiating an asynchronous I/O request through the aio_read, aio_write, or lio_listio subroutine. This array may contain NULL pointers, which are ignored. If this array contains pointers that refer to aiocb structures that have not been used in submitting asynchronous I/O, the effect is undefined.
If the time interval indicated in the timespec structure pointed to by timeout passes before any of the I/O operations referenced by list are completed, the aio_suspend subroutine returns with an error. If the Monotonic Clock option is supported, the clock that is used to measure this time interval is the CLOCK_MONOTONIC clock.
| list | Array of asynchronous I/O operations. |
| nent | Indicates the number of elements in the list array. |
| timeout | Specifies the time the subroutine has to complete the operation. |
The aio_suspend and aio_suspend64 subroutines can be called from the process environment only.
If the aio_suspend subroutine returns after one or more asynchronous I/O operations have completed, it returns a 0. Otherwise, it returns a -1 and sets the errno global variable to indicate the error.
The application can determine which asynchronous I/O completed by scanning the associated error and returning status using the aio_error and aio_return subroutines, respectively.
| EAGAIN | No asynchronous I/O indicated in the list referenced by list completed in the time interval indicated by timeout. |
| EINTR | A signal interrupted the aio_suspend subroutine. Since each asynchronous I/O operation may possibly provoke a signal when it completes, this error return may be caused by the completion of one (or more) of the very I/O operations being awaited. |
aio_read or aio_read64 Subroutine, aio_write or aio_write64 Subroutine, and lio_listio or lio_listio64 Subroutine.
Legacy AIO aio_suspend Subroutine
Suspends the calling process until one or more asynchronous I/O requests is completed.
Standard C Library (libc.a)
#include <aio.h>
aio_suspend( count, aiocbpa)
int count;
struct aiocb *aiocbpa[ ];
aio_suspend64( count, aiocbpa)
int count;
struct aiocb64 *aiocbpa[ ];
The aio_suspend subroutine suspends the calling process until one or more of the count parameter asynchronous I/O requests are completed or a signal interrupts the subroutine. Specifically, the aio_suspend subroutine handles requests associated with the aio control block (aiocb) structures pointed to by the aiocbpa parameter.
The aio_suspend64 subroutine is similar to the aio_suspend subroutine except that it takes an array of pointers to aiocb64 structures. This allows the aio_suspend64 subroutine to suspend on asynchronous I/O requests submitted by either the aio_read64, aio_write64, or the lio_listio64 subroutines.
In the large file enabled programming environment, aio_suspend is redefined to be aio_suspend64.
The array of aiocb pointers may include null pointers, which will be ignored. If one of the I/O requests is already completed at the time of the aio_suspend call, the call immediately returns.
#define _AIO_AIX_SOURCE #include <sys/aio.h>or, on the command line when compiling enter:
->xlc ... -D_AIO_AIX_SOURCE ... legacy_aio_program.c
| count | Specifies the number of entries in the aiocbpa array. |
| aiocbpa | Points to the aiocb or aiocb64 structures associated with the asynchronous I/O operations. |
The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:
int aio_whence off_t aio_offset char *aio_buf size_t aio_nbytes int aio_reqprio struct event aio_event struct osigevent aio_event int aio_flag aiohandle_t aio_handle
The aio_suspend and aio_suspend64 subroutines can be called from the process environment only.
If one or more of the I/O requests completes, the aio_suspend subroutine returns the index into the aiocbpa array of one of the completed requests. The index of the first element in the aiocbpa array is 0. If more than one request has completed, the return value can be the index of any of the completed requests.
In the event of an error, the aio_suspend subroutine returns a value of -1 and sets the errno global variable to identify the error. Return codes can be set to the following errno values:
| EINTR | Indicates that a signal or event interrupted the aio_suspend subroutine call. |
| EINVAL | Indicates that the aio_whence field does not have a valid value or that the resulting pointer is not valid. |
aio_cancel or aio_cancel64 Subroutine, aio_error or aio_error64 Subroutine, aio_read or aio_read64 Subroutine, aio_return or aio_return64 Subroutine, aio_write or aio_write64 Subroutine, and lio_listio or lio_listio64 Subroutine.
The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
The Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.