# aio_read

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           aio_read — asynchronous read from a file
    


## SYNOPSIS



           #include <aio.h>
    
           int aio_read(struct aiocb *_aiocbp_);
    


## DESCRIPTION



           The _aio_read_() function shall read _aiocbp_ ->_aio_nbytes_ from the
           file associated with _aiocbp_ ->_aio_fildes_ into the buffer pointed to
           by _aiocbp_ ->_aio_buf_. The function call shall return when the read
           request has been initiated or queued to the file or device (even
           when the data cannot be delivered immediately).
    
           If prioritized I/O is supported for this file, then the
           asynchronous operation shall be submitted at a priority equal to a
           base scheduling priority minus _aiocbp_ ->_aio_reqprio_. If Thread
           Execution Scheduling is not supported, then the base scheduling
           priority is that of the calling process;
           otherwise, the base scheduling priority is that of the calling
           thread.
    
           The _aiocbp_ value may be used as an argument to _aio_error_() and
           _aio_return_() in order to determine the error status and return
           status, respectively, of the asynchronous operation while it is
           proceeding. If an error condition is encountered during queuing,
           the function call shall return without having initiated or queued
           the request. The requested operation takes place at the absolute
           position in the file as given by _aio_offset_ , as if _lseek_() were
           called immediately prior to the operation with an _offset_ equal to
           _aio_offset_ and a _whence_ equal to SEEK_SET.  After a successful
           call to enqueue an asynchronous I/O operation, the value of the
           file offset for the file is unspecified.
    
           The _aio_sigevent_ member specifies the notification which occurs
           when the request is completed.
    
           The _aiocbp_ ->_aio_lio_opcode_ field shall be ignored by _aio_read_().
    
           The _aiocbp_ argument points to an **aiocb** structure. If the buffer
           pointed to by _aiocbp_ ->_aio_buf_ or the control block pointed to by
           _aiocbp_ becomes an illegal address prior to asynchronous I/O
           completion, then the behavior is undefined.
    
           Simultaneous asynchronous operations using the same _aiocbp_ produce
           undefined results.
    
           If synchronized I/O is enabled on the file associated with
           _aiocbp_ ->_aio_fildes_ , the behavior of this function shall be
           according to the definitions of synchronized I/O data integrity
           completion and synchronized I/O file integrity completion.
    
           For any system action that changes the process memory space while
           an asynchronous I/O is outstanding to the address range being
           changed, the result of that action is undefined.
    
           For regular files, no data transfer shall occur past the offset
           maximum established in the open file description associated with
           _aiocbp_ ->_aio_fildes_.
    


## RETURN VALUE



           The _aio_read_() function shall return the value zero if the I/O
           operation is successfully queued; otherwise, the function shall
           return the value -1 and set _errno_ to indicate the error.
    


## ERRORS



           The _aio_read_() function shall fail if:
    
           **EAGAIN** The requested asynchronous I/O operation was not queued due
                  to system resource limitations.
    
           Each of the following conditions may be detected synchronously at
           the time of the call to _aio_read_(), or asynchronously. If any of
           the conditions below are detected synchronously, the _aio_read_()
           function shall return -1 and set _errno_ to the corresponding value.
           If any of the conditions below are detected asynchronously, the
           return status of the asynchronous operation is set to -1, and the
           error status of the asynchronous operation is set to the
           corresponding value.
    
           **EBADF** The _aiocbp_ ->_aio_fildes_ argument is not a valid file
                  descriptor open for reading.
    
           **EINVAL** The file offset value implied by _aiocbp_ ->_aio_offset_ would
                  be invalid,
                  _aiocbp_ ->_aio_reqprio_ is not a valid value, or
                  _aiocbp_ ->_aio_nbytes_ is an invalid value.
    
           In the case that the _aio_read_() successfully queues the I/O
           operation but the operation is subsequently canceled or encounters
           an error, the return status of the asynchronous operation is one
           of the values normally returned by the _read_() function call. In
           addition, the error status of the asynchronous operation is set to
           one of the error statuses normally set by the _read_() function
           call, or one of the following values:
    
           **EBADF** The _aiocbp_ ->_aio_fildes_ argument is not a valid file
                  descriptor open for reading.
    
           **ECANCELED**
                  The requested I/O was canceled before the I/O completed due
                  to an explicit _aio_cancel_() request.
    
           **EINVAL** The file offset value implied by _aiocbp_ ->_aio_offset_ would
                  be invalid.
    
           The following condition may be detected synchronously or
           asynchronously:
    
           **EOVERFLOW**
                  The file is a regular file, _aiobcp_ ->_aio_nbytes_ is greater
                  than 0, and the starting offset in _aiobcp_ ->_aio_offset_ is
                  before the end-of-file and is at or beyond the offset
                  maximum in the open file description associated with
                  _aiocbp_ ->_aio_fildes_.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *