aio_read.2 (2010 09)

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 suc-
cessfully 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
associated with
aiocbp->aio_fildes
into the buffer pointed to by aiocbp->aio_buf. The prior-
ity 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 argu-
ment _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
operation 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
operation 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 asynchro-
nous 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.
[EEXIST] The
aiocbp is already in use for another asynchronous I/O operation.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1