名称

read, readv, pread, preadv — 入力を読み込む

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/types.h>
#include < unistd.h>

ssize_t
read( int fd, void *buf, size_t nbytes);

ssize_t
pread( int fd, void *buf, size_t nbytes, off_t offset);

#include < sys/uio.h>

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

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

解説

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

readv() と preadv() のための iovec 構造体は、次のように定義されます:

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

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

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

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

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

戻り値

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

エラー

read(), readv(), pread() と preadv() システムコールは、次の場合を除いて正常に完了します:

[ EBADF]

fd 引数は、読み込み用にオープンされた有効なファイルまたはソケットの記述子ではありません。

[ ECONNRESET]

fd 引数がソケットを参照していて、そのリモート側のソケット端が強制的にクローズされました。

[ EFAULT]

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

[ EIO]

ファイルシステムから読み込んでいる間に入出力エラーが発生しました。

[ EBUSY]

ファイルからの読み込みに失敗しました、例えば、<pid>が停止されない、 /proc/<pid>/regs。

[ EINTR]

低速デバイス (すなわち、任意の時間ブロックされるかもしれないもの) からの読み込みは、データが到着する前にシグナルの配信により割り込まれました。

[ EINVAL]

fd に結び付けられたポインタが負でした。

[ EAGAIN]

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

[ EISDIR]

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

[ EOPNOTSUPP]

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

[ EOVERFLOW]

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

[ EINVAL]

値 nbytes が INT_MAX よりも大きな値です。

さらに、 readv() と preadv() は、次のエラーのうちの 1 つを返します:

[ EINVAL]

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

[ EINVAL]

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

[ EINVAL]

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

[ EFAULT]

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

pread() と preadv() システムコールは、次のエラーを返します:

[ 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() システムコールは、 IEEE Std 1003.1-1990 (“POSIX.1”) に適合するはずです。 readv() と pread() システムコールは、 X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”) に適合するはずです。

歴史

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