.\" t
.\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2012-05-02, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH AIO 7 2014\-04\-06 Linux "Linux Programmer's Manual"
.SH 名前
aio \- POSIX 非同期 I/O の概要
.SH 説明
POSIX 非同期 (AIO) インターフェースを使うと、アプリケーションは、非同期
に (つまり、バックグラウンドで) 実行されるI/O 操作を一つ以上発行できる
ようになる。アプリケーションは I/O 操作の完了の通知方法を選択することが
できる。選択できる通知方法は、シグナルの配送、スレッドの起動、通知を行
わないである。

POSIX AIO インターフェースは以下の関数で構成されている。
.TP  16
\fBaio_read\fP(3)
読み出しリクエストをキューに入れる。
\fBread\fP(2) の非同期版である。
.TP 
\fBaio_write\fP(3)
書き込みリクエストをキューに入れる。
\fBwrite\fP(2) の非同期版である。
.TP 
\fBaio_fsync\fP(3)
ファイルディスクリプターに対して行われた I/O 操作の
同期 (sync) リクエストをキューに入れる。
\fBfsync\fP(2) や \fBfdatasync\fP(2) の非同期版である。
.TP 
\fBaio_error\fP(3)
キューに入れられた I/O リクエストのエラー状態を取得する。
.TP 
\fBaio_return\fP(3)
完了した I/O リクエストの終了ステータスを取得する。
.TP 
\fBaio_suspend\fP(3)
指定された I/O リクエストの集合 (要素は一つ以上) が完了するまで、
呼び出し側の実行を停止 (suspend) する。
.TP 
\fBaio_cancel\fP(3)
指定されたファイルディスクリプターに関する
完了していない I/O リクエストのキャンセルを試みる。
.TP 
\fBlio_listio\fP(3)
一回の関数呼び出しで複数の I/O リクエストをキューに入れる。
.PP
\fIaiocb\fP ("非同期 I/O 制御ブロック (asynchronous I/O control block)")
構造体は、I/O 操作を制御するパラメーターを定義する。この型の引き数は上記
の全ての関数で使用されている。この構造体は以下の通りである。
.PP
.in +4n
.nf
#include <aiocb.h>

struct aiocb {
    /* The order of these fields is implementation\-dependent */

    int             aio_fildes;     /* File descriptor */
    off_t           aio_offset;     /* File offset */
    volatile void  *aio_buf;        /* Location of buffer */
    size_t          aio_nbytes;     /* Length of transfer */
    int             aio_reqprio;    /* Request priority */
    struct sigevent aio_sigevent;   /* Notification method */
    int             aio_lio_opcode; /* Operation to be performed;
                                       lio_listio() only */

    /* Various implementation\-internal fields not shown */
};

/* Operation codes for \(aqaio_lio_opcode\(aq: */

enum { LIO_READ, LIO_WRITE, LIO_NOP };

.fi
.in
この構造体のフィールドは以下の通りである。
.TP  16
\fIaio_filedes\fP
I/O 操作の実行対象となるファイルディスクリプター。
.TP 
\fIaio_offset\fP
I/O 操作を行うファイルオフセットを示す。
.TP 
\fIaio_buf\fP
読み出し操作、書き込み操作でデータ転送に使用されるバッファー。
.TP 
\fIaio_nbytes\fP
\fIaio_buf\fP が指すバッファーのサイズ。
.TP 
\fIaio_reqprio\fP
このフィールドでは、呼び出したスレッドのリアルタイム優先度から
減算する値を指定する。この I/O リクエストの実行の優先度を
決定するために使用される (\fBpthread_setschedparam\fP(3) 参照)。
指定する値は 0 と \fIsysconf(_SC_AIO_PRIO_DELTA_MAX)\fP が返す値の間で
なければならない。このフィールドは、ファイル同期操作では無視される。
.TP 
\fIaio_sigevent\fP
このフィールドは、非同期 I/O 操作が完了した際に呼び出し側に
どのように通知を行うかを指定する構造体である。
\fIaio_sigevent.sigev_notify\fP に指定できる値は、
\fBSIGEV_NONE\fP, \fBSIGEV_SIGNAL\fP, \fBSIGEV_THREAD\fP である。
詳細は \fBsigevent\fP(7) を参照。
.TP 
\fIaio_lio_opcode\fP
実行される操作の種別。
\fBlio_listio\fP(3) でのみ使用される。
.PP
上記のリストにある標準の関数に加えて、GNU C ライブラリでは
以下に示す POSIX AIO API に対する拡張が提供されている。
.TP  16
\fBaio_init\fP(3)
glibc の POSIX AIO 実装の動作を調整するパラメーターを設定する。
.SH エラー
.TP 
\fBEINVAL\fP
\fIaiocb\fP 構造体の \fIaio_reqprio\fP フィールドが、0 より小さいか、
\fIsysconf(_SC_AIO_PRIO_DELTA_MAX)\fP が返す上限よりも大きかった。
.SH バージョン
POSIX AIO インターフェイスは glibc バージョン 2.1 以降で提供されている。
.SH 準拠
POSIX.1\-2001, POSIX.1\-2008.
.SH 注意
使用前に制御ブロックバッファーを 0 で埋めるのはよい考えである
(\fBmemset\fP(3) 参照)。I/O 操作が実行中の間は、制御ブロックバッファーと
\fIaio_buf\fP が指すバッファーを変更してはならない。I/O 操作が完了するまで、
これらのバッファーは有効な状態に保たなければならない。

