# io_uring_prep_cancel_fd

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


* * *