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