READ(2)

名称
read, readv, pread - 入力を読み取る

ライブラリ
libc

書式
<sys/types.h> <sys/uio.h> <unistd.h> ssize_t read(int d, void *buf, size_t nbytes) ssize_t readv(int d, const struct iovec *iov, int iovcnt) ssize_t pread(int d, void *buf, size_t nbytes, off_t offset)

解説
read() システムコールは、記述子 d で参照されたオブジェクトから buf が指すバッファへ nbytes のデータを読み取ろうとします。 readv() システムコールは同様の処理を実行しますが、配列 iov : iov[0], iov[1], ..., iov[iovcnt-1] のメンバで指定される iovcnt 個のバッファに入力データを分散させます。 pread() システムコールは同様の機能を実行しますが、 ファイル内の指定の位置から読み取った後、 ファイルポインタを変更しません。

readv() に対する iovec 構造体は次のように定義されます:

    struct iovec {
    	void   *iov_base;  /* ベースアドレス */
    	size_t iov_len;    /* 長さ */
    };

iovec の各エントリは、データを配置するべきメモリ領域のベースアドレスと 長さを指定しています。 readv() システムコールは、次のエントリに進む前に必ず領域を完全に満たします。

シーク可能なオブジェクト上では read() は d に結び付けられたポインタが指定する位置から開始します (lseek(2) を参照)。 read() からの戻り時に、ポインタは実際に読み取られたバイト数だけ増加させられます。

シークできないオブジェクトは必ず現在の位置から読み取られます。 そのようなオブジェクトに結び付けられたポインタの値は未定義です。

処理が成功すると、 read(), readv() および pread() は、実際に読み取られバッファ内に配置されたバイト数を返します。 記述子が通常ファイルを参照しており、 ファイルの終端までに十分な量のバイトがあれば、 システムは要求されたバイト数を読み取ることを保証しますが、 他のケースではそうではありません。

戻り値
正常に完了すると、実際に読み取られたバイト数が返されます。 ファイル終了 (EOF) が読み取られると 0 が返されます。 そうでない場合は -1 が返され、エラーを示すためにグローバル変数 errno が設定されます。

エラー
read(), readv() および pread() システムコールは次の場合を除いて正常に完了します:

[EBADF]
    d 引数は読取り用にオープンされた有効なファイルまたは ソケットの記述子ではありません。

[EFAULT]
    buf 引数は、プロセスに割り当てられたアドレス空間の範囲外を指しています。

[EIO]
    ファイルシステムから読み取っている間に入出力エラーが発生しました。

[EINTR]
    データが到着する前に、シグナルの配送により低速デバイスからの読取りが 割り込まれました。

[EINVAL]
    d に結び付けられたポインタが負でした。

[EAGAIN]
    ファイルは非ブロッキング入出力とマークされており、 読取りの準備ができたデータがありません。

[EISDIR]
    ファイル記述子が、ディレクトリ上での普通の読み込み操作を許可していない ファイルシステム (例えば NFS) に属しているディレクトリに 関連付けられています。

[EOPNOTSUPP]
    ファイル記述子が、普通の読み込み操作を許可していないファイルシステムおよび ファイルタイプに関連付けられています。

[EOVERFLOW]
    ファイル記述子が普通のファイルに関連付けられていて、 nbytes が 0 よりも大きく、 offset がファイルの末尾の前にあり、かつ offset がこのファイルシステムに収まるオフセットの最大値以上です。

さらに、 readv() は次のエラーのうちの 1 つを返すことがあります:

[EINVAL]
    iovcnt 引数が 0 以下であるか、または IOV_MAX より大きくなっています。

[EINVAL]
    iov 配列の中の iov_len 値の 1 つが負でした。

[EINVAL]
    iov 配列の中の iov_len 値の合計が 32 ビット整数をオーバフローしました。

[EFAULT]
    iov の一部が、プロセスに割り当てられたアドレス空間の範囲外を指しています。

pread() システムコールは次のエラーを返すこともあります:

[EINVAL]
    offset の値が負です。

[ESPIPE]
    ファイル記述子がパイプ、ソケット、または FIFO に結び付けられています。

関連項目
dup(2), fcntl(2), getdirentries(2), open(2), pipe(2), select(2), socket(2), socketpair(2), fread(3), readdir(3)

規格
read() システムコールは p1003.1-90 に適合しています。 readv() システムコールと pread() システムコールは xpg4.2 に適合しています。

歴史
pread() 関数は AT&T UNIX で登場しました。 readv() システムコールは 4.2BSD で登場しました。 read() 関数は AT&T UNIX で登場しました。