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 {
    	char   *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]
    ファイルは非ブロッキング入出力とマークされており、 読取りの準備ができたデータがありません。

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

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

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

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

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

pread() 呼び出しも次のエラーを返すことがあります。

[EINVAL]
    指定のファイルオフセットが有効ではありません。

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

関連項目
dup(2), fcntl(2), open(2), pipe(2), select(2), socket(2), socketpair(2)

規格
read() 関数は p1003.1-90 に準拠しています。 readv() 関数と pread() 関数は xpg4.2 に準拠しています。

歴史
pread() 関数は AT&T UNIX で登場しました。 readv() 関数は 4.2BSD で登場しました。 read() 関数は AT&T UNIX で登場しました。