pread(2)

read, readv, pread − 入力を読み取る

標準 C ライブラリ (libc, −lc)

#include <sys/types.h>
#include <sys/uio.h>
#include <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() システムコールは次の場合を除いて正常に完了 します:

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() システムコールは ISO/IEC 9945-1:1990 (‘‘POSIX.1’’) に適合していま す。 readv() システムコールと pread() システムコールは X/Open Portability Guide Issue 4.2 (‘‘XPG4.2’’) に適合しています。

pread() 関数は AT&T System V.4 UNIX で登場しました。 readv() システムコー ルは 4.2BSD で登場しました。 read() 関数は Version 6 AT&T UNIX で登場しま した。

FreeBSD 10.0 October 16, 2004 FreeBSD 10.0