man2/io_getevents.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" This file is distributed according to the GNU General Public License.
   5 .\" %%%LICENSE_END
   6 .\"
   7 .TH IO_GETEVENTS 2 2017-09-15 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 io_getevents \- read asynchronous I/O events from the completion queue
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
  13 .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
  14 .PP
  15 .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
  16 .BI "                 struct io_event *" events \
  17 ", struct timespec *" timeout );
  18 .fi
  19 .PP
  20 .IR Note :
  21 There is no glibc wrapper for this system call; see NOTES.
  22 .SH DESCRIPTION
  23 .PP
  24 The
  25 .BR io_getevents ()
  26 system call
  27 attempts to read at least \fImin_nr\fP events and
  28 up to \fInr\fP events from the completion queue of the AIO context
  29 specified by \fIctx_id\fP.
  30 .PP
  31 The \fItimeout\fP argument specifies the amount of time to wait for events,
  32 and is specified as a relative timeout in a structure of the following form:
  33 .PP
  34 .in +4n
  35 .EX
  36 struct timespec {
  37     time_t tv_sec;      /* seconds */
  38     long   tv_nsec;     /* nanoseconds [0 .. 999999999] */
  39 };
  40 .EE
  41 .in
  42 .PP
  43 The specified time will be rounded up to the system clock granularity
  44 and is guaranteed not to expire early.
  45 .PP
  46 Specifying
  47 .I timeout
  48 as NULL means block indefinitely until at least
  49 .I min_nr
  50 events have been obtained.
  51 .SH RETURN VALUE
  52 On success,
  53 .BR io_getevents ()
  54 returns the number of events read.
  55 This may be 0, or a value less than
  56 .IR min_nr ,
  57 if the
  58 .I timeout
  59 expired.
  60 It may also be a nonzero value less than
  61 .IR min_nr ,
  62 if the call was interrupted by a signal handler.
  63 .PP
  64 For the failure return, see NOTES.
  65 .SH ERRORS
  66 .TP
  67 .B EFAULT
  68 Either \fIevents\fP or \fItimeout\fP is an invalid pointer.
  69 .TP
  70 .B EINTR
  71 Interrupted by a signal handler; see
  72 .BR signal (7).
  73 .TP
  74 .B EINVAL
  75 \fIctx_id\fP is invalid.
  76 \fImin_nr\fP is out of range or \fInr\fP is
  77 out of range.
  78 .TP
  79 .B ENOSYS
  80 .BR io_getevents ()
  81 is not implemented on this architecture.
  82 .SH VERSIONS
  83 .PP
  84 The asynchronous I/O system calls first appeared in Linux 2.5.
  85 .SH CONFORMING TO
  86 .PP
  87 .BR io_getevents ()
  88 is Linux-specific and should not be used in
  89 programs that are intended to be portable.
  90 .SH NOTES
  91 Glibc does not provide a wrapper function for this system call.
  92 You could invoke it using
  93 .BR syscall (2).
  94 But instead, you probably want to use the
  95 .BR io_getevents ()
  96 wrapper function provided by
  97 .\" http://git.fedorahosted.org/git/?p=libaio.git
  98 .IR libaio .
  99 .PP
 100 Note that the
 101 .I libaio
 102 wrapper function uses a different type
 103 .RI ( io_context_t )
 104 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
 105 .\" the system call.
 106 for the
 107 .I ctx_id
 108 argument.
 109 Note also that the
 110 .I libaio
 111 wrapper does not follow the usual C library conventions for indicating errors:
 112 on error it returns a negated error number
 113 (the negative of one of the values listed in ERRORS).
 114 If the system call is invoked via
 115 .BR syscall (2),
 116 then the return value follows the usual conventions for
 117 indicating an error: \-1, with
 118 .I errno
 119 set to a (positive) value that indicates the error.
 120 .SH BUGS
 121 An invalid
 122 .IR ctx_id
 123 may cause a segmentation fault instead of generating the error
 124 .BR EINVAL .
 125 .SH SEE ALSO
 126 .PP
 127 .BR io_cancel (2),
 128 .BR io_destroy (2),
 129 .BR io_setup (2),
 130 .BR io_submit (2),
 131 .BR aio (7),
 132 .BR time (7)
 133 .\" .SH AUTHOR
 134 .\" Kent Yoder.