同じ \fIaiocb\fP 構造体を使って、同時に複数の非同期の読み出し操作や
書き込み操作を行った場合に、どのような結果になるかは未定義である。

.\" http://lse.sourceforge.net/io/aio.html
.\" http://lse.sourceforge.net/io/aionotes.txt
.\" http://lwn.net/Articles/148755/
現在の Linux では、POSIX AIO 実装は glibc によりユーザー空間で提供
されている。このため、制限がいくつかあり、最も顕著なものは、I/O 操作を
実行する複数のスレッドの管理コストが高く、スケーラビリティに欠けること
である。しばらくの間、カーネルのステートマシンによる非同期 I/O の実装
の作業が行われているが (\fBio_submit\fP(2), \fBio_setup\fP(2),
\fBio_cancel\fP(2), \fBio_destroy\fP(2), \fBio_getevents\fP(2) 参照)、
この実装はまだ POSIX AIO 実装をカーネルシステムコールにより
再実装するほど成熟したものてはない。
.SH 例
下記のプログラムは、コマンドライン引き数で指定された名前のファイルを
それぞれオープンし、得られたファイルディスクリプターに対するリクエストを
\fBaio_read\fP(3) を使ってキューに入れる。その後、このプログラムはループに
入り、定期的に \fBaio_error\fP(3) を使ってまだ実行中の各 I/O 操作を監視す
る。各 I/O リクエストは、シグナルの配送による完了通知が行われるように設
定される。全ての I/O リクエストが完了した後、\fBaio_return\fP(3) を使って
それぞれのステータスを取得する。

\fBSIGQUIT\fP シグナル (control\-\e をタイプすると生成できる) を送ると、
このプログラムは \fBaio_cancel\fP(3) を使って
完了していない各リクエストにキャンセル要求を送る。

以下はこのプログラムを実行した際の出力例である。
この例では、標準入力に対して 2 つのリクエストを行い、
"abc" と "x" という 2 行の入力を行っている。

.in +4n
.nf
$ \fB./a.out /dev/stdin /dev/stdin\fP
opened /dev/stdin on descriptor 3
opened /dev/stdin on descriptor 4
aio_error():
    for request 0 (descriptor 3): In progress
    for request 1 (descriptor 4): In progress
\fBabc\fP
I/O completion signal received
aio_error():
    for request 0 (descriptor 3): I/O succeeded
    for request 1 (descriptor 4): In progress
aio_error():
    for request 1 (descriptor 4): In progress
\fBx\fP
I/O completion signal received
aio_error():
    for request 1 (descriptor 4): I/O succeeded
All I/O requests completed
aio_return():
    for request 0 (descriptor 3): 4
    for request 1 (descriptor 4): 2
.fi
.in
.SS プログラムのソース
\&
.nf
#include <stdlib.h>
#include <unistd.h>
#include <stdio.h>
#include <errno.h>
#include <aio.h>
#include <signal.h>

#define BUF_SIZE 20     /* Size of buffers for read operations */

#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)

#define errMsg(msg)  do { perror(msg); } while (0)

struct ioRequest {      /* Application\-defined structure for tracking
                           I/O requests */
    int           reqNum;
    int           status;
    struct aiocb *aiocbp;
};

static volatile sig_atomic_t gotSIGQUIT = 0;
                        /* On delivery of SIGQUIT, we attempt to
                           cancel all outstanding I/O requests */

static void             /* Handler for SIGQUIT */
quitHandler(int sig)
{
    gotSIGQUIT = 1;
}

#define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */

static void                 /* Handler for I/O completion signal */
aioSigHandler(int sig, siginfo_t *si, void *ucontext)
{
    write(STDOUT_FILENO, "I/O completion signal received\en", 31);

    /* The corresponding ioRequest structure would be available as
           struct ioRequest *ioReq = si\->si_value.sival_ptr;
       and the file descriptor would then be available via
           ioReq\->aiocbp\->aio_fildes */
}

