lio_listio(3aio)


lio_listio, lio_listio64 -- issue list of I/O requests

Synopsis

   

cc [options] -Kthread file

#include <aio.h>

int lio_listio(int mode, struct aiocb *list[], int nent,struct sigevent *sig);

int lio_listio64(int mode, struct aiocb64 *list[], int nent,struct sigevent *sig);

Description

lio_listio supports issuing a list of I/O requests with a single function call.

The mode argument takes one of the values LIO_WAIT or LIO_NOWAIT and determines whether the function returns when the I/O operations have been completed, or as soon as the operations have been queued. If the mode argument is LIO_WAIT, the function waits until all I/O is complete and the sig argument is ignored.

When LIO_WAIT is selected, lio_listio waits for all requests that were successfully queued to complete before returning. If no requests were successfully queued, it returns immediately.

If the mode argument is LIO_NOWAIT, the function returns immediately, and completion notification occurs according to the sig argument, when all the I/O operations complete. If sig is NULL, no notification occurs. If sig is not NULL, notification occurs according to the same rules as the aio_sigevent aiocb field.

The list argument is an array of pointers to aiocb structures. The array contains nent elements. The array may contain NULL elements which are ignored.

The I/O requests enumerated by list are submitted in an unspecified order.

The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The supported operations are LIO_READ, LIO_WRITE, and LIO_NOP. The LIO_NOP operation causes the list entry to be ignored. If the aio_lio_opcode element is equal to LIO_READ, an I/O operation is submitted as if by a call to aio_read with the aiocb equal to the address of the aiocb structure. If the aio_lio_opcode element is equal to LIO_WRITE, an I/O operation is submitted as if by a call to aio_write with the aiocb equal to the address of the aiocb structure.

Other aiocb structure members (i.e. aio_fildes, aio_buf, aio_nbytes, etc) are set in a manner equivalent to how they would be set if you use them in a direct call to aio_write or aio_read.

The nent argument specifies how many elements are members of the list, or the length of the array.

The sig argument is a pointer to a signal control structure, used when the mode argument has the value LIO_NOWAIT, which defines the notification to be issued when the entire list of I/O requests have been completed.

The behavior of lio_listio 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 the requests.

Mixing of requests with and without the AIO_RAW flag set in aio_flags is supported. The implementation should, but is not required to, return an error if this is attempted. The setting of the AIO_RAW flag can be determined by examing the first request in list.

Return values

If the mode argument has the value LIO_NOWAIT, the lio_listio and lio_listio64 functions return the value zero if the I/O operations are successfully queued; otherwise, they return the value -1 and set errno to indicate the error.

If the mode argument has the value LIO_WAIT, the lio_listio and lio_listio64 functions return zero when all the indicated I/O has completed successfully. Otherwise, lio_listio and lio_listio64 return a value of -1 and set errno to indicate the error.

Both of these return values only indicate the success or failure of the lio_listio and lio_listio64 calls themselves, 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 does not prevent completion of any other individual request. To determine the outcome of each I/O request, the application examines the error status associated with each lio_aiocb control block. The error statuses returned are identical to those returned as the result of an aio_read or aio_write function.

Errors

If any of the following conditions occur, the lio_listio function returns -1 and sets errno to:

EFBIG
The aiocbp->aio_lio_opcode is LIO_WRITE, the file is a regular file, aiocbp->aio_nbytes is greater than 0, and the starting offset in aiocbp->aio_offset is greater than or equal to the offset maximum in the open file descriptor associated with aio_fildes.

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 descriptor associated with aio_fildes.

If any of the following conditions occur, the lio_listio and the lio_listio64 function return -1 and set errno to:


EAGAIN
The resources necessary to queue all the I/O requests were not available. The application may check the error status for each aiocb to determine the individual request(s) that failed.

EAGAIN
The number of entries indicated by nent would cause the system-wide limit {AIO_MAX} to be exceeded. All entries return EAGAIN when queried with aio_error.

EFAULT
A memory fault occurred while accessing a lio_listio or a lio_listio64 request. In this case, lio_listio and lio_listio64 return immediately without processing subsequent requests in the list. On some implementations, memory faults might result in a SIGSEGV signal being delivered to the processes instead of returning the error code.

EINVAL
The mode argument is not a proper value.

EINVAL
the value of nent was greater than {AIO_LISTIO_MAX} (see ``Miscellaneous parameters'' in Monitoring and tuning the system), or nent is zero.

EINVAL
All requests are NULL or have their lio_listio set to LIO_NOP.

EINTR
A signal was delivered while waiting for all I/O requests to complete during a LIO_WAIT operation. Note that, since each I/O operation invoked by lio_listio or lio_listio64 may possibly provoke a signal when it completes, this error return may be caused by the completion of one (or more) of the very I/O operations being awaited. Outstanding I/O requests are not canceled, and the application shall examine each list element to determine whether the request was initiated, canceled or completed.

EIO
One or more of the individual I/O operations failed. The application may check the error status for each aiocb structure to determine the individual request(s) that failed.

ENOMEM
There were no internal kernal aio control blocks available to service the request (number of kernel aio control blocks is tunable via the NUMAIO kernel parameter; see ``Miscellaneous parameters'' in Monitoring and tuning the system).

EOVERFLOW
The I/O request is trying to write beyond the offset maximum established in the open file descriptor associated with aio_fildes.

References

aiocb(5), aio_read(3aio), aio_suspend(3aio), aio_write(3aio), intro(2)

Notices

Considerations for large file support

lio_listio64 supports large files, but is otherwise identical to lio_listio. For details on programming for large file capable applications, see ``Large File Support'' on intro(2).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004