io_uring_prep_cancel(3) — Linux manual page

io_uring_prep_cancel(3)      liburing Manual     io_uring_prep_cancel(3)

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_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.

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)

COLOPHON

       This page is part of the liburing (A library for io_uring)
       project.  Information about the project can be found at 
       ⟨https://github.com/axboe/liburing⟩.  If you have a bug report for
       this manual page, send it to io-uring@vger.kernel.org.  This page
       was obtained from the project's upstream Git repository
       ⟨https://github.com/axboe/liburing⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-03.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

liburing-2.2                 March 12, 2022      io_uring_prep_cancel(3)

Pages that refer to this page: io_uring_prep_cancel(3), io_uring_prep_cancel64(3), io_uring_prep_cancel_fd(3), io_uring_prep_poll_remove(3), io_uring_register_sync_cancel(3)

---