lib/libc/sys/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$
  26 .\"
  27 .Dd January 2, 2021
  28 .Dt AIO_READ 2
  29 .Os
  30 .Sh NAME
  31 .Nm aio_read ,
  32 .Nm aio_readv
  33 .Nd asynchronous read from a file (REALTIME)
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In aio.h
  38 .Ft int
  39 .Fn aio_read "struct aiocb *iocb"
  40 .In sys/uio.h
  41 .Ft int
  42 .Fn aio_readv "struct aiocb *iocb"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn aio_read
  46 and
  47 .Fn aio_readv
  48 system calls allow the calling process to read
  49 from the descriptor
  50 .Fa iocb->aio_fildes
  51 beginning at the offset
  52 .Fa iocb->aio_offset .
  53 .Fn aio_read
  54 will read
  55 .Fa iocb->aio_nbytes
  56 from the buffer pointed to by
  57 .Fa iocb->aio_buf ,
  58 whereas
  59 .Fn aio_readv
  60 reads the data into the
  61 .Fa iocb->aio_iovcnt
  62 buffers specified by the members of the
  63 .Fa iocb->aio_iov
  64 array.
  65 Both syscalls return immediately after the read request has
  66 been enqueued to the descriptor; the read may or may not have
  67 completed at the time the call returns.
  68 .Pp
  69 For
  70 .Fn aio_readv
  71 the
  72 .Fa iovec
  73 structure is defined in
  74 .Xr readv 2 .
  75 .Pp
  76 If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it,
  77 then the enqueued operation is submitted at a priority equal to that
  78 of the calling process minus
  79 .Fa iocb->aio_reqprio .
  80 .Pp
  81 The
  82 .Fa iocb->aio_lio_opcode
  83 argument
  84 is ignored by the
  85 .Fn aio_read
  86 and
  87 .Fn aio_readv
  88 system calls.
  89 .Pp
  90 The
  91 .Fa iocb
  92 pointer may be subsequently used as an argument to
  93 .Fn aio_return
  94 and
  95 .Fn aio_error
  96 in order to determine return or error status for the enqueued operation
  97 while it is in progress.
  98 .Pp
  99 If the request could not be enqueued (generally due to invalid arguments),
 100 then the call returns without having enqueued the request.
 101 .Pp
 102 If the request is successfully enqueued, the value of
 103 .Fa iocb->aio_offset
 104 can be modified during the request as context, so this value must
 105 not be referenced after the request is enqueued.
 106 .Pp
 107 The
 108 .Fa iocb->aio_sigevent
 109 structure can be used to request notification of the operation's
 110 completion as described in
 111 .Xr aio 4 .
 112 .Sh RESTRICTIONS
 113 The Asynchronous I/O Control Block structure pointed to by
 114 .Fa iocb
 115 and the buffer that the
 116 .Fa iocb->aio_buf
 117 member of that structure references must remain valid until the
 118 operation has completed.
 119 .Pp
 120 The asynchronous I/O control buffer
 121 .Fa iocb
 122 should be zeroed before the
 123 .Fn aio_read
 124 call to avoid passing bogus context information to the kernel.
 125 .Pp
 126 Modifications of the Asynchronous I/O Control Block structure or the
 127 buffer contents are not allowed while the request is queued.
 128 .Pp
 129 If the file offset in
 130 .Fa iocb->aio_offset
 131 is past the offset maximum for
 132 .Fa iocb->aio_fildes ,
 133 no I/O will occur.
 134 .Sh RETURN VALUES
 135 .Rv -std aio_read aio_readv
 136 .Sh DIAGNOSTICS
 137 None.
 138 .Sh ERRORS
 139 The
 140 .Fn aio_read
 141 and
 142 .Fn aio_readv
 143 system calls will fail if:
 144 .Bl -tag -width Er
 145 .It Bq Er EAGAIN
 146 The request was not queued because of system resource limitations.
 147 .It Bq Er EFAULT
 148 Part of
 149 .Fa aio_iov
 150 points outside the process's allocated address space.
 151 .It Bq Er EINVAL
 152 The asynchronous notification method in
 153 .Fa iocb->aio_sigevent.sigev_notify
 154 is invalid or not supported.
 155 .It Bq Er EOPNOTSUPP
 156 Asynchronous read operations on the file descriptor
 157 .Fa iocb->aio_fildes
 158 are unsafe and unsafe asynchronous I/O operations are disabled.
 159 .El
 160 .Pp
 161 The following conditions may be synchronously detected when the
 162 .Fn aio_read
 163 or
 164 .Fn aio_readv
 165 system call is made, or asynchronously, at any time thereafter.
 166 If they
 167 are detected at call time,
 168 .Fn aio_read
 169 or
 170 .Fn aio_readv
 171 returns -1 and sets
 172 .Va errno
 173 appropriately; otherwise the
 174 .Fn aio_return
 175 system call must be called, and will return -1, and
 176 .Fn aio_error
 177 must be called to determine the actual value that would have been
 178 returned in
 179 .Va errno .
 180 .Bl -tag -width Er
 181 .It Bq Er EBADF
 182 The
 183 .Fa iocb->aio_fildes
 184 argument
 185 is invalid.
 186 .It Bq Er EINVAL
 187 The offset
 188 .Fa iocb->aio_offset
 189 is not valid, the priority specified by
 190 .Fa iocb->aio_reqprio
 191 is not a valid priority, or the number of bytes specified by
 192 .Fa iocb->aio_nbytes
 193 is not valid.
 194 .It Bq Er EOVERFLOW
 195 The file is a regular file,
 196 .Fa iocb->aio_nbytes
 197 is greater than zero, the starting offset in
 198 .Fa iocb->aio_offset
 199 is before the end of the file, but is at or beyond the
 200 .Fa iocb->aio_fildes
 201 offset maximum.
 202 .El
 203 .Pp
 204 If the request is successfully enqueued, but subsequently cancelled
 205 or an error occurs, the value returned by the
 206 .Fn aio_return
 207 system call is per the
 208 .Xr read 2
 209 system call, and the value returned by the
 210 .Fn aio_error
 211 system call is either one of the error returns from the
 212 .Xr read 2
 213 system call, or one of:
 214 .Bl -tag -width Er
 215 .It Bq Er EBADF
 216 The
 217 .Fa iocb->aio_fildes
 218 argument
 219 is invalid for reading.
 220 .It Bq Er ECANCELED
 221 The request was explicitly cancelled via a call to
 222 .Fn aio_cancel .
 223 .It Bq Er EINVAL
 224 The offset
 225 .Fa iocb->aio_offset
 226 would be invalid.
 227 .El
 228 .Sh SEE ALSO
 229 .Xr aio_cancel 2 ,
 230 .Xr aio_error 2 ,
 231 .Xr aio_return 2 ,
 232 .Xr aio_suspend 2 ,
 233 .Xr aio_waitcomplete 2 ,
 234 .Xr aio_write 2 ,
 235 .Xr sigevent 3 ,
 236 .Xr siginfo 3 ,
 237 .Xr aio 4
 238 .Sh STANDARDS
 239 The
 240 .Fn aio_read
 241 system call is expected to conform to the
 242 .St -p1003.1
 243 standard.
 244 The
 245 .Fn aio_readv
 246 system call is a FreeBSD extension, and should not be used in portable code.
 247 .Sh HISTORY
 248 The
 249 .Fn aio_read
 250 system call first appeared in
 251 .Fx 3.0 .
 252 The
 253 .Fn aio_readv
 254 system call first appeared in
 255 .Fx 13.0 .
 256 .Sh AUTHORS
 257 This
 258 manual page was written by
 259 .An Terry Lambert Aq Mt terry@whistle.com .
 260 .Sh BUGS
 261 Invalid information in
 262 .Fa iocb->_aiocb_private
 263 may confuse the kernel.