man2/io_getevents.2

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