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