iocancel

iocancel refers to the Linux asynchronous I/O cancellation operation, commonly seen in the libaio interface. It provides a mechanism to cancel a previously submitted asynchronous I/O request from an io_context_t. Programs submit I/O requests with io_submit, and may later cancel a pending request using io_cancel.

The function signature is int io_cancel(io_context_t ctx, struct iocb *iocb, struct io_event *result). It takes an I/O context, a pointer to the I/O control block describing the operation, and an optional result buffer to receive cancellation details. Return values are typically: 1 if the request was canceled, 0 if it could not be canceled (for example if it completed or could not be found), and -1 on error with errno set.

Cancellation behavior: If io_cancel succeeds, the operation is removed from the submission queue and the cancellation is reported to the caller, either directly or through a subsequent io_getevents call. Cancellation does not guarantee delivery of a normal completion event; canceled operations may follow a cancellation path depending on kernel and driver support. The exact delivery mechanism and timing can vary, and some I/O requests may not be cancelable depending on the device and file type.

Limitations and scope: io_cancel applies only to I/O requests submitted to a compatible Linux AIO context. Not all devices, file systems, or operations support cancellation, and there is no portable POSIX equivalent across all platforms. Behavior can vary with kernel version and libaio implementation, so software that relies on cancellation should handle multiple outcomes gracefully.

See also: Linux AIO, libaio, io_submit, io_getevents.