aioread(3scl)aioread(3scl)NAMEaioread - issue an asynchronous read operation
LIBRARY
SCL Miscellaneous Library (libsolmisc.so, libsolmisc.a)
SYNOPSIS
#include <sys/asynch.h>
int aioread(int fildes,
char *bufp,
int bufs,
off_t offset,
int whence,
aio_result_t *resultp);
PARAMETERS
Specifies the object to which the I/O operation is applied Points to a
location from which data is read Specifies amount of data to transfer
(bytes) Specifies the offset at which to start the I/O operation Speci‐
fies the relative position of the offset Pointer to aio_result_t struc‐
ture in which the asynchronous return value is stored
DESCRIPTION
The aioread() function initiates an asynchronous read operation to the
object specified by the fildes parameter, to retrieve bufs bytes of
data into the buffer pointed to by bufp.
If the object is capable of seeking, the I/O operation starts at the
position specified with the whence and offset parameters. These have
the same meaning as with the lseek(2) function. The seek pointer is not
updated as a result of the I/O operation.
The result of the completed operation is stored in the aio_result_t
structure pointed to by the resultp parameter. The aio_return member
stores the return status of the read operation, and the aio_errno mem‐
ber stores the corresponding errno value. The aio_return member can be
set to AIO_INPROGRESS prior to calling this function, and I/O comple‐
tion can be detected by polling this member for a change in value.
It is unsafe to access the application I/O buffer (specified with the
bufp parameter) until the operation is known to have completed.
Notification of I/O completion can be achieved synchronously or asyn‐
chronously. The former uses the aiowait(3scl) function which will
cause the thread to wait for an I/O operation to complete. Asynchronous
notification is enabled by installing a SIGIO signal handler, thus
causing I/O completion to raise a SIGIO signal. The handler is expected
to call the aiowait() function in order to dequeue the completed asyn‐
chronous operations. Notification of multiple completed operations
needs to be handled, as multiple SIGIO signals are not queued. There‐
fore the handler should call the aiowait() function with a timeout
value of 0 to effect polling for a completed request.
The result buffer specified by the resultp parameter can only be used
by one I/O operation at a time. The result buffer must be "released"
for reuse by calling the aiowait(3scl) or aiocancel(3scl) functions.
SCL IMPLEMENTATION NOTES
This function is implemented by creating an additional thread to per‐
form the I/O operation asynchronously by calling the pread(2) function.
Consequently, there are a number of differences that application devel‐
opers should be aware of:
Some error values are returned differently. The Solaris implementation
of this function returns certain errors immediately and therefore does
not initiate the I/O operation. An example is EBADF, returned if an
invalid file descriptor is specified. The SCL implementation does not
detect this problem until the I/O operation is issued by the separate
I/O thread, therefore the call to aioread() has apparantly been suc‐
cessful. However, the EBADF error will be reported asynchronously - the
error code will be written to the result structure. Therefore, applica‐
tions must ensure that the result structure is tested for errors and
that those errors may be different to those expected on Solaris. On
Tru64 UNIX, it is possible for pread() to be interrupted by a signal,
and thus complete with an error (return value of -1 and errno set to
EINTR). This means that, unlike Solaris, the asynchronous I/O operation
could terminate is such a way. Applications may need to change to pre‐
vent this by handling EINTR or blocking expected signals while the I/O
operation is in progress. The aio_result_t structure defined for the
SCL implementation is significantly different from that of Solaris.
Applications that make assumptions about the size of this structure
should be altered. The two members defined on Solaris are still valid
for the SCL variant. Any defined aio_result_t structures must be ini‐
tialized to contain zeros before first being used. On Solaris, appli‐
cations that use the aioread() function are required to link with the
libaio library to resolve the function reference. SCL places this func‐
tion within the libsolmisc shared and static libraries, thus the
library option on the build command should be changed from -laio to
-lsolmisc. Tru64 UNIX already supplies a libaio that implements the
POSIX asynchronous I/O functionality. There is no "hard" limit to the
number of asynchronous operations that can be outstanding at any one
time. In practise, the limit is set as the number of threads that the
operating system allows a process to create. For applications that do
not wish to reach this limit (and thereby potentially cause the process
to hang), ensure that the number of outstanding I/O operations does not
exceed MAXASYNCHIO.
RETURN VALUES
Function aioread() returns 0 if successful, otherwise -1. The return
status reflects the success of initiating the I/O operation, not the
completion of it, which is reported in the result structure pointed to
by the resultp parameter.
The SCL implementation of this function may cause errors to occur that
could not occur on Solaris. Such errors are written to the SCL error‐
log. In this case the errno reflecting the actual error is mapped to an
errno that is valid and expected on Solaris. This means that applica‐
tions testing for a specific set of errors will continue to work as
expected.
ERRORS
The aioread() function can set errno to one of the following values:
The maximum number of outstanding asynchronous requests has been
exceeded, caused by creating the maximum number of threads permitted
for the process. The result structure is currently in use by an out‐
standing I/O request.
An internal implementation error occurred. Refer to the SCL
errorlog for additional information Insufficient memory
resources available
When the I/O operation has completed, the result structure aio_return
member value will contain the value returned by the pread() function,
and the aio_errno member value will be the corresponding errno value.
Refer to the pread() man page for possible values and meanings.
RELATED INFORMATION
Functions: aiocancel(3scl), aiowait(3scl), aiowrite(3scl), pread(2)
File: scl_error_log(4scl)
Manual: Solaris Compatibility Library User's Guide
aioread(3scl)