source: trunk/packages/xen-3.1/xen-3.1/tools/libaio/man/aio_cancel.3 @ 34

Last change on this file since 34 was 34, checked in by hartmans, 18 years ago

Add xen and xen-common

File size: 3.3 KB
Line 
1.TH aio_cancel 3 2002-09-12 "Linux 2.4" Linux AIO"
2.SH NAME
3aio_cancel - Cancel asynchronous I/O requests
4.SH SYNOPSYS
5.nf
6.B #include <errno.h>
7.sp
8.br
9.B #include <aio.h>
10.sp
11.br
12.BI "int aio_cancel (int fildes " , struct aiocb *aiocbp " )"
13.fi
14.SH DESCRIPTION
15When one or more requests are asynchronously processed, it might be
16useful in some situations to cancel a selected operation, e.g., if it
17becomes obvious that the written data is no longer accurate and would
18have to be overwritten soon.  As an example, assume an application, which
19writes data in files in a situation where new incoming data would have
20to be written in a file which will be updated by an enqueued request.
21The POSIX AIO implementation provides such a function, but this function
22is not capable of forcing the cancellation of the request.  It is up to the
23implementation to decide whether it is possible to cancel the operation
24or not.  Therefore using this function is merely a hint.
25.B "The libaio implementation does not implement the cancel operation in the"
26.B "POSIX libraries".
27.PP
28The
29.IR aio_cancel
30function can be used to cancel one or more
31outstanding requests.  If the
32.IR aiocbp
33parameter is
34.IR NULL
35, the
36function tries to cancel all of the outstanding requests which would process
37the file descriptor
38.IR fildes
39(i.e., whose
40.IR aio_fildes
41member
42is
43.IR fildes
44).  If
45.IR aiocbp is not
46.IR  NULL
47,
48.IR aio_cancel
49attempts to cancel the specific request pointed to by
50.IR aiocbp.
51
52For requests which were successfully canceled, the normal notification
53about the termination of the request should take place.  I.e., depending
54on the
55.IR "struct sigevent"
56object which controls this, nothing
57happens, a signal is sent or a thread is started.  If the request cannot
58be canceled, it terminates the usual way after performing the operation.
59After a request is successfully canceled, a call to
60.IR aio_error
61with
62a reference to this request as the parameter will return
63.B ECANCELED
64and a call to
65.IR aio_return
66will return
67.IR -1.
68If the request wasn't canceled and is still running the error status is
69still
70.B EINPROGRESS.
71When the sources are compiled with
72.IR "_FILE_OFFSET_BITS == 64"
73, this
74function is in fact
75.IR aio_cancel64
76since the LFS interface
77transparently replaces the normal implementation.
78
79.SH "RETURN VALUES"
80.TP
81.B AIO_CANCELED
82If there were
83requests which haven't terminated and which were successfully canceled.
84.TP
85.B AIO_NOTCANCELED
86If there is one or more requests left which couldn't be canceled,
87.  In this case
88.IR aio_error
89must be used to find out which of the, perhaps multiple, requests (in
90.IR aiocbp
91is
92.IR NULL
93) weren't successfully canceled. 
94.TP
95.B AIO_ALLDONE
96If all
97requests already terminated at the time
98.IR aio_cancel
99is called the
100return value is
101.
102.SH ERRORS
103If an error occurred during the execution of
104.IR aio_cancel
105the
106function returns
107.IR -1
108and sets
109.IR errno
110to one of the following
111values.
112.TP
113.B EBADF
114The file descriptor
115.IR fildes
116is not valid.
117.TP
118.B ENOSYS
119.IR aio_cancel
120is not implemented.
121.SH "SEE ALSO"
122.BR aio(3),
123.BR aio_cancel64(3),
124.BR aio_error(3),
125.BR aio_error64(3),
126.BR aio_fsync(3),
127.BR aio_fsync64(3),
128.BR aio_init(3),
129.BR aio_read(3),
130.BR aio_read64(3),
131.BR aio_return(3),
132.BR aio_return64(3),
133.BR aio_suspend(3),
134.BR aio_suspend64(3),
135.BR aio_write(3),
136.BR aio_write64(3),
137.BR errno(3),
Note: See TracBrowser for help on using the repository browser.