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 July 15, 2016
  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_NOP
  70 No operation.
  71 .It Dv LIO_WRITE
  72 Write data as if by a call to
  73 .Xr aio_write 2 .
  74 .El
  75 .Pp
  76 If the
  77 .Fa mode
  78 argument is
  79 .Dv LIO_WAIT ,
  80 .Fn lio_listio
  81 does not return until all the requested operations have been completed.
  82 If
  83 .Fa mode
  84 is
  85 .Dv LIO_NOWAIT ,
  86 .Fa sig
  87 can be used to request asynchronous notification when all operations have
  88 completed.
  89 If
  90 .Fa sig
  91 is
  92 .Dv NULL ,
  93 no notification is sent.
  94 .Pp
  95 For
  96 .Dv SIGEV_KEVENT
  97 notifications,
  98 the posted kevent will contain:
  99 .Bl -column ".Va filter"
 100 .It Sy Member Ta Sy Value
 101 .It Va ident Ta Fa list
 102 .It Va filter Ta Dv EVFILT_LIO
 103 .It Va udata Ta
 104 value stored in
 105 .Fa sig->sigev_value
 106 .El
 107 .Pp
 108 For
 109 .Dv SIGEV_SIGNO
 110 and
 111 .Dv SIGEV_THREAD_ID
 112 notifications,
 113 the information for the queued signal will include
 114 .Dv SI_ASYNCIO
 115 in the
 116 .Va si_code
 117 field and the value stored in
 118 .Fa sig->sigev_value
 119 in the
 120 .Va si_value
 121 field.
 122 .Pp
 123 For
 124 .Dv SIGEV_THREAD
 125 notifications,
 126 the value stored in
 127 .Fa sig->sigev_value
 128 is passed to the
 129 .Fa sig->sigev_notify_function
 130 as described in
 131 .Xr sigevent 3 .
 132 .Pp
 133 The order in which the requests are carried out is not specified;
 134 in particular, there is no guarantee that they will be executed in
 135 the order 0, 1, ...,
 136 .Fa nent Ns \-1 .
 137 .Sh RETURN VALUES
 138 If
 139 .Fa mode
 140 is
 141 .Dv LIO_WAIT ,
 142 the
 143 .Fn lio_listio
 144 function returns 0 if the operations completed successfully,
 145 otherwise \-1.
 146 .Pp
 147 If
 148 .Fa mode
 149 is
 150 .Dv LIO_NOWAIT ,
 151 the
 152 .Fn lio_listio
 153 function returns 0 if the operations are successfully queued,
 154 otherwise \-1.
 155 .Sh ERRORS
 156 The
 157 .Fn lio_listio
 158 function will fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EAGAIN
 161 There are not enough resources to enqueue the requests.
 162 .It Bq Er EAGAIN
 163 The request would cause the system-wide limit
 164 .Dv AIO_MAX
 165 to be exceeded.
 166 .It Bq Er EINVAL
 167 The
 168 .Fa mode
 169 argument is neither
 170 .Dv LIO_WAIT
 171 nor
 172 .Dv LIO_NOWAIT ,
 173 or
 174 .Fa nent
 175 is greater than
 176 .Dv AIO_LISTIO_MAX .
 177 .It Bq Er EINVAL
 178 The asynchronous notification method in
 179 .Fa sig->sigev_notify
 180 is invalid or not supported.
 181 .It Bq Er EINTR
 182 A signal interrupted the system call before it could be completed.
 183 .It Bq Er EIO
 184 One or more requests failed.
 185 .El
 186 .Pp
 187 In addition, the
 188 .Fn lio_listio
 189 function may fail for any of the reasons listed for
 190 .Xr aio_read 2
 191 and
 192 .Xr aio_write 2 .
 193 .Pp
 194 If
 195 .Fn lio_listio
 196 succeeds, or fails with an error code of
 197 .Er EAGAIN , EINTR ,
 198 or
 199 .Er EIO ,
 200 some of the requests may have been initiated.
 201 The caller should check the error status of each
 202 .Vt aiocb
 203 structure individually by calling
 204 .Xr aio_error 2 .
 205 .Sh SEE ALSO
 206 .Xr aio_error 2 ,
 207 .Xr aio_read 2 ,
 208 .Xr aio_write 2 ,
 209 .Xr read 2 ,
 210 .Xr write 2 ,
 211 .Xr sigevent 3 ,
 212 .Xr siginfo 3 ,
 213 .Xr aio 4
 214 .Sh STANDARDS
 215 The
 216 .Fn lio_listio
 217 function is expected to conform to
 218 .St -p1003.1-2001 .