1LIO_LISTIO(3P)             POSIX Programmer's Manual            LIO_LISTIO(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       lio_listio — list directed I/O
14

SYNOPSIS

16       #include <aio.h>
17
18       int lio_listio(int mode, struct aiocb *restrict const list[restrict],
19           int nent, struct sigevent *restrict sig);
20

DESCRIPTION

22       The lio_listio() function shall initiate a list of I/O requests with  a
23       single function call.
24
25       The  mode  argument  takes  one  of  the  values LIO_WAIT or LIO_NOWAIT
26       declared in <aio.h> and determines whether the  function  returns  when
27       the  I/O  operations  have been completed, or as soon as the operations
28       have been queued. If the mode argument is LIO_WAIT, the function  shall
29       wait until all I/O is complete and the sig argument shall be ignored.
30
31       If  the  mode argument is LIO_NOWAIT, the function shall return immedi‐
32       ately, and asynchronous notification shall occur, according to the  sig
33       argument, when all the I/O operations complete. If sig is NULL, then no
34       asynchronous notification shall occur. If sig is not NULL, asynchronous
35       notification  occurs  as  specified in Section 2.4.1, Signal Generation
36       and Delivery when all the requests in list have completed.
37
38       The I/O requests enumerated by list are  submitted  in  an  unspecified
39       order.
40
41       The  list  argument  is  an  array of pointers to aiocb structures. The
42       array contains nent elements. The  array  may  contain  NULL  elements,
43       which shall be ignored.
44
45       If  the buffer pointed to by list or the aiocb structures pointed to by
46       the elements of the array list  become  illegal  addresses  before  all
47       asynchronous I/O completed and, if necessary, the notification is sent,
48       then the behavior is undefined.  If  the  buffers  pointed  to  by  the
49       aio_buf member of the aiocb structure pointed to by the elements of the
50       array list become illegal addresses prior to the asynchronous I/O asso‐
51       ciated with that aiocb structure being completed, the behavior is unde‐
52       fined.
53
54       The aio_lio_opcode field of each aiocb structure specifies  the  opera‐
55       tion to be performed. The supported operations are LIO_READ, LIO_WRITE,
56       and LIO_NOP; these symbols are defined in <aio.h>.  The LIO_NOP  opera‐
57       tion causes the list entry to be ignored. If the aio_lio_opcode element
58       is equal to LIO_READ, then an I/O operation is submitted  as  if  by  a
59       call  to  aio_read()  with the aiocbp equal to the address of the aiocb
60       structure. If the aio_lio_opcode element is equal to LIO_WRITE, then an
61       I/O  operation  is  submitted  as  if by a call to aio_write() with the
62       aiocbp equal to the address of the aiocb structure.
63
64       The aio_fildes member specifies the file descriptor on which the opera‐
65       tion is to be performed.
66
67       The aio_buf member specifies the address of the buffer to or from which
68       the data is transferred.
69
70       The aio_nbytes member specifies the number  of  bytes  of  data  to  be
71       transferred.
72
73       The  members  of the aiocb structure further describe the I/O operation
74       to be performed, in a manner identical to  that  of  the  corresponding
75       aiocb structure when used by the aio_read() and aio_write() functions.
76
77       The  nent argument specifies how many elements are members of the list;
78       that is, the length of the array.
79
80       The behavior of this function is altered according to  the  definitions
81       of synchronized I/O data integrity completion and synchronized I/O file
82       integrity completion if synchronized I/O is enabled on the file associ‐
83       ated with aio_fildes.
84
85       For regular files, no data transfer shall occur past the offset maximum
86       established   in   the   open   file   description   associated    with
87       aiocbp->aio_fildes.
88
89       If  sig->sigev_notify  is SIGEV_THREAD and sig->sigev_notify_attributes
90       is a non-null pointer and the block pointed to by this pointer  becomes
91       an  illegal address prior to all asynchronous I/O being completed, then
92       the behavior is undefined.
93

RETURN VALUE

95       If the mode argument has the value LIO_NOWAIT, the  lio_listio()  func‐
96       tion shall return the value zero if the I/O operations are successfully
97       queued; otherwise, the function shall return the value −1 and set errno
98       to indicate the error.
99
100       If  the mode argument has the value LIO_WAIT, the lio_listio() function
101       shall return the value zero when all the indicated  I/O  has  completed
102       successfully.  Otherwise,  lio_listio()  shall return a value of −1 and
103       set errno to indicate the error.
104
105       In either case, the return value only indicates the success or  failure
106       of  the  lio_listio() call itself, not the status of the individual I/O
107       requests. In some cases one or more of the I/O  requests  contained  in
108       the  list  may fail.  Failure of an individual request does not prevent
109       completion of any other individual request. To determine the outcome of
110       each  I/O request, the application shall examine the error status asso‐
111       ciated with each aiocb control block. The error  statuses  so  returned
112       are  identical  to  those  returned  as  the result of an aio_read() or
113       aio_write() function.
114

ERRORS

116       The lio_listio() function shall fail if:
117
118       EAGAIN The resources necessary to queue all the I/O requests  were  not
119              available.  The  application may check the error status for each
120              aiocb to determine the individual request(s) that failed.
121
122       EAGAIN The number of entries indicated by nent would cause the  system-
123              wide limit {AIO_MAX} to be exceeded.
124
125       EINVAL The  mode  argument  is not a proper value, or the value of nent
126              was greater than {AIO_LISTIO_MAX}.
127
128       EINTR  A signal was delivered while waiting for  all  I/O  requests  to
129              complete during an LIO_WAIT operation. Note that, since each I/O
130              operation invoked by lio_listio() may possibly provoke a  signal
131              when  it  completes, this error return may be caused by the com‐
132              pletion of one (or  more)  of  the  very  I/O  operations  being
133              awaited.  Outstanding  I/O  requests  are  not canceled, and the
134              application shall examine each list element to determine whether
135              the request was initiated, canceled, or completed.
136
137       EIO    One  or more of the individual I/O operations failed. The appli‐
138              cation may check the error status for each  aiocb  structure  to
139              determine the individual request(s) that failed.
140
141       In addition to the errors returned by the lio_listio() function, if the
142       lio_listio() function  succeeds  or  fails  with  errors  of  [EAGAIN],
143       [EINTR],  or [EIO], then some of the I/O specified by the list may have
144       been initiated. If the lio_listio() function fails with an  error  code
145       other  than  [EAGAIN],  [EINTR],  or [EIO], no operations from the list
146       shall have been initiated. The I/O operation  indicated  by  each  list
147       element  can  encounter errors specific to the individual read or write
148       function being performed. In this event,  the  error  status  for  each
149       aiocb control block contains the associated error code. The error codes
150       that can be set are the same as would be set by  a  read()  or  write()
151       function, with the following additional error codes possible:
152
153       EAGAIN The requested I/O operation was not queued due to resource limi‐
154              tations.
155
156       ECANCELED
157              The requested I/O was canceled before the I/O completed  due  to
158              an explicit aio_cancel() request.
159
160       EFBIG  The  aiocbp->aio_lio_opcode  is LIO_WRITE, the file is a regular
161              file,  aiocbp->aio_nbytes   is   greater   than   0,   and   the
162              aiocbp->aio_offset  is greater than or equal to the offset maxi‐
163              mum   in   the   open   file   description    associated    with
164              aiocbp->aio_fildes.
165
166       EINPROGRESS
167              The requested I/O is in progress.
168
169       EOVERFLOW
170              The  aiocbp->aio_lio_opcode  is  LIO_READ, the file is a regular
171              file,  aiocbp->aio_nbytes   is   greater   than   0,   and   the
172              aiocbp->aio_offset is before the end-of-file and is greater than
173              or equal to the offset maximum  in  the  open  file  description
174              associated with aiocbp->aio_fildes.
175
176       The following sections are informative.
177

EXAMPLES

179       None.
180

APPLICATION USAGE

182       None.
183

RATIONALE

185       Although  it may appear that there are inconsistencies in the specified
186       circumstances for error codes, the [EIO] error condition  applies  when
187       any  circumstance relating to an individual operation makes that opera‐
188       tion fail. This might be due to a badly formulated request  (for  exam‐
189       ple, the aio_lio_opcode field is invalid, and aio_error() returns [EIN‐
190       VAL]) or might arise from application behavior (for example,  the  file
191       descriptor is closed before the operation is initiated, and aio_error()
192       returns [EBADF]).
193
194       The limitation on the set of error codes returned when operations  from
195       the  list  shall  have been initiated enables applications to know when
196       operations have been started and whether aio_error()  is  valid  for  a
197       specific operation.
198

FUTURE DIRECTIONS

200       None.
201

SEE ALSO

203       aio_read(),   aio_write(),   aio_error(),  aio_return(),  aio_cancel(),
204       close(), exec, exit(), fork(), lseek(), read()
205
206       The Base Definitions volume of POSIX.1‐2008, <aio.h>
207
209       Portions of this text are reprinted and reproduced in  electronic  form
210       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
211       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
212       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
213       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
214       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
215       event of any discrepancy between this version and the original IEEE and
216       The  Open Group Standard, the original IEEE and The Open Group Standard
217       is the referee document. The original Standard can be  obtained  online
218       at http://www.unix.org/online.html .
219
220       Any  typographical  or  formatting  errors that appear in this page are
221       most likely to have been introduced during the conversion of the source
222       files  to  man page format. To report such errors, see https://www.ker
223       nel.org/doc/man-pages/reporting_bugs.html .
224
225
226
227IEEE/The Open Group                  2013                       LIO_LISTIO(3P)
Impressum