[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

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

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

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.

Related Information

aio_read or aio_read64 Subroutine, aio_write or aio_write64 Subroutine, and lio_listio or lio_listio64 Subroutine.

Legacy AIO aio_suspend Subroutine

Purpose

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

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:

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

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:

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.

Related Information

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.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]