| .\" Copyright (C) 2003 Free Software Foundation, Inc. |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" This file is distributed according to the GNU General Public License. |
| .\" %%%LICENSE_END |
| .\" |
| .TH IO_GETEVENTS 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| io_getevents \- read asynchronous I/O events from the completion queue |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" |
| .BR "#include <linux/time.h>" " /* Defines 'struct timespec' */" |
| .PP |
| .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr , |
| .BI " struct io_event *" events \ |
| ", struct timespec *" timeout ); |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .SH DESCRIPTION |
| .IR Note : |
| this page describes the raw Linux system call interface. |
| The wrapper function provided by |
| .I libaio |
| uses a different type for the |
| .I ctx_id |
| argument. |
| See NOTES. |
| .PP |
| The |
| .BR io_getevents () |
| system call |
| attempts to read at least \fImin_nr\fP events and |
| up to \fInr\fP events from the completion queue of the AIO context |
| specified by \fIctx_id\fP. |
| .PP |
| The \fItimeout\fP argument specifies the amount of time to wait for events, |
| and is specified as a relative timeout in a structure of the following form: |
| .PP |
| .in +4n |
| .EX |
| struct timespec { |
| time_t tv_sec; /* seconds */ |
| long tv_nsec; /* nanoseconds [0 .. 999999999] */ |
| }; |
| .EE |
| .in |
| .PP |
| The specified time will be rounded up to the system clock granularity |
| and is guaranteed not to expire early. |
| .PP |
| Specifying |
| .I timeout |
| as NULL means block indefinitely until at least |
| .I min_nr |
| events have been obtained. |
| .SH RETURN VALUE |
| On success, |
| .BR io_getevents () |
| returns the number of events read. |
| This may be 0, or a value less than |
| .IR min_nr , |
| if the |
| .I timeout |
| expired. |
| It may also be a nonzero value less than |
| .IR min_nr , |
| if the call was interrupted by a signal handler. |
| .PP |
| For the failure return, see NOTES. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| Either \fIevents\fP or \fItimeout\fP is an invalid pointer. |
| .TP |
| .B EINTR |
| Interrupted by a signal handler; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| \fIctx_id\fP is invalid. |
| \fImin_nr\fP is out of range or \fInr\fP is |
| out of range. |
| .TP |
| .B ENOSYS |
| .BR io_getevents () |
| is not implemented on this architecture. |
| .SH VERSIONS |
| The asynchronous I/O system calls first appeared in Linux 2.5. |
| .SH CONFORMING TO |
| .BR io_getevents () |
| is Linux-specific and should not be used in |
| programs that are intended to be portable. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call. |
| You could invoke it using |
| .BR syscall (2). |
| But instead, you probably want to use the |
| .BR io_getevents () |
| wrapper function provided by |
| .\" http://git.fedorahosted.org/git/?p=libaio.git |
| .IR libaio . |
| .PP |
| Note that the |
| .I libaio |
| wrapper function uses a different type |
| .RI ( io_context_t ) |
| .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare |
| .\" the system call. |
| for the |
| .I ctx_id |
| argument. |
| Note also that the |
| .I libaio |
| wrapper does not follow the usual C library conventions for indicating errors: |
| on error it returns a negated error number |
| (the negative of one of the values listed in ERRORS). |
| If the system call is invoked via |
| .BR syscall (2), |
| then the return value follows the usual conventions for |
| indicating an error: \-1, with |
| .I errno |
| set to a (positive) value that indicates the error. |
| .SH BUGS |
| An invalid |
| .IR ctx_id |
| may cause a segmentation fault instead of generating the error |
| .BR EINVAL . |
| .SH SEE ALSO |
| .BR io_cancel (2), |
| .BR io_destroy (2), |
| .BR io_setup (2), |
| .BR io_submit (2), |
| .BR aio (7), |
| .BR time (7) |
| .\" .SH AUTHOR |
| .\" Kent Yoder. |