original/man2/io_getevents.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\" This file is distributed according to the GNU General Public License.
   3 .\" See the file COPYING in the top level source directory for details.
   4 .\"
   5 .TH IO_GETEVENTS 2 2012-05-08 "Linux" "Linux Programmer's Manual"
   6 .SH NAME
   7 io_getevents \- read asynchronous I/O events from the completion queue
   8 .SH "SYNOPSIS"
   9 .nf
  10 .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
  11 .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
  12
  13 .sp
  14 .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
  15 .BI "                 struct io_event *" events \
  16 ", struct timespec *" timeout );
  17 .fi
  18 .SH "DESCRIPTION"
  19 .PP
  20 The
  21 .BR io_getevents ()
  22 system call
  23 attempts to read at least \fImin_nr\fP events and
  24 up to \fInr\fP events from the completion queue of the AIO context
  25 specified by \fIctx_id\fP.
  26 The \fItimeout\fP argument specifies the amount of time to wait for events,
  27 where a NULL timeout waits until at least \fImin_nr\fP events
  28 have been seen.
  29 Note that \fItimeout\fP is relative and will be updated if not NULL
  30 and the operation blocks.
  31 .SH "RETURN VALUE"
  32 On success,
  33 .BR io_getevents ()
  34 returns the number of events read: 0 if no events are
  35 available, or less than \fImin_nr\fP if the \fItimeout\fP has elapsed.
  36 For the failure return, see NOTES.
  37 .SH "ERRORS"
  38 .TP
  39 .B EFAULT
  40 Either \fIevents\fP or \fItimeout\fP is an invalid pointer.
  41 .TP
  42 .B EINVAL
  43 \fIctx_id\fP is invalid.
  44 \fImin_nr\fP is out of range or \fInr\fP is
  45 out of range.
  46 .TP
  47 .B EINTR
  48 Interrupted by a signal handler; see
  49 .BR signal (7).
  50 .TP
  51 .B ENOSYS
  52 .BR io_getevents ()
  53 is not implemented on this architecture.
  54 .SH "VERSIONS"
  55 .PP
  56 The asynchronous I/O system calls first appeared in Linux 2.5.
  57 .SH "CONFORMING TO"
  58 .PP
  59 .BR io_getevents ()
  60 is Linux-specific and should not be used in
  61 programs that are intended to be portable.
  62 .SH NOTES
  63 Glibc does not provide a wrapper function for this system call.
  64 You could invoke it using
  65 .BR syscall (2).
  66 But instead, you probably want to use the
  67 .BR io_getevents ()
  68 wrapper function provided by
  69 .\" http://git.fedorahosted.org/git/?p=libaio.git
  70 .IR libaio .
  71
  72 Note that the
  73 .I libaio
  74 wrapper function uses a different type
  75 .RI ( io_context_t )
  76 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  77 .\" the system call.
  78 for the
  79 .I ctx_id
  80 argument.
  81 Note also that the
  82 .I libaio
  83 wrapper does not follow the usual C library conventions for indicating errors:
  84 on error it returns a negated error number
  85 (the negative of one of the values listed in ERRORS).
  86 If the system call is invoked via
  87 .BR syscall (2),
  88 then the return value follows the usual conventions for
  89 indicating an error: \-1, with
  90 .I errno
  91 set to a (positive) value that indicates the error.
  92 .SH "SEE ALSO"
  93 .PP
  94 .BR io_cancel (2),
  95 .BR io_destroy (2),
  96 .BR io_setup (2),
  97 .BR io_submit (2),
  98 .BR aio (7),
  99 .BR time (7)
 100 .\" .SH AUTHOR
 101 .\" Kent Yoder.