| .TH aio_cancel 3 2002-09-12 "Linux 2.4" Linux AIO" |
| .SH NAME |
| aio_cancel - Cancel asynchronous I/O requests |
| .SH SYNOPSYS |
| .nf |
| .B #include <errno.h> |
| .sp |
| .br |
| .B #include <aio.h> |
| .sp |
| .br |
| .BI "int aio_cancel (int fildes " , struct aiocb *aiocbp " )" |
| .fi |
| .SH DESCRIPTION |
| 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. |
| .B "The libaio implementation does not implement the cancel operation in the" |
| .B "POSIX libraries". |
| .PP |
| The |
| .IR aio_cancel |
| function can be used to cancel one or more |
| outstanding requests. If the |
| .IR aiocbp |
| parameter is |
| .IR NULL |
| , the |
| function tries to cancel all of the outstanding requests which would process |
| the file descriptor |
| .IR fildes |
| (i.e., whose |
| .IR aio_fildes |
| member |
| is |
| .IR fildes |
| ). If |
| .IR aiocbp is not |
| .IR NULL |
| , |
| .IR aio_cancel |
| attempts to cancel the specific request pointed to by |
| .IR aiocbp. |
| |
| For requests which were successfully canceled, the normal notification |
| about the termination of the request should take place. I.e., depending |
| on the |
| .IR "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 |
| .IR aio_error |
| with |
| a reference to this request as the parameter will return |
| .B ECANCELED |
| and a call to |
| .IR aio_return |
| will return |
| .IR -1. |
| If the request wasn't canceled and is still running the error status is |
| still |
| .B EINPROGRESS. |
| When the sources are compiled with |
| .IR "_FILE_OFFSET_BITS == 64" |
| , this |
| function is in fact |
| .IR aio_cancel64 |
| since the LFS interface |
| transparently replaces the normal implementation. |
| |
| .SH "RETURN VALUES" |
| .TP |
| .B AIO_CANCELED |
| If there were |
| requests which haven't terminated and which were successfully canceled. |
| .TP |
| .B AIO_NOTCANCELED |
| If there is one or more requests left which couldn't be canceled, |
| . In this case |
| .IR aio_error |
| must be used to find out which of the, perhaps multiple, requests (in |
| .IR aiocbp |
| is |
| .IR NULL |
| ) weren't successfully canceled. |
| .TP |
| .B AIO_ALLDONE |
| If all |
| requests already terminated at the time |
| .IR aio_cancel |
| is called the |
| return value is |
| . |
| .SH ERRORS |
| If an error occurred during the execution of |
| .IR aio_cancel |
| the |
| function returns |
| .IR -1 |
| and sets |
| .IR errno |
| to one of the following |
| values. |
| .TP |
| .B EBADF |
| The file descriptor |
| .IR fildes |
| is not valid. |
| .TP |
| .B ENOSYS |
| .IR aio_cancel |
| is not implemented. |
| .SH "SEE ALSO" |
| .BR aio(3), |
| .BR aio_cancel64(3), |
| .BR aio_error(3), |
| .BR aio_error64(3), |
| .BR aio_fsync(3), |
| .BR aio_fsync64(3), |
| .BR aio_init(3), |
| .BR aio_read(3), |
| .BR aio_read64(3), |
| .BR aio_return(3), |
| .BR aio_return64(3), |
| .BR aio_suspend(3), |
| .BR aio_suspend64(3), |
| .BR aio_write(3), |
| .BR aio_write64(3), |
| .BR errno(3), |