bsd/man/man2/aio_read.2

   1 .\" Copyright (c) 1998 Terry Lambert
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/sys/aio_read.2,v 1.19 2003/01/14 02:37:06 tjr Exp $
  26 .\"
  27 .Dd November 17, 1998
  28 .Dt AIO_READ 2
  29 .Os
  30 .Sh NAME
  31 .Nm aio_read
  32 .Nd asynchronous read from a file (REALTIME)
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In aio.h
  37 .Ft int
  38 .Fo aio_read
  39 .Fa "struct aiocb *aiocbp"
  40 .Fc
  41 .Sh DESCRIPTION
  42 The
  43 .Fn aio_read
  44 system call allows the calling process to read
  45 .Fa aiocbp->aio_nbytes
  46 from the descriptor
  47 .Fa aiocbp->aio_fildes ,
  48 beginning at the offset
  49 .Fa aiocbp->aio_offset ,
  50 into the buffer pointed to by
  51 .Fa aiocbp->aio_buf .
  52 The call returns immediately after the read request has
  53 been enqueued to the descriptor;
  54 the read may or may not have completed at the time the call returns.
  55 .Pp
  56 If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it,
  57 then the enqueued operation is submitted at a priority equal to that
  58 of the calling process minus
  59 .Fa aiocbp->aio_reqprio .
  60 .Pp
  61 The
  62 .Fa aiocbp->aio_lio_opcode
  63 argument
  64 is ignored by the
  65 .Fn aio_read
  66 system call.
  67 .Pp
  68 The
  69 .Fa aiocbp
  70 pointer may be subsequently used as an argument to
  71 .Fn aio_return
  72 and
  73 .Fn aio_error
  74 in order to determine return or error status for the enqueued operation
  75 while it is in progress.
  76 .Pp
  77 If the request could not be enqueued (generally due to invalid arguments),
  78 then the call returns without having enqueued the request.
  79 .Pp
  80 If the request is successfully enqueued, the value of
  81 .Fa aiocbp->aio_offset
  82 can be modified during the request as context, so this value must
  83 not be referenced after the request is enqueued.
  84 .Sh RESTRICTIONS
  85 The Asynchronous I/O Control Block structure pointed to by
  86 .Fa aiocbp
  87 and the buffer that the
  88 .Fa aiocbp->aio_buf
  89 member of that structure references must remain valid until the
  90 operation has completed.  For this reason, use of auto (stack) variables
  91 for these objects is discouraged.
  92 .Pp
  93 The asynchronous I/O control buffer
  94 .Fa aiocbp
  95 should be zeroed before the
  96 .Fn aio_read
  97 call to avoid passing bogus context information to the kernel.
  98 .Pp
  99 Modifications of the Asynchronous I/O Control Block structure or the
 100 buffer contents after the request has been enqueued, but before the
 101 request has completed, are not allowed.
 102 .Pp
 103 If the file offset in
 104 .Fa aiocbp->aio_offset
 105 is past the offset maximum  for
 106 .Fa aiocbp->aio_fildes ,
 107 no I/O will occur.
 108 .Sh RETURN VALUES
 109 .Rv -std aio_read
 110 .Sh DIAGNOSTICS
 111 None.
 112 .Sh ERRORS
 113 The
 114 .Fn aio_read
 115 system call will fail if:
 116 .Bl -tag -width Er
 117 .\" ==========
 118 .It Bq Er EAGAIN
 119 Because of system resource limitations,
 120 the request was not queued.
 121 .\" ==========
 122 .It Bq Er ENOSYS
 123 The
 124 .Fn aio_read
 125 system call is not supported.
 126 .El
 127 .Pp
 128 The following conditions may be synchronously detected when the
 129 .Fn aio_read
 130 system call is made, or asynchronously, at any time thereafter.
 131 If they are detected at call time,
 132 .Fn aio_read
 133 returns -1 and sets
 134 .Va errno
 135 appropriately.
 136 Otherwise, the
 137 .Fn aio_return
 138 system call must be called.
 139 It will return -1;
 140 .Fn aio_error
 141 must then be called to determine the actual value
 142 that would have been returned in
 143 .Va errno .
 144 .Pp
 145 .Bl -tag -width Er
 146 .\" ==========
 147 .It Bq Er EBADF
 148 The
 149 .Fa aiocbp->aio_fildes
 150 argument
 151 is invalid.
 152 .\" ==========
 153 .It Bq Er EINVAL
 154 The offset
 155 .Fa aiocbp->aio_offset
 156 is not valid, the priority specified by
 157 .Fa aiocbp->aio_reqprio
 158 is not a valid priority, or the number of bytes specified by
 159 .Fa aiocbp->aio_nbytes
 160 is not valid.
 161 .\" ==========
 162 .It Bq Er EOVERFLOW
 163 The file is a regular file,
 164 .Fa aiocbp->aio_nbytes
 165 is greater than zero, the starting offset in
 166 .Fa aiocbp->aio_offset
 167 is before the end of the file, but is at or beyond the
 168 .Fa aiocbp->aio_fildes
 169 offset maximum.
 170 .El
 171 .Pp
 172 If the request is successfully enqueued, but subsequently cancelled
 173 or an error occurs, the value returned by the
 174 .Fn aio_return
 175 system call is per the
 176 .Xr read 2
 177 system call, and the value returned by the
 178 .Fn aio_error
 179 system call is either one of the error returns from the
 180 .Xr read 2
 181 system call, or one of:
 182 .Bl -tag -width Er
 183 .\" ==========
 184 .It Bq Er EBADF
 185 The
 186 .Fa aiocbp->aio_fildes
 187 argument
 188 is invalid for reading.
 189 .\" ==========
 190 .It Bq Er ECANCELED
 191 The request was explicitly cancelled via a call to
 192 .Fn aio_cancel .
 193 .\" ==========
 194 .It Bq Er EINVAL
 195 The offset
 196 .Fa aiocbp->aio_offset
 197 would be invalid.
 198 .El
 199 .Sh SEE ALSO
 200 .Xr aio_cancel 2 ,
 201 .Xr aio_error 2 ,
 202 .Xr aio_return 2 ,
 203 .Xr aio_suspend 2 ,
 204 .Xr aio_write 2 ,
 205 .Xr aio 4
 206 .Sh STANDARDS
 207 The
 208 .Fn aio_read
 209 system call is expected to conform to the
 210 .St -p1003.1
 211 standard.
 212 .Sh HISTORY
 213 The
 214 .Fn aio_read
 215 system call first appeared in
 216 .Fx 3.0 .
 217 .Sh AUTHORS
 218 This
 219 manual page was written by
 220 .An Terry Lambert Aq terry@whistle.com .
 221 .Sh BUGS
 222 Invalid information in
 223 .Fa aiocbp->_aiocb_private
 224 may confuse the kernel.