Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
read - ファイルディスクリプターから読み込む
書式
#include <unistd.h>
ssize_t read(int fd, void *buf, size_t count);
説明
read() はファイルディスクリプター (file descriptor) fd から最大 count バイトを buf で始
まるバッファーへ読み込もうとする。
seek に対応しているファイルでは、read はファイルオフセットから行われ、ファイルオフセットは
読み込んだバイト数分だけ進められる。ファイルオフセットがファイル末尾かそれより先の場合
は、読み出しは行われず、 read() は 0 を返す。
count が 0 の場合、 read() は以下で説明するエラーを検出する場合がある。 どのエラーもなかっ
た場合、もしくは read() がエラーのチェックを行わない場合、 count が 0 で呼び出された
read() は 0 を返し、何も行わない。
According to POSIX.1, if count is greater than SSIZE_MAX, the result is
implementation-defined; see NOTES for the upper limit on Linux.
返り値
成功した場合、読み込んだバイト数を返す (0 はファイルの終りを意味する)。 ファイル位置はこの
数だけ進められる。 この数が要求した数より小さかったとしてもエラーではない; 例えば今すぐに
は実際にそれだけの数しかない場合 (ファイルの最後に近いのかも しれないし、パイプ (pipe) や
端末 (terminal) から読み込んでいるかもしれない) や read() がシグナル (signal) によって割
り込まれた場合にこれは起こりえる。
エラーの場合は、-1 が返され、 errno が適切に設定される。この場合はファイル位置が変更される
かどうかは 不定である。
エラー
EAGAIN ファイルディスクリプター fd がソケット以外のファイルを参照していて、 非停止
(nonblocking) モード (O_NONBLOCK) に設定されており、読み込みを行うと停止する状況に
ある。 O_NONBLOCK フラグの詳細は open(2) を参照。
EAGAIN または EWOULDBLOCK
ファイルディスクリプター fd がソケットを参照していて、非停止 (nonblocking) モード
(O_NONBLOCK) に設定されており、読み込みを行うと停止する状況にある。 POSIX.1-2001
は、この場合にどちらのエラーを返すことも認めており、 これら 2 つの定数が同じ値を持
つことも求めていない。 したがって、移植性が必要なアプリケーションでは、両方の可能性
を 確認すべきである。
EBADF fd が有効なファイルディスクリプターでないか、読み込みのために オープン (open) され
ていない。
EFAULT buf がアクセス可能なアドレス空間の外にある。
EINTR 何のデータも読み込まないうちにシグナルに割り込まれた。 signal(7) 参照。
EINVAL fd は読み込みに適していないオブジェクトを参照している。 もしくは、ファイルが
O_DIRECT フラグを指定してオープンされているが、 buf に指定されたアドレス、 count に
指定された値、 ファイルオフセットのいずれかの アラインメントが不適切である。
EINVAL fd が timerfd_create(2) の呼び出しで作成されたが、 read() に間違ったサイズのバッ
ファーが渡された。 さらなる情報は timerfd_create(2) を参照のこと。
EIO I/O error. This will happen for example when the process is in a background
process group, tries to read from its controlling terminal, and either it is
ignoring or blocking SIGTTIN or its process group is orphaned. It may also occur
when there is a low-level I/O error while reading from a disk or tape. A further
possible cause of EIO on networked filesystems is when an advisory lock had been
taken out on the file descriptor and this lock has been lost. See the Lost locks
section of fcntl(2) for further details.
EISDIR fd がディレクトリを参照している。
fd に接続されたオブジェクトによっては、他のエラーが起こるかもしれない。
準拠
SVr4, 4.3BSD, POSIX.1-2001.
注意
The types size_t and ssize_t are, respectively, unsigned and signed integer data types
specified by POSIX.1.
On Linux, read() (and similar system calls) will transfer at most 0x7ffff000
(2,147,479,552) bytes, returning the number of bytes actually transferred. (This is true
on both 32-bit and 64-bit systems.)
NFS において。少量のデータを読み込む場合、最初の時のみにタイム スタンプが更新され、続く
コールでは更新されないだろう。 これはクライアント側で属性のキャッシングを行なうためであ
る。 なぜならば、もし全ての NFS クライアントが st_atime (最終ファイルアクセス時刻) の更新
をサーバーに送らず、クライアント側でキャッシュを読むことに満足して いれば、サーバー側での
read は発生しないので st_atime の更新は行なわれからだ。 UNIX の方式では、クライアント側の
属性のキャッシングを無効にすることで、 これを得ることができる。しかしほとんどの状況ではこ
れは続くサーバーの 負荷を増加させ、パフォーマンスの低下をもたらす。
バグ
POSIX.1-2008/SUSv4 セクション XSI 2.9.7 ("Thread Interactions with Regular File
Operations") によると、
以下のすべての関数では、 通常ファイルもしくはシンボリックリンクに対する操作では
POSIX.1-2008 で規定された効果が互いにアトミックに行われなければならない: ...
この後に書かれている API の中に read() と readv(2) である。 スレッド（やプロセス) 間でアト
ミックに適用することが求められる効果の一つとして、 ファイルオフセットの更新がある。 しかし
ながら、 バージョン 3.14 より前の Linux では、 この限りではない。 オープンファイル記述
(open file description) を共有する 2 つのプロセスが同時に read() (や readv(2)) を実行した
場合、 この I/O 操作ではファイルオフセットの更新に関してはアトミックではなく、 2 つのプロ
セスの read で取得されるデータブロックが (間違って) 重なる可能性がある。 この問題は Linux
3.14 で修正された。
関連項目
close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2), readlink(2),
readv(2), select(2), write(2), fread(3)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。