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,
                                 void *user_data,
                                 int flags);

       void io_uring_prep_cancel_fd(struct io_uring_sqe *sqe,
                                 int fd,
                                 int flags);

DESCRIPTION

       The  io_uring_prep_cancel(3) 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)  is  identical  to  io_uring_prep_cancel(3),  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) 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) sets up. Available since 5.19.

       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.

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_get_sqe(3), io_uring_submit(3)