io_getevents(2)

1IO_GETEVENTS(2)            Linux Programmer's Manual           IO_GETEVENTS(2)
2
3
4

NAME

6       io_getevents - read asynchronous I/O events from the completion queue
7

SYNOPSIS

9       #include <linux/aio_abi.h>    /* Definition of *io_* types */
10       #include <sys/syscall.h>      /* Definition of SYS_* constants */
11       #include <unistd.h>
12
13       int syscall(SYS_io_getevents, aio_context_t ctx_id,
14                   long min_nr, long nr, struct io_event *events,
15                   struct timespec *timeout);
16
17       Note:  glibc  provides no wrapper for io_getevents(), necessitating the
18       use of syscall(2).
19

DESCRIPTION

21       Note: this page describes the raw Linux  system  call  interface.   The
22       wrapper  function  provided  by  libaio  uses  a different type for the
23       ctx_id argument.  See NOTES.
24
25       The io_getevents() system call attempts to read at least min_nr  events
26       and up to nr events from the completion queue of the AIO context speci‐
27       fied by ctx_id.
28
29       The timeout argument specifies the amount of time to wait  for  events,
30       and  is specified as a relative timeout in a structure of the following
31       form:
32
33           struct timespec {
34               time_t tv_sec;      /* seconds */
35               long   tv_nsec;     /* nanoseconds [0 .. 999999999] */
36           };
37
38       The specified time will be rounded up to the system  clock  granularity
39       and is guaranteed not to expire early.
40
41       Specifying  timeout  as  NULL  means  block indefinitely until at least
42       min_nr events have been obtained.
43

RETURN VALUE

45       On success, io_getevents() returns the number of events read.  This may
46       be 0, or a value less than min_nr, if the timeout expired.  It may also
47       be a nonzero value less than min_nr, if the call was interrupted  by  a
48       signal handler.
49
50       For the failure return, see NOTES.
51

ERRORS

53       EFAULT Either events or timeout is an invalid pointer.
54
55       EINTR  Interrupted by a signal handler; see signal(7).
56
57       EINVAL ctx_id  is  invalid.   min_nr  is  out  of range or nr is out of
58              range.
59
60       ENOSYS io_getevents() is not implemented on this architecture.
61

VERSIONS

63       The asynchronous I/O system calls first appeared in Linux 2.5.
64

CONFORMING TO

66       io_getevents() is Linux-specific and should not  be  used  in  programs
67       that are intended to be portable.
68

NOTES

70       You  probably  want to use the io_getevents() wrapper function provided
71       by libaio.
72
73       Note that the libaio wrapper function uses a  different  type  (io_con‐
74       text_t)  for  the  ctx_id  argument.  Note also that the libaio wrapper
75       does not follow the usual C library conventions for indicating  errors:
76       on  error it returns a negated error number (the negative of one of the
77       values  listed  in  ERRORS).   If  the  system  call  is  invoked   via
78       syscall(2), then the return value follows the usual conventions for in‐
79       dicating an error: -1, with errno set to a (positive) value that  indi‐
80       cates the error.
81

BUGS

83       An  invalid ctx_id may cause a segmentation fault instead of generating
84       the error EINVAL.
85

COLOPHON

90       This page is part of release 5.13 of the Linux  man-pages  project.   A
91       description  of  the project, information about reporting bugs, and the
92       latest    version    of    this    page,    can     be     found     at
93       https://www.kernel.org/doc/man-pages/.
94
95
96
97Linux                             2021-03-22                   IO_GETEVENTS(2)