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