aio_return or aio_return64 Subroutine

The aio_return or aio_return64 subroutine includes information for the POSIX AIO aio_return subroutine (as defined in the IEEE std 1003.1-2001), and the Legacy AIO aio_return subroutine.

POSIX AIO aio_return Subroutine

Purpose

Retrieves the return status of an asynchronous I/O operation.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

size_t aio_return (aiocbp);
struct aiocb *aiocbp;

Description

The aio_return subroutine returns the return status associated with the aiocb structure. The return status for an asynchronous I/O operation is the value that would be returned by the corresponding read, write, or fsync subroutine call. If the error status for the operation is equal to EINPROGRESS, the return status for the operation is undefined. The aio_return subroutine can be called once to retrieve the return status of a given asynchronous operation. After that, if the same aiocb structure is used in a call to aio_return or aio_error, an error may be returned. When the aiocb structure referred to by aiocbp is used to submit another asynchronous operation, the aio_return subroutine can be successfully used to retrieve the return status of that operation.

Parameters

Item Description
aiocbp Points to the aiocb structure associated with the I/O operation.

aiocb Structure

The aiocb structure is defined in the /usr/include/aio.h file and contains the following members:
int               aio_fildes
off_t             aio_offset
char             *aio_buf
size_t            aio_nbytes
int               aio_reqprio
struct sigevent   aio_sigevent
int               aio_lio_opcode

Execution Environment

The aio_return and aio_return64 subroutines can be called from the process environment only.

Return Values

If the asynchronous I/O operation has completed, the return status (as described for the read, write, and fsync subroutines) is returned. If the asynchronous I/O operation has not yet completed, the results of the aio_return subroutine are undefined.

Error Codes

Item Description
EINVAL The aiocbp parameter does not refer to an asynchronous operation whose return status has not yet been retrieved.

Purpose

Legacy AIO aio_return Subroutine

Retrieves the return status of an asynchronous I/O request.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h> 

int aio_return( handle)
aio_handle_t handle;

int aio_return64( handle)
aio_handle_t handle;

Description

The aio_return subroutine retrieves the return status of the asynchronous I/O request associated with the aio_handle_t handle if the I/O request has completed. The status returned is the same as the status that would be returned by the corresponding read or write function calls. If the I/O operation has not completed, the returned status is undefined.

The aio_return64 subroutine is similar to the aio_return subroutine except that it retrieves the error status associated with an aiocb64 control block.

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
handle The handle field of an aio control block (aiocb or aiocb64) structure is set by a previous call of the aio_read, aio_read64, aio_write, aio_write64, lio_listio, aio_listio64 subroutine. If a random memory location is passed in, random results are returned.

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 Environment

The aio_return and aio_return64 subroutines can be called from the process environment only.

Return Values

The aio_return subroutine returns the status of an asynchronous I/O request corresponding to those returned by read or write functions. If the error status returned by the aio_error subroutine call is EINPROG, the value returned by the aio_return subroutine is undefined.

Examples

An aio_read request to read 1000 bytes from a disk device eventually, when the aio_error subroutine returns a 0, causes the aio_return subroutine to return 1000. An aio_read request to read 1000 bytes from a 500 byte file eventually causes the aio_return subroutine to return 500. An aio_write request to write to a read-only file system results in the aio_error subroutine eventually returning EROFS and the aio_return subroutine returning a value of -1.