aio_cancel or aio_cancel64 Subroutine

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

POSIX AIO aio_cancel Subroutine

Purpose

Cancels one or more outstanding asynchronous I/O requests.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

int aio_cancel (fildes, aiocbp)
int fildes;
struct aiocb *aiocbp;

Description

The aio_cancel subroutine cancels one or more asynchronous I/O requests currently outstanding against the fildes parameter. The aiocbp parameter points to the asynchronous I/O control block for a particular request to be canceled. If aiocbp is NULL, all outstanding cancelable asynchronous I/O requests against fildes are canceled.

Normal asynchronous notification occurs for asynchronous I/O operations that are successfully canceled. If there are requests that cannot be canceled, the normal asynchronous completion process takes place for those requests when they are completed.

For requested operations that are successfully canceled, the associated error status is set to ECANCELED, and a -1 is returned. For requested operations that are not successfully canceled, the aiocbp parameter is not modified by the aio_cancel subroutine.

If aiocbp is not NULL, and if fildes does not have the same value as the file descriptor with which the asynchronous operation was initiated, unspecified results occur.

The implementation of the subroutine defines which operations are cancelable.

Parameters

Item Description
fildes Identifies the object to which the outstanding asynchronous I/O requests were originally queued.
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_cancel and aio_cancel64 subroutines can be called from the process environment only.

Return Values

The aio_cancel subroutine returns AIO_CANCELED to the calling process if the requested operation(s) were canceled. AIO_NOTCANCELED is returned if at least one of the requested operations cannot be canceled because it is in progress. In this case, the state of the other operations, referenced in the call to aio_cancel is not indicated by the return value of aio_cancel. The application may determine the state of affairs for these operations by using the aio_error subroutine. AIO_ALLDONE is returned if all of the operations are completed. Otherwise, the subroutine returns -1 and sets the errno global variable to indicate the error.

Error Codes

Item Description
EBADF The fildes parameter is not a valid file descriptor.

Purpose

Legacy AIO aio_cancel Subroutine

Cancels one or more outstanding asynchronous I/O requests.

Library

Standard C Library (libc.a)

Syntax

#include <aio.h>

aio_cancel ( FileDescriptor,  aiocbp)
int FileDescriptor;
struct aiocb *aiocbp;

aio_cancel64 ( FileDescriptor,  aiocbp)
int FileDescriptor;
struct aiocb64 *aiocbp;

Description

The aio_cancel subroutine attempts to cancel one or more outstanding asynchronous I/O requests issued on the file associated with the FileDescriptor parameter. If the pointer to the aio control block (aiocb) structure (the aiocbp parameter) is not null, then an attempt is made to cancel the I/O request associated with this aiocb. The aiocbp parameter used by the thread calling aix_cancel must have had its request initiated by this same thread. Otherwise, a -1 is returned and errno is set to EINVAL. However, if the aiocbp parameter is null, then an attempt is made to cancel all outstanding asynchronous I/O requests associated with the FileDescriptor parameter without regard to the initiating thread.

The aio_cancel64 subroutine is similar to the aio_cancel subroutine except that it attempts to cancel outstanding large file enabled asynchronous I/O requests. Large file enabled asynchronous I/O requests make use of the aiocb64 structure instead of the aiocb structure. The aiocb64 structure allows asynchronous I/O requests to specify offsets in excess of OFF_MAX (2 gigbytes minus 1).

In the large file enabled programming environment, aio_cancel is redefined to be aio_cancel64.

When an I/O request is canceled, the aio_error (aio_error or aio_error64 Subroutine) subroutine called with the handle to the corresponding aiocb structure returns ECANCELED.

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
FileDescriptor Identifies the object to which the outstanding asynchronous I/O requests were originally queued.
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:
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_cancel and aio_cancel64 subroutines can be called from the process environment only.

Return Values

Item Description
AIO_CANCELED Indicates that all of the asynchronous I/O requests were canceled successfully. The aio_error subroutine call with the handle to the aiocb structure of the request will return ECANCELED.
AIO_NOTCANCELED Indicates that the aio_cancel subroutine did not cancel one or more outstanding I/O requests. This may happen if an I/O request is already in progress. The corresponding error status of the I/O request is not modified.
AIO_ALLDONE Indicates that none of the I/O requests is in the queue or in progress.
-1 Indicates that the subroutine was not successful. Sets the errno global variable to identify the error.

A return code can be set to the following errno value:

Item Description
EBADF Indicates that the FileDescriptor parameter is not valid.