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