Initiate a list of I/O requests
Synopsis:
#include <aio.h>
int lio_listio( int mode,
struct aiocb* const list[],
int nent,
struct sigevent* sig );
int lio_listio64( int mode,
struct aiocb64* const list[],
int nent,
struct sigevent* sig );
Arguments:
- mode
- The mode of operation; one of:
- LIO_WAIT — behave
synchronously, waiting until all I/O is completed, and ignore the
sig argument.
- LIO_NOWAIT — behave
asynchronously, returning immediately; the signal specified by
the sig argument is delivered to the calling process when
all the I/O operations from this function are completed.
- list
- An array of pointers to
aiocb or aiocb64
structures that specify the I/O operations that you want to initiate.
The array may contain NULL pointers, which the function ignores.
- nent
- The number of entries in the list array.
- sig
- NULL, or a pointer to a
sigevent
structure that specifies the notification that you want to deliver to the
calling process when all of the I/O operations are completed.
The function ignores this argument if mode is
LIO_WAIT.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The lio_listio() and lio_listio64() functions let the calling process
or thread initiate a list of I/O requests within a single function call.
The lio_listio64() function is a large-file support version of
lio_listio().
Note:
In QNX Neutrino 6.6 or later, the large-file support functions and data types
appear in the name space only if you define
_LARGEFILE64_SOURCE when you compile your code.
For more information, see
Classification
in What's in a Function Description?
The aio_lio_opcode field of each aiocb structure
in list specifies the operation to be performed (see
<aio.h>):
- LIO_READ requests
aio_read().
- LIO_WRITE requests
aio_write().
- LIO_NOP causes the list entry to be ignored.
If mode is LIO_NOWAIT, lio_listio()
and lio_listio64() use the
sigevent
structure pointed to by sig to define the signal to
be generated when all the I/O operations are complete:
- If sig is NULL or
sig->sigev_notify is SIGEV_NONE,
then no signal delivery occurs.
- If sig->sigev_notify is
SIGEV_SIGNAL:
- If nonzero, the signal specified in sig->sigev_signo is delivered
to the process when all the requests in the list have been completed.
If the SA_SIGINFO flag is set for that
signal number, the signal is queued to the process,
and the value specified in sig->sigev_value
is the si_value component of the generated signal; see
siginfo_t.
- If sigev_signo is zero, then no signal delivery occurs.
- You can use other SIGEV_* types, including
those that are QNX Neutrino extensions.
For regular files, no data transfer occurs past the
offset maximum established in the open file description
associated with aiocbp->aio_fildes.
The behavior of this function is altered according to the
definitions of synchronized I/O data integrity completion
and synchronized I/O file integrity completion if synchronized
I/O is enabled on the file associated with aio_fildes.
(see the definitions of O_DSYNC and O_SYNC
in the description of
fcntl().)
Returns:
If the mode argument is LIO_NOWAIT,
and the I/O operations are successfully queued, these functions return 0;
otherwise they return -1 and set
errno.
If the mode argument is LIO_WAIT, and all the
indicated I/O has been completed successfully, these functions
return 0; otherwise, they return -1 and set errno.
In either case, the return value indicates only the success
or failure of the lio_listio() call itself, not the status
of the individual I/O requests. In some cases, one or more
of the I/O requests contained in the list may fail. Failure
of an individual request doesn't prevent completion of any
other individual request. To determine the outcome of each
I/O request, examine the error status
associated with each aiocb control block. Each error status
so returned is identical to that returned as a result of calling
aio_read() or aio_write().
Errors:
- EAGAIN
- The resources necessary to queue all the I/O
requests weren't available. The error status for each request is
recorded in the aio_error member of the corresponding
aiocb structure, and can be retrieved using
aio_error().
- EINVAL
- The mode argument is invalid.
- EINTR
- A signal was delivered while waiting for all
I/O requests to be completed during an LIO_WAIT
operation. However, the outstanding I/O requests aren't canceled.
Use aio_fsync()
to determine if any request was initiated;
aio_return() to
determine if any request has been completed; or aio_error()
to determine if any request was canceled.
- EIO
- One or more of the individual I/O operations failed.
Use aio_error() with each aiocb
structure to determine which request(s) failed.
- ENOSYS
- The lio_listio() function isn't supported by this implementation.
If either lio_listio() succeeds in queuing all of its
requests, or errno is set to EAGAIN,
EINTR, or EIO, then
some of the I/O specified from the list may have been initiated.
In this event, each aiocb structure contains errors
specific to the
read()
or
write()
function being performed:
- EAGAIN
- The requested I/O operation wasn't queued due to resource limitations.
- ECANCELED
- The requested I/O was canceled before the I/O was completed due to an
explicit
aio_cancel()
request.
- EINPROGRESS
- The requested I/O is in progress.
The following additional error codes may be set
for each aiocb control block:
- EOVERFLOW
- The aiocbp->aio_lio_opcode is
LIO_READ, the file is a regular file,
aiocbp->aio_nbytes is greater than 0, and the
aiocbp->aio_offset is before the end-of-file
and is greater than or equal to the offset maximum in the open file
description associated with aiocbp->aio_fildes.
- EFBIG
- The aiocbp->aio_lio_opcode is
LIO_WRITE, the file is a regular file,
aiocbp->aio_nbytes is greater than 0, and the
aiocbp->aio_offset is greater than or equal
to the offset maximum in the open file description associated with
aiocbp->aio_fildes.
Classification:
lio_listio() is
POSIX 1003.1;
lio_listio64() is
Large-file support
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |