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
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | Safe |
+---------------+-----------------+
SEE ALSO
close(2),
execve(2),
exit(2),
llseek(2),
lseek(2),
open(2),
read(2),
write(2),
aiocancel(3C),
aiowait(3C),
attributes(7),
lf64(7) May 13, 2017
AIOREAD(3C)