original/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 2012-05-08  "" "Linux Programmer's Manual"
  25 .SH NAME
  26 aio_read \- asynchronous read
  27 .SH SYNOPSIS
  28 .B "#include <aio.h>"
  29 .sp
  30 .BI "int aio_read(struct aiocb *" aiocbp );
  31 .sp
  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
  42     read(fd, buf, count)
  43
  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 .LP
  57 The data is read starting at the absolute file offset
  58 .IR aiocbp\->aio_offset ,
  59 regardless of the current file offset.
  60 After the call,
  61 the value of the current file offset is unspecified.
  62 .LP
  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 .LP
  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 .LP
  83 The field
  84 .I aiocbp\->aio_lio_opcode
  85 is ignored.
  86 .LP
  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 CONFORMING TO
 133 POSIX.1-2001, POSIX.1-2008.
 134 .SH NOTES
 135 It is a good idea to zero out the control block before use.
 136 The control block must not be changed while the read operation
 137 is in progress.
 138 The buffer area being read into
 139 .\" or the control block of the operation
 140 must not be accessed during the operation or undefined results may occur.
 141 The memory areas involved must remain valid.
 142
 143 Simultaneous I/O operations specifying the same
 144 .I aiocb
 145 structure produce undefined results.
 146 .SH EXAMPLE
 147 See
 148 .BR aio (7).
 149 .SH SEE ALSO
 150 .BR aio_cancel (3),
 151 .BR aio_error (3),
 152 .BR aio_fsync (3),
 153 .BR aio_return (3),
 154 .BR aio_suspend (3),
 155 .BR aio_write (3),
 156 .BR lio_listio (3),
 157 .BR aio (7)
 158 .SH COLOPHON
 159 This page is part of release 3.79 of the Linux
 160 .I man-pages
 161 project.
 162 A description of the project,
 163 information about reporting bugs,
 164 and the latest version of this page,
 165 can be found at
 166 \%http://www.kernel.org/doc/man\-pages/.