aio_suspend or aio_suspend64 Subroutine

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

Purpose

Waits for an asynchronous I/O request.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_suspend (list, nent,
 timeout)
const struct aiocb * const list[];
int nent;
const struct timespec *timeout;

Description

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.

Parameters

Item Description
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.

Execution Envrionment

The aio_suspend and aio_suspend64 subroutines can be called from the process environment only.

Return Values

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.

Error Codes

Item Description
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.

Purpose

Legacy AIO aio_suspend Subroutine

Suspends the calling process until one or more asynchronous I/O requests is completed.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

aio_suspend( count,  aiocbpa)
int count;
struct aiocb *aiocbpa[ ];

aio_suspend64( count,  aiocbpa)
int count;
struct aiocb64 *aiocbpa[ ];

Description

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.

Note: The _AIO_AIX_SOURCE macro used in aio.h must be defined when using aio.h to compile an aio application with the Legacy AIO function definitions. The default compile using the aio.h file is for an application with the POSIX AIO definitions. In the source file enter:
#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 

Parameters

Item Description
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.

aiocb Structure

The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:
struct aiocb
{
       int                 aio_whence;
       off_t               aio_offset;
       char                *aio_buf;
       ssize_t             aio_return;
       int                 aio_errno;
       size_t              aio_nbytes;
       union {
              int          reqprio;
              struct {
                     int   version:8;
                     int   priority:8;
                     int   cache_hint:16;
              } ext;
       } aio_u1;
       int                 aio_flag;
       int                 aio_iocpfd;
       aio_handle_t        aio_handle;
}

#define aio_reqprio        aio_u1.reqprio
#define aio_version        aio_u1.ext.version
#define aio_priority       aio_u1.ext.priority
#define aio_cache_hint     aio_u1.ext.cache_hint

Execution Envrionment

The aio_suspend and aio_suspend64 subroutines can be called from the process environment only.

Return Values

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:

Item Description
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.