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 January 12, 2003
  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 the requests are processed asynchronously, and the signal specified by
  87 .Fa sig
  88 is sent when all operations have completed.
  89 If
  90 .Fa sig
  91 is
  92 .Dv NULL ,
  93 the calling process is not notified of I/O completion.
  94 .Pp
  95 The order in which the requests are carried out is not specified;
  96 in particular, there is no guarantee that they will be executed in
  97 the order 0, 1, ...,
  98 .Fa nent Ns \-1 .
  99 .Sh RETURN VALUES
 100 If
 101 .Fa mode
 102 is
 103 .Dv LIO_WAIT ,
 104 the
 105 .Fn lio_listio
 106 function returns 0 if the operations completed successfully,
 107 otherwise \-1.
 108 .Pp
 109 If
 110 .Fa mode
 111 is
 112 .Dv LIO_NOWAIT ,
 113 the
 114 .Fn lio_listio
 115 function returns 0 if the operations are successfully queued,
 116 otherwise \-1.
 117 .Sh ERRORS
 118 The
 119 .Fn lio_listio
 120 function will fail if:
 121 .Bl -tag -width Er
 122 .It Bq Er EAGAIN
 123 There are not enough resources to enqueue the requests.
 124 .It Bq Er EAGAIN
 125 The request would cause the system-wide limit
 126 .Dv AIO_MAX
 127 to be exceeded.
 128 .It Bq Er EINVAL
 129 The
 130 .Fa mode
 131 argument is neither
 132 .Dv LIO_WAIT
 133 nor
 134 .Dv LIO_NOWAIT ,
 135 or
 136 .Fa nent
 137 is greater than
 138 .Dv AIO_LISTIO_MAX .
 139 .It Bq Er EINTR
 140 A signal interrupted the system call before it could be completed.
 141 .It Bq Er EIO
 142 One or more requests failed.
 143 .El
 144 .Pp
 145 In addition, the
 146 .Fn lio_listio
 147 function may fail for any of the reasons listed for
 148 .Xr aio_read 2
 149 and
 150 .Xr aio_write 2 .
 151 .Pp
 152 If
 153 .Fn lio_listio
 154 succeeds, or fails with an error code of
 155 .Er EAGAIN , EINTR ,
 156 or
 157 .Er EIO ,
 158 some of the requests may have been initiated.
 159 The caller should check the error status of each
 160 .Vt aiocb
 161 structure individually by calling
 162 .Xr aio_error 2 .
 163 .Sh SEE ALSO
 164 .Xr aio_error 2 ,
 165 .Xr aio_read 2 ,
 166 .Xr aio_write 2 ,
 167 .Xr read 2 ,
 168 .Xr write 2 ,
 169 .Xr siginfo 3 ,
 170 .Xr aio 4
 171 .Sh STANDARDS
 172 The
 173 .Fn lio_listio
 174 function is expected to conform to
 175 .St -p1003.1-2001 .