]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 2003 Free Software Foundation, Inc. |
2 | .\" This file is distributed according to the GNU General Public License. | |
3 | .\" See the file COPYING in the top level source directory for details. | |
4 | .\" | |
46fccf2d | 5 | .TH IO_GETEVENTS 2 2012-11-11 "Linux" "Linux Programmer's Manual" |
fea681da | 6 | .SH NAME |
d12c1424 | 7 | io_getevents \- read asynchronous I/O events from the completion queue |
fea681da | 8 | .SH "SYNOPSIS" |
d12c1424 | 9 | .nf |
e1c5ebfa MK |
10 | .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" |
11 | .BR "#include <linux/time.h>" " /* Defines 'struct timespec' */" | |
12 | ||
fea681da | 13 | .sp |
c13182ef | 14 | .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , |
d12c1424 MK |
15 | .BI " struct io_event *" events \ |
16 | ", struct timespec *" timeout ); | |
d12c1424 | 17 | .fi |
45c99e3e MK |
18 | |
19 | .IR Note : | |
20 | There is no glibc wrapper for this system call; see NOTES. | |
fea681da | 21 | .SH "DESCRIPTION" |
fea681da | 22 | .PP |
e1c5ebfa | 23 | The |
60a90ecd | 24 | .BR io_getevents () |
e1c5ebfa | 25 | system call |
a8d55537 MK |
26 | attempts to read at least \fImin_nr\fP events and |
27 | up to \fInr\fP events from the completion queue of the AIO context | |
28 | specified by \fIctx_id\fP. | |
e1c5ebfa | 29 | The \fItimeout\fP argument specifies the amount of time to wait for events, |
a8d55537 | 30 | where a NULL timeout waits until at least \fImin_nr\fP events |
c13182ef | 31 | have been seen. |
a8d55537 | 32 | Note that \fItimeout\fP is relative and will be updated if not NULL |
fea681da | 33 | and the operation blocks. |
fea681da | 34 | .SH "RETURN VALUE" |
c13182ef | 35 | On success, |
60a90ecd MK |
36 | .BR io_getevents () |
37 | returns the number of events read: 0 if no events are | |
24d2f49a MK |
38 | available, or less than \fImin_nr\fP if the \fItimeout\fP has elapsed. |
39 | For the failure return, see NOTES. | |
fea681da | 40 | .SH "ERRORS" |
fea681da | 41 | .TP |
c4e45390 MK |
42 | .B EFAULT |
43 | Either \fIevents\fP or \fItimeout\fP is an invalid pointer. | |
44 | .TP | |
d12c1424 | 45 | .B EINVAL |
a8d55537 MK |
46 | \fIctx_id\fP is invalid. |
47 | \fImin_nr\fP is out of range or \fInr\fP is | |
fea681da | 48 | out of range. |
fea681da | 49 | .TP |
359f6e5e MK |
50 | .B EINTR |
51 | Interrupted by a signal handler; see | |
52 | .BR signal (7). | |
53 | .TP | |
d12c1424 | 54 | .B ENOSYS |
60a90ecd MK |
55 | .BR io_getevents () |
56 | is not implemented on this architecture. | |
a1d5f77c MK |
57 | .SH "VERSIONS" |
58 | .PP | |
e1c5ebfa | 59 | The asynchronous I/O system calls first appeared in Linux 2.5. |
fea681da | 60 | .SH "CONFORMING TO" |
fea681da | 61 | .PP |
60a90ecd | 62 | .BR io_getevents () |
8382f16d | 63 | is Linux-specific and should not be used in |
75b48e9d | 64 | programs that are intended to be portable. |
24d2f49a MK |
65 | .SH NOTES |
66 | Glibc does not provide a wrapper function for this system call. | |
e1c5ebfa MK |
67 | You could invoke it using |
68 | .BR syscall (2). | |
69 | But instead, you probably want to use the | |
70 | .BR io_getevents () | |
71 | wrapper function provided by | |
72 | .\" http://git.fedorahosted.org/git/?p=libaio.git | |
73 | .IR libaio . | |
24d2f49a | 74 | |
e1c5ebfa | 75 | Note that the |
24d2f49a | 76 | .I libaio |
e1c5ebfa MK |
77 | wrapper function uses a different type |
78 | .RI ( io_context_t ) | |
79 | .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare | |
80 | .\" the system call. | |
81 | for the | |
82 | .I ctx_id | |
83 | argument. | |
84 | Note also that the | |
85 | .I libaio | |
86 | wrapper does not follow the usual C library conventions for indicating errors: | |
24d2f49a MK |
87 | on error it returns a negated error number |
88 | (the negative of one of the values listed in ERRORS). | |
89 | If the system call is invoked via | |
90 | .BR syscall (2), | |
91 | then the return value follows the usual conventions for | |
92 | indicating an error: \-1, with | |
93 | .I errno | |
94 | set to a (positive) value that indicates the error. | |
46fccf2d MK |
95 | .SH BUGS |
96 | An invalid | |
97 | .IR ctx_id | |
98 | may cause a segmentation fault instead of genenerating the error | |
99 | .BR EINVAL . | |
fea681da | 100 | .SH "SEE ALSO" |
fea681da | 101 | .PP |
60a90ecd | 102 | .BR io_cancel (2), |
c4e45390 MK |
103 | .BR io_destroy (2), |
104 | .BR io_setup (2), | |
1d7c4d16 | 105 | .BR io_submit (2), |
ff0c3278 | 106 | .BR aio (7), |
1d7c4d16 | 107 | .BR time (7) |
d12c1424 MK |
108 | .\" .SH AUTHOR |
109 | .\" Kent Yoder. |