]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Free Software Foundation, Inc. |
2297bf0e | 2 | .\" |
d36c3a75 | 3 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
fea681da | 4 | .\" This file is distributed according to the GNU General Public License. |
d36c3a75 | 5 | .\" %%%LICENSE_END |
fea681da | 6 | .\" |
4b8c67d9 | 7 | .TH IO_GETEVENTS 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 8 | .SH NAME |
d12c1424 | 9 | io_getevents \- read asynchronous I/O events from the completion queue |
47297adb | 10 | .SH SYNOPSIS |
d12c1424 | 11 | .nf |
e1c5ebfa MK |
12 | .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" |
13 | .BR "#include <linux/time.h>" " /* Defines 'struct timespec' */" | |
dbfe9c70 | 14 | .PP |
c13182ef | 15 | .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , |
d12c1424 MK |
16 | .BI " struct io_event *" events \ |
17 | ", struct timespec *" timeout ); | |
d12c1424 | 18 | .fi |
dbfe9c70 | 19 | .PP |
45c99e3e MK |
20 | .IR Note : |
21 | There is no glibc wrapper for this system call; see NOTES. | |
47297adb | 22 | .SH DESCRIPTION |
fea681da | 23 | .PP |
e1c5ebfa | 24 | The |
60a90ecd | 25 | .BR io_getevents () |
e1c5ebfa | 26 | system call |
a8d55537 MK |
27 | attempts to read at least \fImin_nr\fP events and |
28 | up to \fInr\fP events from the completion queue of the AIO context | |
29 | specified by \fIctx_id\fP. | |
efeece04 | 30 | .PP |
e1c5ebfa | 31 | The \fItimeout\fP argument specifies the amount of time to wait for events, |
c5359783 | 32 | and is specified as a relative timeout in a structure of the following form: |
efeece04 | 33 | .PP |
c5359783 | 34 | .in +4n |
18ef2552 | 35 | .EX |
c5359783 MK |
36 | struct timespec { |
37 | time_t tv_sec; /* seconds */ | |
38 | long tv_nsec; /* nanoseconds [0 .. 999999999] */ | |
39 | }; | |
18ef2552 | 40 | .EE |
c5359783 | 41 | .in |
efeece04 | 42 | .PP |
c5359783 | 43 | The specified time will be rounded up to the system clock granularity |
001c2827 | 44 | and is guaranteed not to expire early. |
efeece04 | 45 | .PP |
c5359783 MK |
46 | Specifying |
47 | .I timeout | |
48 | as NULL means block indefinitely until at least | |
49 | .I min_nr | |
50 | events have been obtained. | |
47297adb | 51 | .SH RETURN VALUE |
c13182ef | 52 | On success, |
60a90ecd | 53 | .BR io_getevents () |
13ed138b MK |
54 | returns the number of events read. |
55 | This may be 0, or a value less than | |
56 | .IR min_nr , | |
57 | if the | |
58 | .I timeout | |
59 | expired. | |
0ebc88fc MK |
60 | It may also be a nonzero value less than |
61 | .IR min_nr , | |
62 | if the call was interrupted by a signal handler. | |
efeece04 | 63 | .PP |
24d2f49a | 64 | For the failure return, see NOTES. |
47297adb | 65 | .SH ERRORS |
fea681da | 66 | .TP |
c4e45390 MK |
67 | .B EFAULT |
68 | Either \fIevents\fP or \fItimeout\fP is an invalid pointer. | |
69 | .TP | |
3a66db4a MK |
70 | .B EINTR |
71 | Interrupted by a signal handler; see | |
72 | .BR signal (7). | |
73 | .TP | |
d12c1424 | 74 | .B EINVAL |
a8d55537 MK |
75 | \fIctx_id\fP is invalid. |
76 | \fImin_nr\fP is out of range or \fInr\fP is | |
fea681da | 77 | out of range. |
fea681da | 78 | .TP |
d12c1424 | 79 | .B ENOSYS |
60a90ecd MK |
80 | .BR io_getevents () |
81 | is not implemented on this architecture. | |
47297adb | 82 | .SH VERSIONS |
a1d5f77c | 83 | .PP |
e1c5ebfa | 84 | The asynchronous I/O system calls first appeared in Linux 2.5. |
47297adb | 85 | .SH CONFORMING TO |
fea681da | 86 | .PP |
60a90ecd | 87 | .BR io_getevents () |
8382f16d | 88 | is Linux-specific and should not be used in |
75b48e9d | 89 | programs that are intended to be portable. |
24d2f49a MK |
90 | .SH NOTES |
91 | Glibc does not provide a wrapper function for this system call. | |
e1c5ebfa MK |
92 | You could invoke it using |
93 | .BR syscall (2). | |
94 | But instead, you probably want to use the | |
95 | .BR io_getevents () | |
96 | wrapper function provided by | |
97 | .\" http://git.fedorahosted.org/git/?p=libaio.git | |
98 | .IR libaio . | |
efeece04 | 99 | .PP |
e1c5ebfa | 100 | Note that the |
24d2f49a | 101 | .I libaio |
e1c5ebfa MK |
102 | wrapper function uses a different type |
103 | .RI ( io_context_t ) | |
104 | .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare | |
105 | .\" the system call. | |
106 | for the | |
107 | .I ctx_id | |
108 | argument. | |
109 | Note also that the | |
110 | .I libaio | |
111 | wrapper does not follow the usual C library conventions for indicating errors: | |
24d2f49a MK |
112 | on error it returns a negated error number |
113 | (the negative of one of the values listed in ERRORS). | |
114 | If the system call is invoked via | |
115 | .BR syscall (2), | |
116 | then the return value follows the usual conventions for | |
117 | indicating an error: \-1, with | |
118 | .I errno | |
119 | set to a (positive) value that indicates the error. | |
46fccf2d MK |
120 | .SH BUGS |
121 | An invalid | |
122 | .IR ctx_id | |
78685d04 | 123 | may cause a segmentation fault instead of generating the error |
46fccf2d | 124 | .BR EINVAL . |
47297adb | 125 | .SH SEE ALSO |
fea681da | 126 | .PP |
60a90ecd | 127 | .BR io_cancel (2), |
c4e45390 MK |
128 | .BR io_destroy (2), |
129 | .BR io_setup (2), | |
1d7c4d16 | 130 | .BR io_submit (2), |
ff0c3278 | 131 | .BR aio (7), |
1d7c4d16 | 132 | .BR time (7) |
d12c1424 MK |
133 | .\" .SH AUTHOR |
134 | .\" Kent Yoder. |