HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

a
aio_read(2) aio_read(2)
NAME
aio_read() - start an asynchronous read operation
SYNOPSIS
#include <aio.h>
int aio_read(struct aiocb *aiocbp);
DESCRIPTION
The aio_read() function allows the calling process to perform an asynchronous read from a previously
opened file. The function call returns when the read operation has been enqueued for processing. At this
point, processing of the read operation may proceed concurrently with execution of the calling process or
thread.
If an error condition is detected that prevents the read request from being enqueued,
aio_read()
returns -1 and sets errno to indicate the cause of the failure. Once the read operation has been success-
fully enqueued, an aio_error() and aio_return() function referencing the
aiocb referred to by
aiocbp must be used to determine its status and any error conditions, including those normally reported
by read(). The request remains enqueued and consumes process and system resources until
aio_return() is called.
The aio_read() function allows the calling process to read aiocbp->aio_nbytes
from the file asso-
ciated with
aiocbp->aio_fildes
into the buffer pointed to by aiocbp->aio_buf. The priority of
the read operation is reduced by the value of
aiocbp->aio_reqprio
, which must be a value between 0
(zero) and a maximum value which can be obtained using the
sysconf() call with the argument
_SC_AIO_PRIO_DELTA_MAX
. A value of 0 (zero) yields no reduction in priority. The aiocbp-
>aio_lio_opcode
field is ignored.
The read operation takes place at the absolute position in the file given by
aiocbp->aio_offset
,asif
lseek() were called immediately prior to the operation with offset equal to aiocbp-
>aio_offset
and whence set to SEEK_SET. However, the value of the file offset is never changed by
asynchronous I/O operations.
Deallocating or altering the contents of memory referred to by aiocbp while an asynchronous read opera-
tion is outstanding (i.e. before aio_return() has been called) may produce unpredictable results.
If aiocbp->aio_sigevent
is a valid signal event structure, then the designated signal will be
delivered when the requested asynchronous read operation completes.
To use this function, link in the realtime library by specifying
-lrt on the compiler or linker command
line.
RETURN VALUE
aio_read() returns the following values:
0 Successful completion, the operation has been enqueued.
-1 Failure. The requested operation was not enqueued. errno
is set to indicate the
error.
The return value from
aio_read() reflects the success or failure of enqueuing the requested read opera-
tion for asynchronous processing. aio_read() fails if an error in the function call is immediately
detected, or if system resource limits prevent the request from being enqueued. Other error conditions are
reported asynchronously and must be retrieved with aio_error() and aio_return() .
ERRORS
If aio_read() detects one of the following error conditions, errno is set to the indicated value:
[EAGAIN] The request could not be queued either because of a resource shortage or because the
per-process or system-wide limit on asynchronous I/O operations or asynchronous
threads would have been exceeded.
[EINVAL] aiocb->aio_sigevent is not a valid address in the process virtual address
space.
[EINVAL] The parameters of the indicated sigevent in aiocb->aio_sigevent are
invalid.
44 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007