man3p/aio_read.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "AIO_READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" aio_read
   4 .SH NAME
   5 aio_read \- asynchronous read from a file (\fBREALTIME\fP)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <aio.h>
   9 .br
  10 .sp
  11 int aio_read(struct aiocb *\fP\fIaiocbp\fP\fB); \fP
  12 \fB
  13 .br
  14 \fP
  15 .SH DESCRIPTION
  16 .LP
  17 The \fIaio_read\fP() function shall read \fIaiocbp\fP->\fIaio_nbytes\fP
  18 from the file associated with
  19 \fIaiocbp\fP->\fIaio_fildes\fP into the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP.
  20 The function call shall return
  21 when the read request has been initiated or queued to the file or
  22 device (even when the data cannot be delivered immediately).
  23 .LP
  24 If prioritized I/O is supported for this file, then the asynchronous
  25 operation shall be submitted at a priority equal to the
  26 scheduling priority of the process minus \fIaiocbp\fP->\fIaio_reqprio\fP.
  27 .LP
  28 The \fIaiocbp\fP value may be used as an argument to \fIaio_error\fP()
  29 and \fIaio_return\fP() in order to determine the error status and
  30 return status, respectively, of
  31 the asynchronous operation while it is proceeding. If an error condition
  32 is encountered during queuing, the function call shall
  33 return without having initiated or queued the request. The requested
  34 operation takes place at the absolute position in the file as
  35 given by \fIaio_offset\fP, as if \fIlseek\fP() were called immediately
  36 prior to the
  37 operation with an \fIoffset\fP equal to \fIaio_offset\fP and a \fIwhence\fP
  38 equal to SEEK_SET. After a successful call to
  39 enqueue an asynchronous I/O operation, the value of the file offset
  40 for the file is unspecified.
  41 .LP
  42 The \fIaiocbp\fP->\fIaio_lio_opcode\fP field shall be ignored by \fIaio_read\fP().
  43 .LP
  44 The \fIaiocbp\fP argument points to an \fBaiocb\fP structure. If the
  45 buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP or
  46 the control block pointed to by \fIaiocbp\fP becomes an illegal address
  47 prior to asynchronous I/O completion, then the behavior is
  48 undefined.
  49 .LP
  50 Simultaneous asynchronous operations using the same \fIaiocbp\fP produce
  51 undefined results.
  52 .LP
  53 If synchronized I/O is enabled on the file associated with \fIaiocbp\fP->\fIaio_fildes\fP,
  54 the behavior of this function shall
  55 be according to the definitions of synchronized I/O data integrity
  56 completion and synchronized I/O file integrity completion.
  57 .LP
  58 For any system action that changes the process memory space while
  59 an asynchronous I/O is outstanding to the address range being
  60 changed, the result of that action is undefined.
  61 .LP
  62 For regular files, no data transfer shall occur past the offset maximum
  63 established in the open file description associated with
  64 \fIaiocbp\fP->\fIaio_fildes\fP.
  65 .SH RETURN VALUE
  66 .LP
  67 The \fIaio_read\fP() function shall return the value zero to the calling
  68 process if the I/O operation is successfully queued;
  69 otherwise, the function shall return the value -1 and set \fIerrno\fP
  70 to indicate the error.
  71 .SH ERRORS
  72 .LP
  73 The \fIaio_read\fP() function shall fail if:
  74 .TP 7
  75 .B EAGAIN
  76 The requested asynchronous I/O operation was not queued due to system
  77 resource limitations.
  78 .sp
  79 .LP
  80 Each of the following conditions may be detected synchronously at
  81 the time of the call to \fIaio_read\fP(), or asynchronously.
  82 If any of the conditions below are detected synchronously, the \fIaio_read\fP()
  83 function shall return -1 and set \fIerrno\fP to
  84 the corresponding value. If any of the conditions below are detected
  85 asynchronously, the return status of the asynchronous
  86 operation is set to -1, and the error status of the asynchronous operation
  87 is set to the corresponding value.
  88 .TP 7
  89 .B EBADF
  90 The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor
  91 open for reading.
  92 .TP 7
  93 .B EINVAL
  94 The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would
  95 be invalid, \fIaiocbp\fP->\fIaio_reqprio\fP is
  96 not a valid value, or \fIaiocbp\fP->\fIaio_nbytes\fP is an invalid
  97 value.
  98 .sp
  99 .LP
 100 In the case that the \fIaio_read\fP() successfully queues the I/O
 101 operation but the operation is subsequently canceled or
 102 encounters an error, the return status of the asynchronous operation
 103 is one of the values normally returned by the \fIread\fP() function
 104 call. In addition, the error status of the asynchronous operation
 105 is set to one
 106 of the error statuses normally set by the \fIread\fP() function call,
 107 or one of the following
 108 values:
 109 .TP 7
 110 .B EBADF
 111 The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor
 112 open for reading.
 113 .TP 7
 114 .B ECANCELED
 115 The requested I/O was canceled before the I/O completed due to an
 116 explicit \fIaio_cancel\fP() request.
 117 .TP 7
 118 .B EINVAL
 119 The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would
 120 be invalid.
 121 .sp
 122 .LP
 123 The following condition may be detected synchronously or asynchronously:
 124 .TP 7
 125 .B EOVERFLOW
 126 The file is a regular file, \fIaiobcp\fP->\fIaio_nbytes\fP is greater
 127 than 0, and the starting offset in
 128 \fIaiobcp\fP->\fIaio_offset\fP is before the end-of-file and is at
 129 or beyond the offset maximum in the open file description
 130 associated with \fIaiocbp\fP->\fIaio_fildes\fP.
 131 .sp
 132 .LP
 133 \fIThe following sections are informative.\fP
 134 .SH EXAMPLES
 135 .LP
 136 None.
 137 .SH APPLICATION USAGE
 138 .LP
 139 The \fIaio_read\fP() function is part of the Asynchronous Input and
 140 Output option and need not be available on all
 141 implementations.
 142 .SH RATIONALE
 143 .LP
 144 None.
 145 .SH FUTURE DIRECTIONS
 146 .LP
 147 None.
 148 .SH SEE ALSO
 149 .LP
 150 \fIaio_cancel\fP() , \fIaio_error\fP() , \fIlio_listio\fP() , \fIaio_return\fP()
 151 , \fIaio_write\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP()
 152 , \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions
 153 volume of
 154 IEEE\ Std\ 1003.1-2001, \fI<aio.h>\fP
 155 .SH COPYRIGHT
 156 Portions of this text are reprinted and reproduced in electronic form
 157 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 158 -- Portable Operating System Interface (POSIX), The Open Group Base
 159 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 160 Electrical and Electronics Engineers, Inc and The Open Group. In the
 161 event of any discrepancy between this version and the original IEEE and
 162 The Open Group Standard, the original IEEE and The Open Group Standard
 163 is the referee document. The original Standard can be obtained online at
 164 http://www.opengroup.org/unix/online.html .