Tribblix: manual page: aioread.3c

AIOREAD(3C) Standard C Library Functions AIOREAD(3C)

NAME

aioread, aiowrite - read or write asynchronous I/O operations

SYNOPSIS

#include <sys/types.h>
#include <sys/asynch.h>

int aioread(int fildes, char *bufp, int bufs, off_t offset,
int whence, aio_result_t *resultp);

int aiowrite(int fildes, const char *bufp, int bufs, off_t offset,
int whence, aio_result_t *resultp);

DESCRIPTION

The aioread() function initiates one asynchronous read(2) and returns
control to the calling program. The read continues concurrently with
other activity of the process. An attempt is made to read bufs bytes
of data from the object referenced by the descriptor fildes into the
buffer pointed to by bufp.

The aiowrite() function initiates one asynchronous write(2) and
returns control to the calling program. The write continues
concurrently with other activity of the process. An attempt is made
to write bufs bytes of data from the buffer pointed to by bufp to the
object referenced by the descriptor fildes.

On objects capable of seeking, the I/O operation starts at the
position specified by whence and offset. These parameters have the
same meaning as the corresponding parameters to the llseek(2)
function. On objects not capable of seeking the I/O operation always
start from the current position and the parameters whence and offset
are ignored. The seek pointer for objects capable of seeking is not
updated by aioread() or aiowrite(). Sequential asynchronous
operations on these devices must be managed by the application using
the whence and offset parameters.

The result of the asynchronous operation is stored in the structure
pointed to by resultp:

int aio_return; /* return value of read() or write() */
int aio_errno; /* value of errno for read() or write() */

Upon completion of the operation both aio_return and aio_errno are
set to reflect the result of the operation. Since AIO_INPROGRESS is
not a value used by the system, the client can detect a change in
state by initializing aio_return to this value.

The application-supplied buffer bufp should not be referenced by the
application until after the operation has completed. While the
operation is in progress, this buffer is in use by the operating
system.

Notification of the completion of an asynchronous I/O operation can
be obtained synchronously through the aiowait(3C) function, or
asynchronously by installing a signal handler for the SIGIO signal.
Asynchronous notification is accomplished by sending the process a
SIGIO signal. If a signal handler is not installed for the SIGIO
signal, asynchronous notification is disabled. The delivery of this
instance of the SIGIO signal is reliable in that a signal delivered
while the handler is executing is not lost. If the client ensures
that aiowait() returns nothing (using a polling timeout) before
returning from the signal handler, no asynchronous I/O notifications
are lost. The aiowait() function is the only way to dequeue an
asynchronous notification. The SIGIO signal can have several meanings
simultaneously. For example, it can signify that a descriptor
generated SIGIO and an asynchronous operation completed. Further,
issuing an asynchronous request successfully guarantees that space
exists to queue the completion notification.

The close(2), exit(2) and execve(2)) functions block until all
pending asynchronous I/O operations can be canceled by the system.

It is an error to use the same result buffer in more than one
outstanding request. These structures can be reused only after the
system has completed the operation.

RETURN VALUES

Upon successful completion, aioread() and aiowrite() return 0. Upon
failure, aioread() and aiowrite() return -1 and set errno to indicate
the error.

ERRORS

The aioread() and aiowrite() functions will fail if:

EAGAIN
The number of asynchronous requests that the system can
handle at any one time has been exceeded

EBADF
The fildes argument is not a valid file descriptor open for
reading.

EFAULT
At least one of bufp or resultp points to an address
outside the address space of the requesting process. This
condition is reported only if detected by the application
process.

EINVAL
The resultp argument is currently being used by an
outstanding asynchronous request.

EINVAL
The offset argument is not a valid offset for this file
system type.

ENOMEM
Memory resources are unavailable to initiate request.

USAGE

The aioread() and aiowrite() functions have transitional interfaces
for 64-bit file offsets. See lf64(7).

ATTRIBUTES