int
main(int argc, char *argv[])
{
    struct ioRequest *ioList;
    struct aiocb *aiocbList;
    struct sigaction sa;
    int s, j;
    int numReqs;        /* Total number of queued I/O requests */
    int openReqs;       /* Number of I/O requests still in progress */

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <pathname> <pathname>...\en",
                argv[0]);
        exit(EXIT_FAILURE);
    }

    numReqs = argc \- 1;

    /* Allocate our arrays */

    ioList = calloc(numReqs, sizeof(struct ioRequest));
    if (ioList == NULL)
        errExit("calloc");

    aiocbList = calloc(numReqs, sizeof(struct aiocb));
    if (aiocbList == NULL)
        errExit("calloc");

    /* Establish handlers for SIGQUIT and the I/O completion signal */

    sa.sa_flags = SA_RESTART;
    sigemptyset(&sa.sa_mask);

    sa.sa_handler = quitHandler;
    if (sigaction(SIGQUIT, &sa, NULL) == \-1)
        errExit("sigaction");

    sa.sa_flags = SA_RESTART | SA_SIGINFO;
    sa.sa_sigaction = aioSigHandler;
    if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
        errExit("sigaction");

    /* Open each file specified on the command line, and queue
       a read request on the resulting file descriptor */

    for (j = 0; j < numReqs; j++) {
        ioList[j].reqNum = j;
        ioList[j].status = EINPROGRESS;
        ioList[j].aiocbp = &aiocbList[j];

        ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
        if (ioList[j].aiocbp\->aio_fildes == \-1)
            errExit("open");
        printf("opened %s on descriptor %d\en", argv[j + 1],
                ioList[j].aiocbp\->aio_fildes);

        ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
        if (ioList[j].aiocbp\->aio_buf == NULL)
            errExit("malloc");

        ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
        ioList[j].aiocbp\->aio_reqprio = 0;
        ioList[j].aiocbp\->aio_offset = 0;
        ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
        ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
        ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
                                &ioList[j];

        s = aio_read(ioList[j].aiocbp);
        if (s == \-1)
            errExit("aio_read");
    }

    openReqs = numReqs;

    /* Loop, monitoring status of I/O requests */

    while (openReqs > 0) {
        sleep(3);       /* Delay between each monitoring step */

        if (gotSIGQUIT) {

            /* On receipt of SIGQUIT, attempt to cancel each of the
               outstanding I/O requests, and display status returned
               from the cancellation requests */

            printf("got SIGQUIT; canceling I/O requests: \en");

            for (j = 0; j < numReqs; j++) {
                if (ioList[j].status == EINPROGRESS) {
                    printf("    Request %d on descriptor %d:", j,
                            ioList[j].aiocbp\->aio_fildes);
                    s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
                            ioList[j].aiocbp);
                    if (s == AIO_CANCELED)
                        printf("I/O canceled\en");
                    else if (s == AIO_NOTCANCELED)
                            printf("I/O not canceled\en");
                    else if (s == AIO_ALLDONE)
                        printf("I/O all done\en");
                    else
                        errMsg("aio_cancel");
                }
            }

            gotSIGQUIT = 0;
        }

        /* Check the status of each I/O request that is still
           in progress */

        printf("aio_error():\en");
        for (j = 0; j < numReqs; j++) {
            if (ioList[j].status == EINPROGRESS) {
                printf("    for request %d (descriptor %d): ",
                        j, ioList[j].aiocbp\->aio_fildes);
                ioList[j].status = aio_error(ioList[j].aiocbp);

                switch (ioList[j].status) {
                case 0:
                    printf("I/O succeeded\en");
                    break;
                case EINPROGRESS:
                    printf("In progress\en");
                    break;
                case ECANCELED:
                    printf("Canceled\en");
                    break;
                default:
                    errMsg("aio_error");
                    break;
                }

                if (ioList[j].status != EINPROGRESS)
                    openReqs\-\-;
            }
        }
    }

    printf("All I/O requests completed\en");

    /* Check status return of all I/O requests */

    printf("aio_return():\en");
    for (j = 0; j < numReqs; j++) {
        ssize_t s;

        s = aio_return(ioList[j].aiocbp);
        printf("    for request %d (descriptor %d): %zd\en",
                j, ioList[j].aiocbp\->aio_fildes, s);
    }

    exit(EXIT_SUCCESS);
}
.fi
.SH 関連項目
.ad l
.nh
\fBio_cancel\fP(2), \fBio_destroy\fP(2), \fBio_getevents\fP(2), \fBio_setup\fP(2),
\fBio_submit\fP(2), \fBaio_cancel\fP(3), \fBaio_error\fP(3), \fBaio_init\fP(3),
\fBaio_read\fP(3), \fBaio_return\fP(3), \fBaio_write\fP(3), \fBlio_listio\fP(3)

.UR http://www.squid\-cache.org\:/~adrian\:/Reprint\-Pulavarty\-OLS2003.pdf
.UE
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。