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