lib/libc/sys/lio_listio.2

   1 .\" Copyright (c) 2003 Tim J. Robbins
   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 August 22, 2021
  28 .Dt LIO_LISTIO 2
  29 .Os
  30 .Sh NAME
  31 .Nm lio_listio
  32 .Nd "list directed I/O (REALTIME)"
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In aio.h
  37 .Ft int
  38 .Fo lio_listio
  39 .Fa "int mode"
  40 .Fa "struct aiocb * const list[]"
  41 .Fa "int nent"
  42 .Fa "struct sigevent *sig"
  43 .Fc
  44 .Sh DESCRIPTION
  45 The
  46 .Fn lio_listio
  47 function initiates a list of I/O requests with a single function call.
  48 The
  49 .Fa list
  50 argument is an array of pointers to
  51 .Vt aiocb
  52 structures describing each operation to perform,
  53 with
  54 .Fa nent
  55 elements.
  56 .Dv NULL
  57 elements are ignored.
  58 .Pp
  59 The
  60 .Va aio_lio_opcode
  61 field of each
  62 .Vt aiocb
  63 specifies the operation to be performed.
  64 The following operations are supported:
  65 .Bl -tag -width ".Dv LIO_WRITE"
  66 .It Dv LIO_READ
  67 Read data as if by a call to
  68 .Xr aio_read 2 .
  69 .It Dv LIO_READV
  70 Read data as if by a call to
  71 .Xr aio_readv 2 .
  72 .It Dv LIO_NOP
  73 No operation.
  74 .It Dv LIO_WRITE
  75 Write data as if by a call to
  76 .Xr aio_write 2 .
  77 .It Dv LIO_WRITEV
  78 Write data as if by a call to
  79 .Xr aio_writev 2 .
  80 .El
  81 .Pp
  82 If the
  83 .Fa mode
  84 argument is
  85 .Dv LIO_WAIT ,
  86 .Fn lio_listio
  87 does not return until all the requested operations have been completed.
  88 If
  89 .Fa mode
  90 is
  91 .Dv LIO_NOWAIT ,
  92 .Fa sig
  93 can be used to request asynchronous notification when all operations have
  94 completed.
  95 If
  96 .Fa sig
  97 is
  98 .Dv NULL ,
  99 no notification is sent.
 100 .Pp
 101 For
 102 .Dv SIGEV_KEVENT
 103 notifications,
 104 the posted kevent will contain:
 105 .Bl -column ".Va filter"
 106 .It Sy Member Ta Sy Value
 107 .It Va ident Ta Fa list
 108 .It Va filter Ta Dv EVFILT_LIO
 109 .It Va udata Ta
 110 value stored in
 111 .Fa sig->sigev_value
 112 .El
 113 .Pp
 114 For
 115 .Dv SIGEV_SIGNO
 116 and
 117 .Dv SIGEV_THREAD_ID
 118 notifications,
 119 the information for the queued signal will include
 120 .Dv SI_ASYNCIO
 121 in the
 122 .Va si_code
 123 field and the value stored in
 124 .Fa sig->sigev_value
 125 in the
 126 .Va si_value
 127 field.
 128 .Pp
 129 For
 130 .Dv SIGEV_THREAD
 131 notifications,
 132 the value stored in
 133 .Fa sig->sigev_value
 134 is passed to the
 135 .Fa sig->sigev_notify_function
 136 as described in
 137 .Xr sigevent 3 .
 138 .Pp
 139 The order in which the requests are carried out is not specified;
 140 in particular, there is no guarantee that they will be executed in
 141 the order 0, 1, ...,
 142 .Fa nent Ns \-1 .
 143 .Sh RETURN VALUES
 144 If
 145 .Fa mode
 146 is
 147 .Dv LIO_WAIT ,
 148 the
 149 .Fn lio_listio
 150 function returns 0 if the operations completed successfully,
 151 otherwise \-1.
 152 .Pp
 153 If
 154 .Fa mode
 155 is
 156 .Dv LIO_NOWAIT ,
 157 the
 158 .Fn lio_listio
 159 function returns 0 if the operations are successfully queued,
 160 otherwise \-1.
 161 .Sh ERRORS
 162 The
 163 .Fn lio_listio
 164 function will fail if:
 165 .Bl -tag -width Er
 166 .It Bq Er EAGAIN
 167 There are not enough resources to enqueue the requests.
 168 .It Bq Er EAGAIN
 169 The request would cause the system-wide limit
 170 .Dv {AIO_MAX}
 171 to be exceeded.
 172 .It Bq Er EINVAL
 173 The
 174 .Fa mode
 175 argument is neither
 176 .Dv LIO_WAIT
 177 nor
 178 .Dv LIO_NOWAIT ,
 179 or
 180 .Fa nent
 181 is greater than
 182 .Dv {AIO_LISTIO_MAX} .
 183 .It Bq Er EINVAL
 184 The asynchronous notification method in
 185 .Fa sig->sigev_notify
 186 is invalid or not supported.
 187 .It Bq Er EINTR
 188 A signal interrupted the system call before it could be completed.
 189 .It Bq Er EIO
 190 One or more requests failed.
 191 .El
 192 .Pp
 193 In addition, the
 194 .Fn lio_listio
 195 function may fail for any of the reasons listed for
 196 .Xr aio_read 2
 197 and
 198 .Xr aio_write 2 .
 199 .Pp
 200 If
 201 .Fn lio_listio
 202 succeeds, or fails with an error code of
 203 .Er EAGAIN , EINTR ,
 204 or
 205 .Er EIO ,
 206 some of the requests may have been initiated.
 207 The caller should check the error status of each
 208 .Vt aiocb
 209 structure individually by calling
 210 .Xr aio_error 2 .
 211 .Sh SEE ALSO
 212 .Xr aio_error 2 ,
 213 .Xr aio_read 2 ,
 214 .Xr aio_readv 2 ,
 215 .Xr aio_write 2 ,
 216 .Xr aio_writev 2 ,
 217 .Xr read 2 ,
 218 .Xr write 2 ,
 219 .Xr sigevent 3 ,
 220 .Xr siginfo 3 ,
 221 .Xr aio 4
 222 .Sh STANDARDS
 223 The
 224 .Fn lio_listio
 225 function is expected to conform to
 226 .St -p1003.1-2001 .
 227 The
 228 .Dv LIO_READV
 229 and
 230 .Dv LIO_WRITEV
 231 operations are
 232 .Fx extensions, and should not be used in portable code.
 233 .Sh HISTORY
 234 The
 235 .Fn lio_listio
 236 system call first appeared in
 237 .Fx 3.0 .