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

liburing-2.2                                     March 12, 2022                          io_uring_prep_cancel(3)