The first aiocbp->aio_nbytes
bytes of the file for which
aiocbp->aio_fildes
is a descriptor are written to the buffer
starting at aiocbp->aio_buf
. Reading starts at the absolute
position aiocbp->aio_offset
in the file.
If prioritized I/O is supported by the platform the
aiocbp->aio_reqprio
value is used to adjust the priority before
the request is actually enqueued.
The calling process is notified about the termination of the read
request according to the aiocbp->aio_sigevent
value.
When aio_read
returns, the return value is zero if no error
occurred that can be found before the process is enqueued. If such an
early error is found, the function returns @math{-1} and sets
errno
to one of the following values:
EAGAIN
ENOSYS
aio_read
function is not implemented.
EBADF
aiocbp->aio_fildes
descriptor is not valid. This condition
need not be recognized before enqueueing the request and so this error
might also be signaled asynchronously.
EINVAL
aiocbp->aio_offset
or aiocbp->aio_reqpiro
value is
invalid. This condition need not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
If aio_read
returns zero, the current status of the request
can be queried using aio_error
and aio_return
functions.
As long as the value returned by aio_error
is EINPROGRESS
the operation has not yet completed. If aio_error
returns zero,
the operation successfully terminated, otherwise the value is to be
interpreted as an error code. If the function terminated, the result of
the operation can be obtained using a call to aio_return
. The
returned value is the same as an equivalent call to read
would
have returned. Possible error codes returned by aio_error
are:
EBADF
aiocbp->aio_fildes
descriptor is not valid.
ECANCELED
EINVAL
aiocbp->aio_offset
value is invalid.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is in fact aio_read64
since the LFS interface transparently
replaces the normal implementation.
aio_read
function. The only
difference is that on 32 bit machines the file descriptor should
be opened in the large file mode. Internally aio_read64
uses
functionality equivalent to lseek64
(see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the reading,
as opposed to lseek
functionality used in aio_read
.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is available under the name aio_read
and so transparently
replaces the interface for small files on 32 bit machines.
To write data asynchronously to a file there exists an equivalent pair of functions with a very similar interface.
The first aiocbp->aio_nbytes
bytes from the buffer starting at
aiocbp->aio_buf
are written to the file for which
aiocbp->aio_fildes
is an descriptor, starting at the absolute
position aiocbp->aio_offset
in the file.
If prioritized I/O is supported by the platform the
aiocbp->aio_reqprio
value is used to adjust the priority before
the request is actually enqueued.
The calling process is notified about the termination of the read
request according to the aiocbp->aio_sigevent
value.
When aio_write
returns the return value is zero if no error
occurred that can be found before the process is enqueued. If such an
early error is found the function returns @math{-1} and sets
errno
to one of the following values.
EAGAIN
ENOSYS
aio_write
function is not implemented.
EBADF
aiocbp->aio_fildes
descriptor is not valid. This condition
needs not be recognized before enqueueing the request and so this error
might also be signaled asynchronously.
EINVAL
aiocbp->aio_offset
or aiocbp->aio_reqpiro
value is
invalid. This condition needs not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
In the case aio_write
returns zero the current status of the
request can be queried using aio_error
and aio_return
functions. As long as the value returned by aio_error
is
EINPROGRESS
the operation has not yet completed. If
aio_error
returns zero the operation successfully terminated,
otherwise the value is to be interpreted as an error code. If the
function terminated the result of the operation can be get using a call
to aio_return
. The returned value is the same as an equivalent
call to read
would have returned. Possible error code returned
by aio_error
are:
EBADF
aiocbp->aio_fildes
descriptor is not valid.
ECANCELED
EINVAL
aiocbp->aio_offset
value is invalid.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is in fact aio_write64
since the LFS interface transparently
replaces the normal implementation.
aio_write
function. The only
difference is that on 32 bit machines the file descriptor should
be opened in the large file mode. Internally aio_write64
uses
functionality equivalent to lseek64
(see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the writing,
as opposed to lseek
functionality used in aio_write
.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is available under the name aio_write
and so transparently
replaces the interface for small files on 32 bit machines.
Beside these functions with the more or less traditional interface
POSIX.1b also defines a function with can initiate more than one
operation at once and which can handled freely mixed read and write
operation. It is therefore similar to a combination of readv
and
writev
.
lio_listio
function can be used to enqueue an arbitrary
number of read and write requests at one time. The requests can all be
meant for the same file, all for different files or every solution in
between.
lio_listio
gets the nent requests from the array pointed to
by list. What operation has to be performed is determined by the
aio_lio_opcode
member in each element of list. If this
field is LIO_READ
an read operation is queued, similar to a call
of aio_read
for this element of the array (except that the way
the termination is signalled is different, as we will see below). If
the aio_lio_opcode
member is LIO_WRITE
an write operation
is enqueued. Otherwise the aio_lio_opcode
must be LIO_NOP
in which case this element of list is simply ignored. This
"operation" is useful in situations where one has a fixed array of
struct aiocb
elements from which only a few need to be handled at
a time. Another situation is where the lio_listio
call was
cancelled before all requests are processed (see section Cancellation of AIO Operations) and the remaining requests have to be reissued.
The other members of each element of the array pointed to by
list
must have values suitable for the operation as described in
the documentation for aio_read
and aio_write
above.
The mode argument determines how lio_listio
behaves after
having enqueued all the requests. If mode is LIO_WAIT
it
waits until all requests terminated. Otherwise mode must be
LIO_NOWAIT
and in this case the function returns immediately after
having enqueued all the requests. In this case the caller gets a
notification of the termination of all requests according to the
sig parameter. If sig is NULL
no notification is
send. Otherwise a signal is sent or a thread is started, just as
described in the description for aio_read
or aio_write
.
If mode is LIO_WAIT
the return value of lio_listio
is @math{0} when all requests completed successfully. Otherwise the
function return @math{-1} and errno
is set accordingly. To find
out which request or requests failed one has to use the aio_error
function on all the elements of the array list.
In case mode is LIO_NOWAIT
the function return @math{0} if
all requests were enqueued correctly. The current state of the requests
can be found using aio_error
and aio_return
as described
above. In case lio_listio
returns @math{-1} in this mode the
global variable errno
is set accordingly. If a request did not
yet terminate a call to aio_error
returns EINPROGRESS
. If
the value is different the request is finished and the error value (or
@math{0}) is returned and the result of the operation can be retrieved
using aio_return
.
Possible values for errno
are:
EAGAIN
EINVAL
AIO_LISTIO_MAX
.
EIO
ENOSYS
lio_listio
function is not supported.
If the mode parameter is LIO_NOWAIT
and the caller cancels
an request the error status for this request returned by
aio_error
is ECANCELED
.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is in fact lio_listio64
since the LFS interface
transparently replaces the normal implementation.
aio_listio
function. The only
difference is that only 32 bit machines the file descriptor should
be opened in the large file mode. Internally lio_listio64
uses
functionality equivalent to lseek64
(see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the reading or
writing, as opposed to lseek
functionality used in
lio_listio
.
When the sources are compiled with _FILE_OFFSET_BITS == 64
this
function is available under the name lio_listio
and so
transparently replaces the interface for small files on 32 bit
machines.
Go to the first, previous, next, last section, table of contents.