mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 18:21:39 +01:00
316 lines
8.7 KiB
Plaintext
316 lines
8.7 KiB
Plaintext
.TH aio 3 2002-09-12 "Linux 2.4" Linux AIO"
|
|
.SH NAME
|
|
aio \- Asynchronous IO
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <errno.h>
|
|
.sp
|
|
.br
|
|
.B #include <aio.h>
|
|
.sp
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The POSIX.1b standard defines a new set of I/O operations which can
|
|
significantly reduce the time an application spends waiting at I/O. The
|
|
new functions allow a program to initiate one or more I/O operations and
|
|
then immediately resume normal work while the I/O operations are
|
|
executed in parallel. This functionality is available if the
|
|
.IR "unistd.h"
|
|
file defines the symbol
|
|
.B "_POSIX_ASYNCHRONOUS_IO"
|
|
.
|
|
|
|
These functions are part of the library with realtime functions named
|
|
.IR "librt"
|
|
. They are not actually part of the
|
|
.IR "libc"
|
|
binary.
|
|
The implementation of these functions can be done using support in the
|
|
kernel (if available) or using an implementation based on threads at
|
|
userlevel. In the latter case it might be necessary to link applications
|
|
with the thread library
|
|
.IR "libpthread"
|
|
in addition to
|
|
.IR "librt"
|
|
and
|
|
.IR "libaio"
|
|
.
|
|
|
|
All AIO operations operate on files which were opened previously. There
|
|
might be arbitrarily many operations running for one file. The
|
|
asynchronous I/O operations are controlled using a data structure named
|
|
.IR "struct aiocb"
|
|
It is defined in
|
|
.IR "aio.h"
|
|
as follows.
|
|
|
|
.nf
|
|
struct aiocb
|
|
{
|
|
int aio_fildes; /* File desriptor. */
|
|
int aio_lio_opcode; /* Operation to be performed. */
|
|
int aio_reqprio; /* Request priority offset. */
|
|
volatile void *aio_buf; /* Location of buffer. */
|
|
size_t aio_nbytes; /* Length of transfer. */
|
|
struct sigevent aio_sigevent; /* Signal number and value. */
|
|
|
|
/* Internal members. */
|
|
struct aiocb *__next_prio;
|
|
int __abs_prio;
|
|
int __policy;
|
|
int __error_code;
|
|
__ssize_t __return_value;
|
|
|
|
#ifndef __USE_FILE_OFFSET64
|
|
__off_t aio_offset; /* File offset. */
|
|
char __pad[sizeof (__off64_t) - sizeof (__off_t)];
|
|
#else
|
|
__off64_t aio_offset; /* File offset. */
|
|
#endif
|
|
char __unused[32];
|
|
};
|
|
|
|
.fi
|
|
The POSIX.1b standard mandates that the
|
|
.IR "struct aiocb"
|
|
structure
|
|
contains at least the members described in the following table. There
|
|
might be more elements which are used by the implementation, but
|
|
depending upon these elements is not portable and is highly deprecated.
|
|
|
|
.TP
|
|
.IR "int aio_fildes"
|
|
This element specifies the file descriptor to be used for the
|
|
operation. It must be a legal descriptor, otherwise the operation will
|
|
fail.
|
|
|
|
The device on which the file is opened must allow the seek operation.
|
|
I.e., it is not possible to use any of the AIO operations on devices
|
|
like terminals where an
|
|
.IR "lseek"
|
|
call would lead to an error.
|
|
.TP
|
|
.IR "off_t aio_offset"
|
|
This element specifies the offset in the file at which the operation (input
|
|
or output) is performed. Since the operations are carried out in arbitrary
|
|
order and more than one operation for one file descriptor can be
|
|
started, one cannot expect a current read/write position of the file
|
|
descriptor.
|
|
.TP
|
|
.IR "volatile void *aio_buf"
|
|
This is a pointer to the buffer with the data to be written or the place
|
|
where the read data is stored.
|
|
.TP
|
|
.IR "size_t aio_nbytes"
|
|
This element specifies the length of the buffer pointed to by
|
|
.IR "aio_buf"
|
|
.
|
|
.TP
|
|
.IR "int aio_reqprio"
|
|
If the platform has defined
|
|
.B "_POSIX_PRIORITIZED_IO"
|
|
and
|
|
.B "_POSIX_PRIORITY_SCHEDULING"
|
|
, the AIO requests are
|
|
processed based on the current scheduling priority. The
|
|
.IR "aio_reqprio"
|
|
element can then be used to lower the priority of the
|
|
AIO operation.
|
|
.TP
|
|
.IR "struct sigevent aio_sigevent"
|
|
This element specifies how the calling process is notified once the
|
|
operation terminates. If the
|
|
.IR "sigev_notify"
|
|
element is
|
|
.B "SIGEV_NONE"
|
|
, no notification is sent. If it is
|
|
.B "SIGEV_SIGNAL"
|
|
,
|
|
the signal determined by
|
|
.IR "sigev_signo"
|
|
is sent. Otherwise,
|
|
.IR "sigev_notify"
|
|
must be
|
|
.B "SIGEV_THREAD"
|
|
. In this case, a thread
|
|
is created which starts executing the function pointed to by
|
|
.IR "sigev_notify_function"
|
|
.
|
|
.TP
|
|
.IR "int aio_lio_opcode"
|
|
This element is only used by the
|
|
.IR "lio_listio"
|
|
and
|
|
.IR "lio_listio64"
|
|
functions. Since these functions allow an
|
|
arbitrary number of operations to start at once, and each operation can be
|
|
input or output (or nothing), the information must be stored in the
|
|
control block. The possible values are:
|
|
.TP
|
|
.B "LIO_READ"
|
|
Start a read operation. Read from the file at position
|
|
.IR "aio_offset"
|
|
and store the next
|
|
.IR "aio_nbytes"
|
|
bytes in the
|
|
buffer pointed to by
|
|
.IR "aio_buf"
|
|
.
|
|
.TP
|
|
.B "LIO_WRITE"
|
|
Start a write operation. Write
|
|
.IR "aio_nbytes"
|
|
bytes starting at
|
|
.IR "aio_buf"
|
|
into the file starting at position
|
|
.IR "aio_offset"
|
|
.
|
|
.TP
|
|
.B "LIO_NOP"
|
|
Do nothing for this control block. This value is useful sometimes when
|
|
an array of
|
|
.IR "struct aiocb"
|
|
values contains holes, i.e., some of the
|
|
values must not be handled although the whole array is presented to the
|
|
.IR "lio_listio"
|
|
function.
|
|
|
|
When the sources are compiled using
|
|
.B "_FILE_OFFSET_BITS == 64"
|
|
on a
|
|
32 bit machine, this type is in fact
|
|
.IR "struct aiocb64"
|
|
, since the LFS
|
|
interface transparently replaces the
|
|
.IR "struct aiocb"
|
|
definition.
|
|
.PP
|
|
For use with the AIO functions defined in the LFS, there is a similar type
|
|
defined which replaces the types of the appropriate members with larger
|
|
types but otherwise is equivalent to
|
|
.IR "struct aiocb"
|
|
. Particularly,
|
|
all member names are the same.
|
|
|
|
.nf
|
|
/* The same for the 64bit offsets. Please note that the members aio_fildes
|
|
to __return_value have to be the same in aiocb and aiocb64. */
|
|
#ifdef __USE_LARGEFILE64
|
|
struct aiocb64
|
|
{
|
|
int aio_fildes; /* File desriptor. */
|
|
int aio_lio_opcode; /* Operation to be performed. */
|
|
int aio_reqprio; /* Request priority offset. */
|
|
volatile void *aio_buf; /* Location of buffer. */
|
|
size_t aio_nbytes; /* Length of transfer. */
|
|
struct sigevent aio_sigevent; /* Signal number and value. */
|
|
|
|
/* Internal members. */
|
|
struct aiocb *__next_prio;
|
|
int __abs_prio;
|
|
int __policy;
|
|
int __error_code;
|
|
__ssize_t __return_value;
|
|
|
|
__off64_t aio_offset; /* File offset. */
|
|
char __unused[32];
|
|
};
|
|
|
|
.fi
|
|
.TP
|
|
.IR "int aio_fildes"
|
|
This element specifies the file descriptor which is used for the
|
|
operation. It must be a legal descriptor since otherwise the operation
|
|
fails for obvious reasons.
|
|
The device on which the file is opened must allow the seek operation.
|
|
I.e., it is not possible to use any of the AIO operations on devices
|
|
like terminals where an
|
|
.IR "lseek"
|
|
call would lead to an error.
|
|
.TP
|
|
.IR "off64_t aio_offset"
|
|
This element specifies at which offset in the file the operation (input
|
|
or output) is performed. Since the operation are carried in arbitrary
|
|
order and more than one operation for one file descriptor can be
|
|
started, one cannot expect a current read/write position of the file
|
|
descriptor.
|
|
.TP
|
|
.IR "volatile void *aio_buf"
|
|
This is a pointer to the buffer with the data to be written or the place
|
|
where the read data is stored.
|
|
.TP
|
|
.IR "size_t aio_nbytes"
|
|
This element specifies the length of the buffer pointed to by
|
|
.IR "aio_buf"
|
|
.
|
|
.TP
|
|
.IR "int aio_reqprio"
|
|
If for the platform
|
|
.B "_POSIX_PRIORITIZED_IO"
|
|
and
|
|
.B "_POSIX_PRIORITY_SCHEDULING"
|
|
are defined the AIO requests are
|
|
processed based on the current scheduling priority. The
|
|
.IR "aio_reqprio"
|
|
element can then be used to lower the priority of the
|
|
AIO operation.
|
|
.TP
|
|
.IR "struct sigevent aio_sigevent"
|
|
This element specifies how the calling process is notified once the
|
|
operation terminates. If the
|
|
.IR "sigev_notify"
|
|
, element is
|
|
.B "SIGEV_NONE"
|
|
no notification is sent. If it is
|
|
.B "SIGEV_SIGNAL"
|
|
,
|
|
the signal determined by
|
|
.IR "sigev_signo"
|
|
is sent. Otherwise,
|
|
.IR "sigev_notify"
|
|
must be
|
|
.B "SIGEV_THREAD"
|
|
in which case a thread
|
|
which starts executing the function pointed to by
|
|
.IR "sigev_notify_function"
|
|
.
|
|
.TP
|
|
.IR "int aio_lio_opcode"
|
|
This element is only used by the
|
|
.IR "lio_listio"
|
|
and
|
|
.IR "lio_listio64"
|
|
functions. Since these functions allow an
|
|
arbitrary number of operations to start at once, and since each operation can be
|
|
input or output (or nothing), the information must be stored in the
|
|
control block. See the description of
|
|
.IR "struct aiocb"
|
|
for a description
|
|
of the possible values.
|
|
.PP
|
|
When the sources are compiled using
|
|
.B "_FILE_OFFSET_BITS == 64"
|
|
on a
|
|
32 bit machine, this type is available under the name
|
|
.IR "struct aiocb64"
|
|
, since the LFS transparently replaces the old interface.
|
|
.SH "RETURN VALUES"
|
|
.SH ERRORS
|
|
.SH "SEE ALSO"
|
|
.BR aio_cancel(3),
|
|
.BR aio_cancel64(3),
|
|
.BR aio_error(3),
|
|
.BR aio_error64(3),
|
|
.BR aio_fsync(3),
|
|
.BR aio_fsync64(3),
|
|
.BR aio_init(3),
|
|
.BR aio_read(3),
|
|
.BR aio_read64(3),
|
|
.BR aio_return(3),
|
|
.BR aio_return64(3),
|
|
.BR aio_suspend(3),
|
|
.BR aio_suspend64(3),
|
|
.BR aio_write(3),
|
|
.BR aio_write64(3),
|
|
.BR errno(3),
|