名前

readv, writev, preadv, pwritev, preadv2, pwritev2 - 複数のバッファーへの読み書きを行なう

書式

#include <sys/uio.h>

ssize_t readv(int fd, const struct iovec *iov, int iovcnt);

ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

ssize_t preadv(int fd, const struct iovec *iov, int iovcnt,
               off_t offset);

ssize_t pwritev(int fd, const struct iovec *iov, int iovcnt,
                off_t offset);

 ssize_t preadv2(int fd, const struct iovec *iov, int iovcnt,
                off_t offset, int flags);

 ssize_t pwritev2(int fd, const struct iovec *iov, int iovcnt,
                 off_t offset, int flags);

preadv(), pwritev():
Since glibc 2.19:
_DEFAULT_SOURCE
Glibc 2.19 and earlier:
_BSD_SOURCE

説明

readv() システムコールは、ファイルディスクリプター fd に関連付けられた ファイルから、 iovcnt 個のバッファー分のデータを読み込み、 iov で指定 されたバッファーに格納する ("scatter input";「ばらまき入力」)。

writev() システムコールは、 iov で指定されたバッファーから最大 iovcnt 個のバッファー分のデータを取り出し、 ファイルディスクリプター fd に関連付けら れたファイルに書き込む ("gather output";「かき集め出力」)。

ポインター iov は iovec 構造体の配列へのポインターである。 iovec 構造体は <sys/uio.h> で以下のように定義されている:

struct iovec {


    void  *iov_base;    /* Starting address */


    size_t iov_len;     /* Number of bytes to transfer */
};

readv() システムコールは、複数のバッファーにデータを読み込む点を除いて read(2) と全く同様の動作を行う。

writev() システムコールは、複数のバッファーのデータを書き出す点以外は write(2) と全く同様の動作を行う。

バッファーは配列の順序で処理される。これは、 readv() が iov[0] が完全に一杯になるまでデータを詰めてから、 iov[1] などに進むことを意味する (データが十分ない場合は、 iov が指すバッファーのいずれも一杯にならない)。 同様に、 writev() は iov[0] の内容を全部書き出してから iov[1] などに進む。

readv() と writev() によるデータ転送は atomic に行われる。つまり、 writev() によるデータ書き込みは一つのブロックとして行われ、他のプロセスの write による書き込みと混ざり合うことはない (例外に関しては pipe(7) を参照のこと)。同様に、 readv() はファイルから連続するデータブロックが読み出すことが保証され、 同じファイル記述 (file description; open(2) 参照) を参照するファイルディスクリプターを持つ他のスレッドやプロセスが 実行した read 操作の影響を受けることはない。

返り値

成功した場合、 readv(), preadv, preadv2 は読み込んだバイト数を返し、 writev(), pwritev(), pwritev2 は書き込んだバイト数を返す。

Note that it is not an error for a successful call to transfer fewer bytes than requested (see read(2) and write(2)).

エラーの場合は -1 が返され、 errno が適切に設定される。

エラー

read(2) や write(2) と同じエラーが定義されている。さらに、 preadv(), preadv2, pwritev(), pwritev2 は lseek(2) と同じ理由でも失敗する。また、追加で以下のエラーが定義されている:

EINVAL

iov_len の合計が ssize_t の範囲をオーバーフローした。

EINVAL

ベクタ数 iovcnt が 0 より小さいか許可された最大値よりも大きかった。

EOPNOTSUPP

未知のフラグが flags に指定された。

バージョン

preadv() と pwritev() は Linux 2.6.30 で初めて登場した。 ライブラリによるサポートは glibc 2.10 で追加された。

preadv2() と pwritev2() は Linux 4.6 で初めて登場した。ライブラリによるサポートは glibc 2.26 で追加された。

準拠

readv(), writev(): POSIX.1-2001, POSIX.1-2008, 4.4BSD (これらのシステムコールは 4.2BSD で初めて登場した)

preadv(), pwritev(): 非標準だが、最近の BSD にも存在する。

preadv2(), pwritev2(): 非標準の Linux による拡張。

注意

POSIX.1 では、 iov で渡すことができる要素数に上限を設ける実装が認められている。 実装はこの上限値を広告することができ、 <limits.h> の IOV_MAX を定義することや、 実行時に sysconf(_SC_IOV_MAX) の返り値経由で知ることができる。 最近の Linux では、 この上限値は 1024 である。 Linux 2.0 の頃は、 この値は 16 であった。

例

以下のサンプルコードは writev() の使用方法を示すものである。

char *str0 = "hello ";
char *str1 = "world\n";
struct iovec iov[2];
ssize_t nwritten;
iov[0].iov_base = str0;
iov[0].iov_len = strlen(str0);
iov[1].iov_base = str1;
iov[1].iov_len = strlen(str1);
nwritten = writev(STDOUT_FILENO, iov, 2);

関連項目

pread(2), read(2), write(2)

この文書について

この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。