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

Technical Reference: Base Operating System and Extensions, Volume 1


aio_suspend or aio_suspend64 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. A thread can only use aio_suspend to suspend on requests that it has initiated. If a thread trys to suspend on requests that it did not initiate, aio_suspend will return -1 and set errno to EINVAL.

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.

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. The aiocb structure is defined in the 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
aio_handle_t      aio_handle

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.

Implementation Specifics

The aio_suspend or aio_suspend64 subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The aio_cancel or aio_cancel64 (aio_cancel or aio_cancel64 Subroutine) subroutine, aio_error or aio_error64 (aio_error or aio_error64 Subroutine) subroutine, aio_read or aio_read64 (aio_read or aio_read64 Subroutine) subroutine, aio_return or aio_return64 (aio_return or aio_return64 Subroutine) subroutine, aio_write or aio_write64 (aio_write or aio_write64 Subroutine) subroutine, lio_listio or lio_listo64 (lio_listio or lio_listio64 Subroutine) subroutine.

The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.1 Kernel Extensions and Device Support Programming Concepts.

The Input and Output Handling Programmer's Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.


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