| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
Single UNIX Specification, Version 2 |
both | OS/390 V2R7 |
#define _XOPEN_SOURCE 500
#include <aio.h>
int aio_cancel(int fildes, struct aiocb *aiocbp);The aio_cancel() function attempts to cancel one or more asynchronous I/O requests currently outstanding against file descriptor fildes. The aiocbp argument points to an aiocb structure for a particular request to be canceled or is NULL to cancel all outstanding cancelable requests against fildes.
Normal asynchronous notification occurs for asynchronous I/O operations that are successfully canceled. The associated error status is set to ECANCELED and the return status is set to -1 for the canceled requests.
For requests that cannot be canceled, the normal asynchronous completion process takes place when their I/O completes. In this case the aiocb is not modified by aio_cancel().
An asynchronous operation is cancelable if it is currently blocked or becomes blocked. Once an outstanding request can be completed it is allowed to complete. For example, an aio_read() will be cancelable if there is no data available at the time that aio_cancel() is called.
fildes must be a valid file descriptor, but when aiocbp is not NULL fildes does not have to match the file descriptor with which the asynchronous operation was initiated. For maximum portability, though, it should match.
The aio_cancel() function always waits for the request being canceled to either complete or be canceled. When control returns from aio_cancel(), the program may safely free the original request's aiocb and buffer. If a signal was specified on the original request, the signal handler for that request's I/O complete notification may run before, during, or after control returns from aio_cancel(), so coordination may be necessary between the signal handler and the caller of aio_cancel(). This is particularly unpredictable when aio_cancel() is called from a different thread than the original request, unless the original thread no longer exists.
Canceling all requests on a given descriptor does not stop new requests from being made or otherwise effect the descriptor. The program may start again or close the descriptor depending on why it issued the cancel.
An individual request can only be canceled once. Subsequent attempts to explicitly cancel the same request will fail with EALREADY.
In this case, the state of the other operations, if any, referenced in the call to aio_cancel() is not indicated by the return value of aio_cancel(). The application can determine the status of these operations by using aio_error().