---
name: "io_uring_prep_cancel"
section: "3"
platform: "linux"
package: "liburing"
version: "2.15-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/io_uring_prep_cancel"
---

# io\_uring\_prep\_cancel(3)

prepare a cancelation request

## NAME

io\_uring\_prep\_cancel - prepare a cancelation request

## SYNOPSIS

```
#include <liburing.h>
```

**void io\_uring\_prep\_cancel64(struct io\_uring\_sqe \****sqe***,**                             **\_\_u64** *user\_data***,**                             **int** *flags***);**

**void io\_uring\_prep\_cancel(struct io\_uring\_sqe \****sqe***,**                           **const void \****user\_data***,**                           **int** *flags***);**

**void io\_uring\_prep\_cancel\_fd(struct io\_uring\_sqe \****sqe***,**                           **int** *fd***,**                           **unsigned int** *flags***);**

## DESCRIPTION

The [**io\_uring\_prep\_cancel**(3)](/io_uring_prep_cancel/3.md) function prepares a cancelation request. The submission queue entry *sqe* is prepared to cancel an existing request identified by *user\_data*. For the *flags* argument, see below.

[**io\_uring\_prep\_cancel64**(3)](/io_uring_prep_cancel64/3.md) is identical to [**io\_uring\_prep\_cancel**(3)](/io_uring_prep_cancel/3.md)**,** except it takes a 64-bit integer rather than a pointer type.

The cancelation request will attempt to find the previously issued request identified by *user\_data* and cancel it. The identifier is what the previously issued request has in their *user\_data* field in the SQE.

The [**io\_uring\_prep\_cancel\_fd**(3)](/io_uring_prep_cancel_fd/3.md) function prepares a cancelation request. The submission queue entry *sqe* is prepared to cancel an existing request that used the file descriptor *fd*. For the *flags* argument, see below.

The cancelation request will attempt to find the previously issued request that used *fd* as the file descriptor and cancel it.

By default, the first request matching the criteria given will be canceled. This can be modified with any of the following flags passed in:

- **IORING\_ASYNC\_CANCEL\_ALL**

  Cancel all requests that match the given criteria, rather than just canceling the first one found. Available since 5.19.

- **IORING\_ASYNC\_CANCEL\_FD**

  Match based on the file descriptor used in the original request rather than the user\_data. This is what [**io\_uring\_prep\_cancel\_fd**(3)](/io_uring_prep_cancel_fd/3.md) sets up. Available since 5.19.

- **IORING\_ASYNC\_CANCEL\_FD\_FIXED**

  Set in conjunction with **IORING\_ASYNC\_CANCEL\_FD ,** indicating that the file descriptor given is a direct descriptor rather than a normal file descriptor. Available since 6.0.

- **IORING\_ASYNC\_CANCEL\_ANY**

  Match any request in the ring, regardless of user\_data or file descriptor. Can be used to cancel any pending request in the ring. Available since 5.19.

- **IORING\_ASYNC\_CANCEL\_USERDATA**

  Match request based on the user data field set in the original request. This is the default lookup key, if no other key matching has been specified. Available since 6.6.

- **IORING\_ASYNC\_CANCEL\_OP**

  Use the original request opcode as the matching key. The opcopde requested must be set in the sqe *len* field after using one of the generic cancel preparation helpers. Available since 6.6.

## RETURN VALUE

None

## ERRORS

These are the errors that are reported in the CQE *res* field. If no flags are used to cancel multiple requests, **0** is returned on success. If flags are used to match multiple requests, then a positive value is returned indicating how many requests were found and canceled.

- **-ENOENT**

  The request identified by *user\_data* could not be located. This could be because it completed before the cancelation request was issued, or if an invalid identifier is used.

- **-EINVAL**

  One of the fields set in the SQE was invalid.

- **-EALREADY**

  The execution state of the request has progressed far enough that cancelation is no longer possible. This should normally mean that it will complete shortly, either successfully, or interrupted due to the cancelation.

## NOTES

Although the cancelation request uses async request syntax, the kernel side of the cancelation is always run synchronously. It is guaranteed that a CQE is always generated by the time the cancel request has been submitted. If the cancelation is successful, the completion for the request targeted for cancelation will have been posted by the time submission returns. For **-EALREADY** it may take a bit of time to do so. For this case, the caller must wait for the canceled request to post its completion event.

## SEE ALSO

[**io\_uring\_prep\_poll\_remove**(3)](/io_uring_prep_poll_remove/3.md), [**io\_uring\_get\_sqe**(3)](/io_uring_get_sqe/3.md), [**io\_uring\_submit**(3)](/io_uring_submit/3.md)