aio_suspend or aio_suspend64 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

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

Legacy AIO aio_suspend Subroutine

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

Library (Legacy AIO aio_suspend Subroutine)

Standard C Library (libc.a)

Syntax (Legacy AIO aio_suspend Subroutine)

#include <aio.h>

Description (Legacy AIO aio_suspend Subroutine)

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>

->xlc ... -D_AIO_AIX_SOURCE ... legacy_aio_program.c 

Parameters (Legacy AIO aio_suspend Subroutine)

aiocb Structure

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 (Legacy AIO aio_suspend Subroutine)

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

Return Values (Legacy AIO aio_suspend Subroutine)

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: