lio_listio(3)

1lio_listio(3)              Library Functions Manual              lio_listio(3)
2
3
4

NAME

6       lio_listio - initiate a list of I/O requests
7

LIBRARY

9       Real-time library (librt, -lrt)
10

SYNOPSIS

12       #include <aio.h>
13
14       int lio_listio(int mode,
15                      struct aiocb *restrict const aiocb_list[restrict],
16                      int nitems, struct sigevent *restrict sevp);
17

DESCRIPTION

19       The  lio_listio()  function  initiates  the  list of I/O operations de‐
20       scribed by the array aiocb_list.
21
22       The mode operation has one of the following values:
23
24       LIO_WAIT
25              The call blocks until all operations are complete.  The sevp ar‐
26              gument is ignored.
27
28       LIO_NOWAIT
29              The  I/O  operations  are queued for processing and the call re‐
30              turns immediately.  When all of  the  I/O  operations  complete,
31              asynchronous notification occurs, as specified by the sevp argu‐
32              ment; see sigevent(7) for details.  If sevp is  NULL,  no  asyn‐
33              chronous notification occurs.
34
35       The  aiocb_list  argument  is  an array of pointers to aiocb structures
36       that describe I/O operations.  These operations are executed in an  un‐
37       specified  order.   The nitems argument specifies the size of the array
38       aiocb_list.  Null pointers in aiocb_list are ignored.
39
40       In each control block in aiocb_list, the aio_lio_opcode field specifies
41       the I/O operation to be initiated, as follows:
42
43       LIO_READ
44              Initiate  a  read  operation.   The operation is queued as for a
45              call to aio_read(3) specifying this control block.
46
47       LIO_WRITE
48              Initiate a write operation.  The operation is queued  as  for  a
49              call to aio_write(3) specifying this control block.
50
51       LIO_NOP
52              Ignore this control block.
53
54       The  remaining  fields  in each control block have the same meanings as
55       for aio_read(3) and aio_write(3).  The aio_sigevent fields of each con‐
56       trol  block can be used to specify notifications for the individual I/O
57       operations (see sigevent(7)).
58

RETURN VALUE

60       If mode is LIO_NOWAIT, lio_listio() returns 0 if all I/O operations are
61       successfully  queued.   Otherwise,  -1 is returned, and errno is set to
62       indicate the error.
63
64       If mode is LIO_WAIT, lio_listio() returns 0 when all of the I/O  opera‐
65       tions  have completed successfully.  Otherwise, -1 is returned, and er‐
66       rno is set to indicate the error.
67
68       The return status from lio_listio() provides information only about the
69       call  itself,  not about the individual I/O operations.  One or more of
70       the I/O operations may fail, but this does not prevent other operations
71       completing.   The status of individual I/O operations in aiocb_list can
72       be determined using aio_error(3).  When an operation has completed, its
73       return  status can be obtained using aio_return(3).  Individual I/O op‐
74       erations  can  fail  for  the  reasons  described  in  aio_read(3)  and
75       aio_write(3).
76

ERRORS

78       The lio_listio() function may fail for the following reasons:
79
80       EAGAIN Out of resources.
81
82       EAGAIN The number of I/O operations specified by nitems would cause the
83              limit AIO_MAX to be exceeded.
84
85       EINTR  mode was LIO_WAIT and a signal was caught before all I/O  opera‐
86              tions  completed;  see  signal(7).  (This may even be one of the
87              signals used for asynchronous I/O completion notification.)
88
89       EINVAL mode is invalid, or nitems exceeds the limit AIO_LISTIO_MAX.
90
91       EIO    One of more of the operations specified  by  aiocb_list  failed.
92              The  application  can  check  the status of each operation using
93              aio_return(3).
94
95       If lio_listio() fails with the error EAGAIN, EINTR, or EIO,  then  some
96       of  the  operations in aiocb_list may have been initiated.  If lio_lis‐
97       tio() fails for any other reason, then none of the I/O  operations  has
98       been initiated.
99

ATTRIBUTES

101       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
102       tributes(7).
103
104       ┌────────────────────────────────────────────┬───────────────┬─────────┐
105       │Interface                                   │ Attribute     │ Value   │
106       ├────────────────────────────────────────────┼───────────────┼─────────┤
107       │lio_listio()                                │ Thread safety │ MT-Safe │
108       └────────────────────────────────────────────┴───────────────┴─────────┘
109

STANDARDS

111       POSIX.1-2008.
112

HISTORY

114       glibc 2.1.  POSIX.1-2001.
115

NOTES

117       It is a good idea to zero out the control blocks before use.  The  con‐
118       trol  blocks  must  not  be  changed  while  the  I/O operations are in
119       progress.  The buffer areas being read into or written from must not be
120       accessed  during  the  operations  or undefined results may occur.  The
121       memory areas involved must remain valid.
122
123       Simultaneous I/O operations specifying the same aiocb structure produce
124       undefined results.
125