aio_cancel or aio_cancel64 Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

aio_cancel or aio_cancel64 Subroutine

Purpose

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. If the aiocbp parameter is null, then an attempt is made to cancel all outstanding asynchronous I/O requests associated with the FileDescriptor parameter.

The aio_cancel64 subroutine is similar to the aio_cancel subroutine execpt 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 subroutine called with the handle to the corresponding aiocb structure returns ECANCELED.

Parameters

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. The aiocb structure is defined in the /usr/include/sys/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 Environment

The aio_cancel and aio_cancel64 subroutines can be called from the process environment only.

Return Values

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:

EBADF

Indicates that the FileDescriptor parameter is not valid.

Implementation Specifics

The aio_cancel or aio_cancel64 subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The aio_error or aio_error64 subroutine, aio_read or aio_read64 subroutine, aio_return or aio_return64 subroutine, aio_suspend or aio_suspend64 subroutine, aio_write or aio_write64 subroutine, lio_listio or lio_listo64 subroutine.

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

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