.\"/* 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).