original/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 2013-04-08 "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
  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
  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 The \fItimeout\fP argument specifies the amount of time to wait for events,
  31 where a NULL timeout waits until at least \fImin_nr\fP events
  32 have been seen.
  33 Note that \fItimeout\fP is relative.
  34 .SH RETURN VALUE
  35 On success,
  36 .BR io_getevents ()
  37 returns the number of events read: 0 if no events are
  38 available, or less than \fImin_nr\fP if the \fItimeout\fP has elapsed.
  39 For the failure return, see NOTES.
  40 .SH ERRORS
  41 .TP
  42 .B EFAULT
  43 Either \fIevents\fP or \fItimeout\fP is an invalid pointer.
  44 .TP
  45 .B EINVAL
  46 \fIctx_id\fP is invalid.
  47 \fImin_nr\fP is out of range or \fInr\fP is
  48 out of range.
  49 .TP
  50 .B EINTR
  51 Interrupted by a signal handler; see
  52 .BR signal (7).
  53 .TP
  54 .B ENOSYS
  55 .BR io_getevents ()
  56 is not implemented on this architecture.
  57 .SH VERSIONS
  58 .PP
  59 The asynchronous I/O system calls first appeared in Linux 2.5.
  60 .SH CONFORMING TO
  61 .PP
  62 .BR io_getevents ()
  63 is Linux-specific and should not be used in
  64 programs that are intended to be portable.
  65 .SH NOTES
  66 Glibc does not provide a wrapper function for this system call.
  67 You could invoke it using
  68 .BR syscall (2).
  69 But instead, you probably want to use the
  70 .BR io_getevents ()
  71 wrapper function provided by
  72 .\" http://git.fedorahosted.org/git/?p=libaio.git
  73 .IR libaio .
  74
  75 Note that the
  76 .I libaio
  77 wrapper function uses a different type
  78 .RI ( io_context_t )
  79 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  80 .\" the system call.
  81 for the
  82 .I ctx_id
  83 argument.
  84 Note also that the
  85 .I libaio
  86 wrapper does not follow the usual C library conventions for indicating errors:
  87 on error it returns a negated error number
  88 (the negative of one of the values listed in ERRORS).
  89 If the system call is invoked via
  90 .BR syscall (2),
  91 then the return value follows the usual conventions for
  92 indicating an error: \-1, with
  93 .I errno
  94 set to a (positive) value that indicates the error.
  95 .SH BUGS
  96 An invalid
  97 .IR ctx_id
  98 may cause a segmentation fault instead of generating the error
  99 .BR EINVAL .
 100 .SH SEE ALSO
 101 .PP
 102 .BR io_cancel (2),
 103 .BR io_destroy (2),
 104 .BR io_setup (2),
 105 .BR io_submit (2),
 106 .BR aio (7),
 107 .BR time (7)
 108 .\" .SH AUTHOR
 109 .\" Kent Yoder.
 110 .SH COLOPHON
 111 This page is part of release 3.79 of the Linux
 112 .I man-pages
 113 project.
 114 A description of the project,
 115 information about reporting bugs,
 116 and the latest version of this page,
 117 can be found at
 118 \%http://www.kernel.org/doc/man\-pages/.