ia64/xen-unstable

view tools/libaio/man/aio_cancel.3 @ 10736:2937703f0ed0

Added blktap support. Includes kernel driver (enabled as CONFIG_XEN_BLKDEV_TAP=y) and userspace tools. The userspace deamon (blktapctrl) is enabled by default when xend is activated. For further information on using and configuring blktap see tools/blktap/README.
author jchesterfield@dhcp92.uk.xensource.com
date Thu Jul 13 10:13:26 2006 +0100 (2006-07-13)
parents
children
line source
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.
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.
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),