GNU Info

(libc.info)Cancel AIO Operations

---

Next: Configuration of AIO Prev: Synchronizing AIO Operations Up: Asynchronous I/O

---

Enter node , (file) or (file)node

Cancellation of AIO Operations
------------------------------

   When one or more requests are asynchronously processed, it might be
useful in some situations to cancel a selected operation, e.g., if it
becomes obvious that the written data is no longer accurate and would
have to be overwritten soon.  As an example, assume an application,
which writes data in files in a situation where new incoming data would
have to be written in a file which will be updated by an enqueued
request.  The POSIX AIO implementation provides such a function, but
this function is not capable of forcing the cancellation of the
request.  It is up to the implementation to decide whether it is
possible to cancel the operation or not.  Therefore using this function
is merely a hint.

 - Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP)
     The `aio_cancel' function can be used to cancel one or more
     outstanding requests.  If the AIOCBP parameter is `NULL', the
     function tries to cancel all of the outstanding requests which
     would process the file descriptor FILDES (i.e., whose `aio_fildes'
     member is FILDES).  If AIOCBP is not `NULL', `aio_cancel' attempts
     to cancel the specific request pointed to by AIOCBP.

     For requests which were successfully canceled, the normal
     notification about the termination of the request should take
     place.  I.e., depending on the `struct sigevent' object which
     controls this, nothing happens, a signal is sent or a thread is
     started.  If the request cannot be canceled, it terminates the
     usual way after performing the operation.

     After a request is successfully canceled, a call to `aio_error'
     with a reference to this request as the parameter will return
     `ECANCELED' and a call to `aio_return' will return -1.  If the
     request wasn't canceled and is still running the error status is
     still `EINPROGRESS'.

     The return value of the function is `AIO_CANCELED' if there were
     requests which haven't terminated and which were successfully
     canceled.  If there is one or more requests left which couldn't be
     canceled, the return value is `AIO_NOTCANCELED'.  In this case
     `aio_error' must be used to find out which of the, perhaps
     multiple, requests (in AIOCBP is `NULL') weren't successfully
     canceled.  If all requests already terminated at the time
     `aio_cancel' is called the return value is `AIO_ALLDONE'.

     If an error occurred during the execution of `aio_cancel' the
     function returns -1 and sets `errno' to one of the following
     values.

    `EBADF'
          The file descriptor FILDES is not valid.

    `ENOSYS'
          `aio_cancel' is not implemented.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64', this
     function is in fact `aio_cancel64' since the LFS interface
     transparently replaces the normal implementation.

 - Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP)
     This function is similar to `aio_cancel' with the only difference
     that the argument is a reference to a variable of type `struct
     aiocb64'.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64', this
     function is available under the name `aio_cancel' and so
     transparently replaces the interface for small files on 32 bit
     machines.