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