1 | .TH aio_cancel 3 2002-09-12 "Linux 2.4" Linux AIO" |
---|
2 | .SH NAME |
---|
3 | aio_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 |
---|
15 | When one or more requests are asynchronously processed, it might be |
---|
16 | useful in some situations to cancel a selected operation, e.g., if it |
---|
17 | becomes obvious that the written data is no longer accurate and would |
---|
18 | have to be overwritten soon. As an example, assume an application, which |
---|
19 | writes data in files in a situation where new incoming data would have |
---|
20 | to be written in a file which will be updated by an enqueued request. |
---|
21 | The POSIX AIO implementation provides such a function, but this function |
---|
22 | is not capable of forcing the cancellation of the request. It is up to the |
---|
23 | implementation to decide whether it is possible to cancel the operation |
---|
24 | or 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 |
---|
28 | The |
---|
29 | .IR aio_cancel |
---|
30 | function can be used to cancel one or more |
---|
31 | outstanding requests. If the |
---|
32 | .IR aiocbp |
---|
33 | parameter is |
---|
34 | .IR NULL |
---|
35 | , the |
---|
36 | function tries to cancel all of the outstanding requests which would process |
---|
37 | the file descriptor |
---|
38 | .IR fildes |
---|
39 | (i.e., whose |
---|
40 | .IR aio_fildes |
---|
41 | member |
---|
42 | is |
---|
43 | .IR fildes |
---|
44 | ). If |
---|
45 | .IR aiocbp is not |
---|
46 | .IR NULL |
---|
47 | , |
---|
48 | .IR aio_cancel |
---|
49 | attempts to cancel the specific request pointed to by |
---|
50 | .IR aiocbp. |
---|
51 | |
---|
52 | For requests which were successfully canceled, the normal notification |
---|
53 | about the termination of the request should take place. I.e., depending |
---|
54 | on the |
---|
55 | .IR "struct sigevent" |
---|
56 | object which controls this, nothing |
---|
57 | happens, a signal is sent or a thread is started. If the request cannot |
---|
58 | be canceled, it terminates the usual way after performing the operation. |
---|
59 | After a request is successfully canceled, a call to |
---|
60 | .IR aio_error |
---|
61 | with |
---|
62 | a reference to this request as the parameter will return |
---|
63 | .B ECANCELED |
---|
64 | and a call to |
---|
65 | .IR aio_return |
---|
66 | will return |
---|
67 | .IR -1. |
---|
68 | If the request wasn't canceled and is still running the error status is |
---|
69 | still |
---|
70 | .B EINPROGRESS. |
---|
71 | When the sources are compiled with |
---|
72 | .IR "_FILE_OFFSET_BITS == 64" |
---|
73 | , this |
---|
74 | function is in fact |
---|
75 | .IR aio_cancel64 |
---|
76 | since the LFS interface |
---|
77 | transparently replaces the normal implementation. |
---|
78 | |
---|
79 | .SH "RETURN VALUES" |
---|
80 | .TP |
---|
81 | .B AIO_CANCELED |
---|
82 | If there were |
---|
83 | requests which haven't terminated and which were successfully canceled. |
---|
84 | .TP |
---|
85 | .B AIO_NOTCANCELED |
---|
86 | If there is one or more requests left which couldn't be canceled, |
---|
87 | . In this case |
---|
88 | .IR aio_error |
---|
89 | must be used to find out which of the, perhaps multiple, requests (in |
---|
90 | .IR aiocbp |
---|
91 | is |
---|
92 | .IR NULL |
---|
93 | ) weren't successfully canceled. |
---|
94 | .TP |
---|
95 | .B AIO_ALLDONE |
---|
96 | If all |
---|
97 | requests already terminated at the time |
---|
98 | .IR aio_cancel |
---|
99 | is called the |
---|
100 | return value is |
---|
101 | . |
---|
102 | .SH ERRORS |
---|
103 | If an error occurred during the execution of |
---|
104 | .IR aio_cancel |
---|
105 | the |
---|
106 | function returns |
---|
107 | .IR -1 |
---|
108 | and sets |
---|
109 | .IR errno |
---|
110 | to one of the following |
---|
111 | values. |
---|
112 | .TP |
---|
113 | .B EBADF |
---|
114 | The file descriptor |
---|
115 | .IR fildes |
---|
116 | is not valid. |
---|
117 | .TP |
---|
118 | .B ENOSYS |
---|
119 | .IR aio_cancel |
---|
120 | is 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), |
---|