Error handling

The Asynchronous I/O feature handles errors by returning a value of -1 and placing an error number in the externally declared variable errno. It is included in <errno.h>.

The value of errno or the aio_error function can be set to one of the following:

EAGAIN

The requested Asynchronous I/O operation was not queued because of system resource limitations. The first request to encounter a resource limitation and all later requests will be marked such that aio_error returns EAGAIN.

EFAULT

aiocbp or the aio_buf member points outside the allocated address space.

ECANCELED

The requested I/O was canceled before the I/O completed because of an explicit aio_cancel request.

EINVAL

All requests are NULL or have their lio_listio set to LIO_NOP. This is used for lio_listio only.

EINVAL

nent is zero. This is used for lio_listio only.

EINVAL

On SVR4.2, the request does not have the AIO_RAW flag bit set in aio_flags.

EFAULT

A memory fault occurred while accessing a lio_listio request. In this cause, lio_listio returns immediately without processing later 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. This is used for lio_listio only.

Error behavior

The following describes the detailed error behavior for the lio_listio and aio_cancel functions.

lio_listio

If the number of entries indicated by nent causes the system-wide limit AIO_MAX to be exceeded, lio_listio returns with -1 and sets errno to EAGAIN after marking EAGAIN in all requests.

If nent is greater than AIO_LISTIO_MAX, lio_listio returns immediately with -1 and sets errno to EINVAL. No requests are processed or touched.

Requests are processed as follows:

1. If there is a memory fault while accessing a request, lio_listio immediately returns -1 or EFAULT, or causes a SIGSEGV.

2. If a resource problem occurs while queuing a request, lio_listio returns -1 and sets errno to EAGAIN for all remaining requests.

3. If any other problem occurs with a request, lio_listio returns -1 and sets errno to the appropriate error code. lio_listio continues processing requests and remembers what was wrong with the request in order for lio_listio to return this error code. The callback or signal will not be executed for that request. Note that if different errors occur while processing requests, it is unspecified which error code gets returned. For example, it could be the first error encountered, or the last one.

4. If all requests from 1 through nent have aio_lio_opcode = LIO_NOP or nent is zero, lio_listio returns -1 or EINVAL.

aio_cancel

aio_cancel returns AIO_CANCELED if all requests were either canceled or completed and at least one request was canceled.

If an attempt was made to cancel a request that is in progress, but it is uncertain whether the request will be canceled, aio_cancel will return AIO_NOTCANCELED.