Standard C Library Functions aioread(3C)
NAME
aioread - asynchronous read from a file
SYNOPSIS
#include
int aioread(struct aiocb *aiocbp);
DESCRIPTION
The aioread() function allows the calling process to read
aiocbp->aionbytes from the file associated with aiocbp-
>aiofildes into the buffer pointed to by aiocbp->aiobuf.
The function call returns when the read request has been
initiated or queued to the file or device (even when the
data cannot be delivered immediately). If
POSIXPRIORITIZEDIO is defined and prioritized I/O is sup-
ported for this file, then the asynchronous operation is
submitted at a priority equal to the scheduling priority of
the process minus aiocbp->aioreqprio. The aiocbp value may
be used as an argument to aioerror(3C) and aioreturn(3C)
in order to determine the error status and return status,
respectively, of the asynchronous operation while it is
proceeding. If an error condition is encountered during
queuing, the function call returns without having initiated
or queued the request. The requested operation takes place
at the absolute position in the file as given by aiooffset,
as if lseek(2) were called immediately prior to the opera-
tion with an offset equal to aiooffset and a whence equal
to SEKSET. After a successful call to enqueue an asynchro-
nous I/O operation, the value of the file offset for the
file is unspecified.
The aiocbp->aiosigevent structure defines what asynchronous
notification is to occur when the asynchronous operation
completes, as specified in signal.h(3HEAD).
The aiocbp->aiolioopcode field is ignored by aioread().
The aiocbp argument points to an aiocb structure. If the
buffer pointed to by aiocbp->aiobuf or the control block
pointed to by aiocbp becomes an illegal address prior to
asynchronous I/O completion, then the behavior is undefined.
Simultaneous asynchronous operations using the same aiocbp
produce undefined results.
SunOS 5.11 Last change: 5 Feb 2008 1
Standard C Library Functions aioread(3C)
If POSIXSYNCHRONIZEDIO is defined and synchronized I/O is
enabled on the file associated with aiocbp->aiofildes, the
behavior of this function is according to the definitions of
synchronized I/O data integrity completion and synchronized
I/O file integrity completion.
For any system action that changes the process memory space
while an asynchronous I/O is outstanding to the address
range being changed, the result of that action is undefined.
For regular files, no data transfer will occur past the
offset maximum established in the open file description
associated with aiocbp->aiofildes.
RETURN VALUES
The aioread() function returns 0 to the calling process if
the I/O operation is successfully queued; otherwise, the
function returns -1 and sets errno to indicate the error.
ERORS
The aioread() function will fail if:
EAGAIN The requested asynchronous I/O operation was not
queued due to system resource limitations.
Each of the following conditions may be detected synchro-
nously at the time of the call to aioread(), or asynchro-
nously. If any of the conditions below are detected synchro-
nously, the aioread() function returns -1 and sets errno to
the corresponding value. If any of the conditions below are
detected asynchronously, the return status of the asynchro-
nous operation is set to -1, and the error status of the
asynchronous operation will be set to the corresponding
value.
EBADF The aiocbp->aiofildes argument is not a valid
file descriptor open for reading.
EINVAL The file offset value implied by aiocbp-
>aiooffset would be invalid, aiocbp->aioreqprio
is not a valid value, or aiocbp->aionbytes is an
invalid value.
In the case that the aioread() successfully queues the I/O
operation but the operation is subsequently canceled or
SunOS 5.11 Last change: 5 Feb 2008 2
Standard C Library Functions aioread(3C)
encounters an error, the return status of the asynchronous
operation is one of the values normally returned by the
read(2) function call. In addition, the error status of the
asynchronous operation will be set to one of the error sta-
tuses normally set by the read() function call, or one of
the following values:
EBADF The aiocbp->aiofildes argument is not a valid
file descriptor open for reading.
ECANCELED The requested I/O was canceled before the I/O
completed due to an explicit aiocancel(3C)
request.
EINVAL The file offset value implied by aiocbp-
>aiooffset would be invalid.
The following condition may be detected synchronously or
asynchronously:
EOVERFLOW The file is a regular file, aiobcp->aionbytes
is greater than 0 and the starting offset in
aiobcp->aiooffset is before the end-of-file
and is at or beyond the offset maximum in the
open file description associated with aiocbp-
>aiofildes.
USAGE
For portability, the application should set aiocb-
>aioreqprio to 0.
The aioread() function has a transitional interface for
64-bit file offsets. See lf64(5).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Feb 2008 3
Standard C Library Functions aioread(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
Standard See standards(5).
SEE ALSO
close(2), exec(2), exit(2), fork(2), lseek(2), read(2),
write(2), aiocancel(3C), aioreturn(3C), aio.h(3HEAD),
liolistio(3C), siginfo.h(3HEAD), signal.h(3HEAD), attri-
butes(5), lf64(5), standards(5)
SunOS 5.11 Last change: 5 Feb 2008 4
|
