1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
.\"/* io_getevents:
.\" * Attempts to read at least min_nr events and up to nr events from
.\" * the completion queue for the aio_context specified by ctx. May
.\" * fail with -EINVAL if ctx is invalid, if min_nr is out of range,
.\" * if nr is out of range, if when is out of range. May fail with
.\" * -EFAULT if any of the memory specified to is invalid. May return
.\" * 0 or < min_nr if no events are available and the timeout specified
.\" * by when has elapsed, where when == NULL specifies an infinite
.\" * timeout. Note that the timeout pointed to by when is relative and
.\" * will be updated if not NULL and the operation blocks. Will fail
.\" * with -ENOSYS if not implemented.
.\" */
.\"asmlinkage long sys_io_getevents(io_context_t ctx,
.\" long min_nr,
.\" long nr,
.\" struct io_event *events,
.\" struct timespec *timeout)
.\"
.TH io_getevents 3 2019-07-23 "Linux" "Linux AIO"
.SH NAME
io_getevents, aio_pgetevents \- Read resulting events from io requests
.SH SYNOPSIS
.nf
.B #include <errno.h>
.sp
.br
.B #include <libaio.h>
.br
.sp
struct iocb {
void *data;
unsigned key;
short aio_lio_opcode;
short aio_reqprio;
int aio_fildes;
};
.sp
struct io_event {
unsigned PADDED(data, __pad1);
unsigned PADDED(obj, __pad2);
unsigned PADDED(res, __pad3);
unsigned PADDED(res2, __pad4);
};
.sp
.BI "int io_getevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ");"
.BI "int io_pgetevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ", sigset_t *" sigmask ");"
.fi
.SH DESCRIPTION
Attempts to read up to
.I nr
events from the completion queue for the aio_context specified by
.IR ctx .
.SH "RETURN VALUES"
May return
.B 0
if no events are available and the timeout specified
by when has elapsed, where
.I when
== NULL specifies an infinite
timeout. Note that the timeout pointed to by when is relative and
will be updated if not NULL and the operation blocks. Will fail with
.B ENOSYS
if not implemented.
.SS io_pgetevents()
The relationship between
.BR io_getevents ()
and
.BR io_pgetevents ()
is analogous to the relationship between
.BR select (2)
and
.BR pselect (2):
similar to
.BR pselect (2),
.BR pgetevents ()
allows an application to safely wait until either an aio completion
event happens or until a signal is caught.
.PP
The following
.BR io_pgetevents ()
call:
.PP
.in +4n
.EX
ret = io_pgetevents(ctx, min_nr, nr, events, timeout, sigmask);
.EE
.in
.PP
is equivalent to
.I atomically
executing the following calls:
.PP
.in +4n
.EX
sigset_t origmask;
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ret = io_getevents(ctx, min_nr, nr, events, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
.PP
See the description of
.BR pselect (2)
for an explanation of why
.BR io_pgetevents ()
is necessary.
.PP
If the
.I sigmask
argument is specified as NULL, then no signal mask manipulation is
performed (and thus
.BR io_pgetevents ()
behaves the same as
.BR io_getevents() ).
.SH ERRORS
.TP
.B EINVAL
If
.I ctx
is invalid, if
.I min_nr
is out of range, if
.I nr
is out of range, if
.I when
is out of range.
.TP
.B EFAULT
If any of the memory specified to is invalid.
.SH "SEE ALSO"
.BR io (3),
.BR io_cancel (3),
.BR io_fsync (3),
.BR io_prep_fsync (3),
.BR io_prep_pread (3),
.BR io_prep_pwrite (3),
.BR io_queue_init (3),
.BR io_queue_release (3),
.BR io_queue_run (3),
.BR io_queue_wait (3),
.BR io_set_callback (3),
.BR io_submit (3),
.BR errno (3),
.BR pselect (2).
|
