mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 18:21:39 +01:00
138 lines
3.3 KiB
Plaintext
138 lines
3.3 KiB
Plaintext
.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),
|