aio_error or aio_error64 Subroutine

Edit online

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

POSIX AIO aio_error Subroutine

Purpose

Retrieves error status for an asynchronous I/O operation.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_error (aiocbp)
const struct aiocb *aiocbp;

Description

The aio_error subroutine returns the error status associated with the aiocb structure. This structure is referenced by the aiocbp parameter. The error status for an asynchronous I/O operation is the synchronous I/O errno value that would be set by the corresponding read, write, or fsync subroutine. If the subroutine has not yet completed, the error status is equal to EINPROGRESS.

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_error and aio_error64 subroutines can be called from the process environment only.

Return Values

If the asynchronous I/O operation has completed successfully, the aio_error subroutine returns a 0. If unsuccessful, the error status (as described for the read, write, and fsync subroutines) is returned. If the asynchronous I/O operation has not yet completed, EINPROGRESS is returned.

Error Codes

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

Legacy AIO aio_error Subroutine

Purpose: Retrieves the error status of an asynchronous I/O request.

Library (Legacy AIO aio_error Subroutine)

Standard C Library (libc.a)

Syntax (Legacy AIO aio_error Subroutine)

#include <aio.h>

int aio_error(handle) aio_handle_t handle;

int aio_error64(handle) aio_handle_t handle;

Description (Legacy AIO aio_error Subroutine)

The aio_error subroutine retrieves the error status of the asynchronous request associated with the handle parameter. The error status is the errno value that would be set by the corresponding I/O operation. The error status is EINPROG if the I/O operation is still in progress.

The aio_error64 subroutine is similar to the aio_error 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 (Legacy AIO aio_error Subroutine)

Item	Description
handle	The handle field of an aio control block (aiocb or aiocb64) structure 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 (Legacy AIO aio_error Subroutine)

The aio_error and aio_error64 subroutines can be called from the process environment only.

Return Values (Legacy AIO aio_error Subroutine)

Item	Description
0	Indicates that the operation completed successfully.
ECANCELED	Indicates that the I/O request was canceled due to an aio_cancel subroutine call.
EINPROG	Indicates that the I/O request has not completed. An errno value described in the aio_read , aio_write, and lio_listio subroutines: Indicates that the operation was not queued successfully. For example, if the aio_read subroutine is called with an unusable file descriptor, it (aio_read) returns a value of -1 and sets the errno global variable to EBADF. A subsequent call of the aio_error subroutine with the handle of the unsuccessful aio control block (aiocb) structure returns EBADF. An errno value of the corresponding I/O operation: Indicates that the operation was initiated successfully, but the actual I/O operation was unsuccessful. For example, calling the aio_write subroutine on a file located in a full file system returns a value of 0, which indicates the request was queued successfully. However, when the I/O operation is complete (that is, when the aio_error subroutine no longer returns EINPROG), the aio_error subroutine returns ENOSPC. This indicates that the I/O was unsuccessful.

Item

Description

Indicates that the operation completed successfully.

ECANCELED

Indicates that the I/O request was canceled due to an aio_cancel subroutine call.

EINPROG

Indicates that the I/O request has not completed.

An errno value described in the aio_read , aio_write, and lio_listio subroutines: Indicates that the operation was not queued successfully. For example, if the aio_read subroutine is called with an unusable file descriptor, it (aio_read) returns a value of -1 and sets the errno global variable to EBADF. A subsequent call of the aio_error subroutine with the handle of the unsuccessful aio control block (aiocb) structure returns EBADF.

An errno value of the corresponding I/O operation: Indicates that the operation was initiated successfully, but the actual I/O operation was unsuccessful. For example, calling the aio_write subroutine on a file located in a full file system returns a value of 0, which indicates the request was queued successfully. However, when the I/O operation is complete (that is, when the aio_error subroutine no longer returns EINPROG), the aio_error subroutine returns ENOSPC. This indicates that the I/O was unsuccessful.