man3/aio_read.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH AIO_READ 3 2017-09-15  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 aio_read \- asynchronous read
  27 .SH SYNOPSIS
  28 .B "#include <aio.h>"
  29 .PP
  30 .BI "int aio_read(struct aiocb *" aiocbp );
  31 .PP
  32 Link with \fI\-lrt\fP.
  33 .SH DESCRIPTION
  34 The
  35 .BR aio_read ()
  36 function queues the I/O request described by the buffer pointed to by
  37 .IR aiocbp .
  38 This function is the asynchronous analog of
  39 .BR read (2).
  40 The arguments of the call
  41 .PP
  42     read(fd, buf, count)
  43 .PP
  44 correspond (in order) to the fields
  45 .IR aio_fildes ,
  46 .IR aio_buf ,
  47 and
  48 .IR aio_nbytes
  49 of the structure pointed to by
  50 .IR aiocbp .
  51 (See
  52 .BR aio (7)
  53 for a description of the
  54 .I aiocb
  55 structure.)
  56 .PP
  57 The data is read starting at the absolute position
  58 .IR aiocbp\->aio_offset ,
  59 regardless of the file offset.
  60 After the call,
  61 the value of the file offset is unspecified.
  62 .PP
  63 The "asynchronous" means that this call returns as soon as the
  64 request has been enqueued; the read may or may not have completed
  65 when the call returns.
  66 One tests for completion using
  67 .BR aio_error (3).
  68 The return status of a completed I/O operation can be obtained by
  69 .BR aio_return (3).
  70 Asynchronous notification of I/O completion can be obtained by setting
  71 .IR aiocbp\->aio_sigevent
  72 appropriately; see
  73 .BR sigevent (7)
  74 for details.
  75 .PP
  76 If
  77 .B _POSIX_PRIORITIZED_IO
  78 is defined, and this file supports it,
  79 then the asynchronous operation is submitted at a priority equal
  80 to that of the calling process minus
  81 .IR aiocbp\->aio_reqprio .
  82 .PP
  83 The field
  84 .I aiocbp\->aio_lio_opcode
  85 is ignored.
  86 .PP
  87 No data is read from a regular file beyond its maximum offset.
  88 .SH RETURN VALUE
  89 On success, 0 is returned.
  90 On error, the request is not enqueued, \-1
  91 is returned, and
  92 .I errno
  93 is set appropriately.
  94 If an error is detected only later, it will
  95 be reported via
  96 .BR aio_return (3)
  97 (returns status \-1) and
  98 .BR aio_error (3)
  99 (error status\(emwhatever one would have gotten in
 100 .IR errno ,
 101 such as
 102 .BR EBADF ).
 103 .SH ERRORS
 104 .TP
 105 .B EAGAIN
 106 Out of resources.
 107 .TP
 108 .B EBADF
 109 .I aio_fildes
 110 is not a valid file descriptor open for reading.
 111 .TP
 112 .B EINVAL
 113 One or more of
 114 .IR aio_offset ,
 115 .IR aio_reqprio ,
 116 or
 117 .I aio_nbytes
 118 are invalid.
 119 .TP
 120 .B ENOSYS
 121 .BR aio_read ()
 122 is not implemented.
 123 .TP
 124 .B EOVERFLOW
 125 The file is a regular file, we start reading before end-of-file
 126 and want at least one byte, but the starting position is past
 127 the maximum offset for this file.
 128 .SH VERSIONS
 129 The
 130 .BR aio_read ()
 131 function is available since glibc 2.1.
 132 .SH ATTRIBUTES
 133 For an explanation of the terms used in this section, see
 134 .BR attributes (7).
 135 .TS
 136 allbox;
 137 lb lb lb
 138 l l l.
 139 Interface       Attribute       Value
 140 T{
 141 .BR aio_read ()
 142 T}      Thread safety   MT-Safe
 143 .TE
 144 .SH CONFORMING TO
 145 POSIX.1-2001, POSIX.1-2008.
 146 .SH NOTES
 147 It is a good idea to zero out the control block before use.
 148 The control block must not be changed while the read operation
 149 is in progress.
 150 The buffer area being read into
 151 .\" or the control block of the operation
 152 must not be accessed during the operation or undefined results may occur.
 153 The memory areas involved must remain valid.
 154 .PP
 155 Simultaneous I/O operations specifying the same
 156 .I aiocb
 157 structure produce undefined results.
 158 .SH EXAMPLE
 159 See
 160 .BR aio (7).
 161 .SH SEE ALSO
 162 .BR aio_cancel (3),
 163 .BR aio_error (3),
 164 .BR aio_fsync (3),
 165 .BR aio_return (3),
 166 .BR aio_suspend (3),
 167 .BR aio_write (3),
 168 .BR lio_listio (3),
 169 .BR aio (7)