# io_getevents

## NAME



           io_getevents - read asynchronous I/O events from the completion
           queue
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    
           Alternatively, Asynchronous I/O library (_libaio_ , _-laio_); see
           VERSIONS.
    


## SYNOPSIS



           **#include <linux/aio_abi.h>    **/* Definition of ***io_*** types */
           **#include <sys/syscall.h>      **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **int syscall(SYS_io_getevents, aio_context_t** _ctx_id_**,**
                       **long** _min_nr_**, long** _nr_**, struct io_event ***_events_**,**
                       **struct timespec ***_timeout_**);**
    
           _Note_ : glibc provides no wrapper for **io_getevents**(), necessitating
           the use of syscall(2).
    


## DESCRIPTION



           _Note_ : this page describes the raw Linux system call interface.
           The wrapper function provided by _libaio_ uses a different type for
           the _ctx_id_ argument.  See VERSIONS.
    
           The **io_getevents**() system call attempts to read at least _min_nr_
           events and up to _nr_ events from the completion queue of the AIO
           context specified by _ctx_id_.
    
           The _timeout_ argument specifies the amount of time to wait for
           events, and is specified as a relative timeout in a **timespec**(3)
           structure.
    
           The specified time will be rounded up to the system clock
           granularity and is guaranteed not to expire early.
    
           Specifying _timeout_ as NULL means block indefinitely until at least
           _min_nr_ events have been obtained.
    


## RETURN VALUE



           On success, **io_getevents**() returns the number of events read.
           This may be 0, or a value less than _min_nr_ , if the _timeout_
           expired.  It may also be a nonzero value less than _min_nr_ , if the
           call was interrupted by a signal handler.
    
           For the failure return, see VERSIONS.
    


## ERRORS



           **EFAULT** Either _events_ or _timeout_ is an invalid pointer.
    
           **EINTR** Interrupted by a signal handler; see signal(7).
    
           **EINVAL** _ctx_id_ is invalid.  _min_nr_ is out of range or _nr_ is out of
                  range.
    
           **ENOSYS io_getevents**() is not implemented on this architecture.
    


## VERSIONS



           You probably want to use the **io_getevents**() wrapper function
           provided by _libaio_.
    
           Note that the _libaio_ wrapper function uses a different type
           (_io_context_t_) for the _ctx_id_ argument.  Note also that the _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 syscall(2), then the return value follows the
           usual conventions for indicating an error: -1, with _errno_ set to a
           (positive) value that indicates the error.
    


## STANDARDS



           Linux.
    


## BUGS



           An invalid _ctx_id_ may cause a segmentation fault instead of
           generating the error **EINVAL**.
    


* * *