io_getevents(2)

1io_getevents(2)               System Calls Manual              io_getevents(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10
11       Alternatively, Asynchronous I/O library (libaio, -laio); see VERSIONS.
12

SYNOPSIS

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

DESCRIPTION

26       Note: this page describes the raw Linux  system  call  interface.   The
27       wrapper  function  provided  by  libaio  uses  a different type for the
28       ctx_id argument.  See VERSIONS.
29
30       The io_getevents() system call attempts to read at least min_nr  events
31       and up to nr events from the completion queue of the AIO context speci‐
32       fied by ctx_id.
33
34       The timeout argument specifies the amount of time to wait  for  events,
35       and is specified as a relative timeout in a timespec(3) structure.
36
37       The  specified  time will be rounded up to the system clock granularity
38       and is guaranteed not to expire early.
39
40       Specifying timeout as NULL means  block  indefinitely  until  at  least
41       min_nr events have been obtained.
42

RETURN VALUE

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

ERRORS

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

VERSIONS

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

STANDARDS

75       Linux.
76

HISTORY

78       Linux 2.5.
79

BUGS

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