HP-UX Reference (11i v2 04/09) - 2 System Calls (vol 5)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

aio_reap(2) aio_reap(2)

Usage Notes

To use aio_reap(), link in the realtime library by specifying

-lrt on the compiler or linker command

line. Then, before making any AIO function calls, initialize the reap mechanism by calling

aio_reap()

in lightweight mode, as shown in this example:

int ignore;

(void)aio_reap(NULL, 0, NULL, 0, &ignore);

For this single call to initialize

aio_reap(), all output (including return value) should be ignored.

RETURN VALUE

aio_reap() returns 0 if waitfor or more AIO requests have completed. The reaped requests (the

aiocb addresses of the completed AIO requests) are copied to the array

list, and the number of AIO

requests reaped is returned into the address speciﬁed by

completed_count

If the function was interrupted by a signal, the function returns

-1 and errno is set to [EINTR]. If the

function was interrupted because the

timeout time has elapsed, the function returns

-1 and errno is

set to [EAGAIN]. In either case, actual number of requests completed at the time of the interrupt is

returned in

completed_count

, and these requests are copied to list

-- even if the number of AIO

requests reaped is less than

waitfor.

If the total number of outstanding AIO requests for that process is less than

waitfor, aio_reap()

will return -1 and set errno to [E2BIG] after all remaining requests have been reaped. The only excep-

tion is if timeout time has elapsed, in which case the preceding rule applies.

If an error is discovered, the return value is

-1. errno contains additional information.

In light-weight polling mode,

aio_reap() returns 0 and sets completed_count

to the number of IOs

that are ready for collection. If an irrecoverable error occurs,

aio_reap() will return -1 and leave

completed_count unchanged.

ERRORS

aio_reap() returns -1, errno contains one of the following errors:

[EINVAL]

waitfor is less than or equal to 0, greater than

nent, or greater than the

conﬁgured maximum possible number of AIO requests the system can reap in one

call

MAX_AIO_REAP).

[EINVAL]

timeout time is not a valid timespec.

[EINVAL]

nent is less than waitfor or greater than the conﬁgured maximum possible

number of AIO requests the system can reap in one call MAX_AIO_REAP).

[ENOMEM] No free memory available.

[EFAULT] Error copying data from or to the user address space.

[EAGAIN] The

timeout time has elapsed and less than waitfor AIO requests are avail-

able.

[EINTR] A signal interrupted the

aio_reap() function and less than waitfor AIO

requests are available.

[E2BIG] The system had fewer than

waitfor outstanding AIO requests available.

[ENOSYS] The

aio_reap() function is not supported by this implementation.

APPLICATION USAGE

Note that if

aio_reap() returns -1, the caller should check the value of errno and

completed_count to determine whether any AIO requests have been reaped.

aio_reap() is designed for high performance handling of a large number of outstanding AIO requests.

It increases the throughput of AIO by reducing the number of calls to reap AIO requests, and by not

hanging up on individual AIO requests that may be taking a long time to complete.

AUTHOR

aio_reap() was developed by HP.