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-11-11 "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
  19 .IR Note :
  20 There is no glibc wrapper for this system call; see NOTES.
  21 .SH "DESCRIPTION"
  22 .PP
  23 The
  24 .BR io_getevents ()
  25 system call
  26 attempts to read at least \fImin_nr\fP events and
  27 up to \fInr\fP events from the completion queue of the AIO context
  28 specified by \fIctx_id\fP.
  29 The \fItimeout\fP argument specifies the amount of time to wait for events,
  30 where a NULL timeout waits until at least \fImin_nr\fP events
  31 have been seen.
  32 Note that \fItimeout\fP is relative and will be updated if not NULL
  33 and the operation blocks.
  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 genenerating 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.