read(2)

構文

#include <unistd.h>

ssize_t read(int fildes, void *buf, size_t nbyte);

ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset);

#include <sys/uio.h>

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

説明

read() 関数は、オープンしているファイル記述子 fildes に対応するファイルから nbyte バイトを buf が指しているバッファーへ読み込みます。

nbyte が ０ の場合、 read() は ０ を返すだけで、その他の戻り値はありません。

シークをサポートしているファイル (たとえば、通常ファイル) では、 read() は、 fildes のファイルオフセットで指定されているファイルの位置から読み取りを開始します。 ファイルオフセットは、実際に読み取られるバイト数で増加します。

シークをサポートしていないファイル (たとえば、ターミナル) は、常に現在の位置から読み込みます。このようなファイルの場合、ファイルオフセットの値は未定です。

現在のファイルの最後 (end-of-file) を過ぎると、データは転送されません。 開始位置がファイルの最後 (end-of-file) またはそれ以降である場合、０ が返ります。ファイルがデバイス特殊ファイルと呼ばれるファイルの場合、 read() 要求の結果はインプリメンテーションに依存します。

nbyte の値が {SSIZE_MAX} よりも大きい場合、 結果はインプリメンテーションに依存します。

空のパイプ (または FIFO) から読み込もうとした場合は、以下のような動作をします。

非ブロック読み取りをサポートしていて、現在利用可能なデータがないファイル (パイプまたは FIFO 以外の) を読み込もうとした場合は、以下のような動作をします。

レコードとファイルの強制ロッキングモード chmod(2) を参照) がセットされている通常のファイルからデータを読み取ろうとしたときに、読み取ろうとするファイルのセグメントが別のプロセスの write ロックによってブロックされていると、その動作は、ファイルステータス フラグ O_NDELAY および O_NONBLOCK によって次のようになります。

tty に関連付けられているファイルを読み込もうとしたとき、そこに入力されたデータがないと、以下のように動作します。

read() 関数はファイルに事前に書き込まれたデータを読み取ります。 通常のファイルの終了 (end-of-file) よりも前の部分が書き込まれていなかった場合、 read() は値 ０ を持つバイトを返します。たとえば、 lseek() を使用すると、ファイルの既存データの最後以降にファイルオフセットをセットできます。 後でデータがその位置に書き込まれた場合、以前のデータの最後と新たに書き込まれたデータとの間のギャップで読み取りを行なうと、そのギャップにデータが書き込まれるまで、値 ０ を持つバイトが返ります。

対象が通常のファイルの場合、 O_RSYNC|O_DSYNC ファイルステータス フラグがセットされていると、呼び出し元プロセスは、読み取ろうとするデータとそのデータの検索に必要なすべてのファイル属性がディスク上のそれらのイメージと同じになるまで、ブロックされます。 読み取ろうとするデータに対して保留されている書き込みがあれば、その書き込みは、呼び出し元プロセスに返る前に実行されます。 O_RSYNC|O_SYNC ファイルステータス フラグがセットされている場合の動作は、次の条件が付け加わること以外、 O_RSYNC|O_DSYNC がセットされている場合と同じです。 つまり、読み取り操作によって変更されたすべてのファイル属性 (アクセス時刻、修正時刻、およびステータス変更時刻を含む) がディスク上のそれらのイメージと同じでなければなりません。 ブロック型特殊ファイルの場合、 O_RSYNC|O_DSYNC または O_RSYNC|O_SYNC ステータスフラグがセットされていると、呼び出し元プロセスは、読み取ろうとするデータがディスク上のデータイメージになるまでブロックされます。 読み取ろうとするデータに対して保留されている書き込みがあれば、その書き込みは、呼び出し元プロセスに返る前に実行されます。

正常終了で、 nbyte が ０ よりも大きい場合、 read() は st_atime フィールドに更新のマークを付け、読み取ったバイト数を返します。 このバイト数は nbyte より大きいことは決してありません。 ファイルの残りのバイト数が nbyte より小さい場合、 read() 要求にシグナルの割り込みがあった場合、あるいは、ファイルがパイプ、FIFO、または特殊ファイルで、読み取りで直接利用できるバイト数が nbyte バイトよりも少ない場合、 返される値は nbyte より小さい値です。 たとえば、ターミナルに対応するファイルから read() で読み取った場合は、１ 行形式のデータを返します。

データを読み取る前にシグナルに割り込まれた場合、 read() は -1 を返し、 errno を [EINTR] にセットします。

データを正常に読み込んだ後にシグナルに割り込まれた場合、 read() は、読み込んだバイト数を返します。

STREAMS ファイルの read() は ３ つの異なるモード (バイトストリーム モード、メッセージ非放棄モード、メッセージ放棄モード) でデータを読み取ることができます。デフォルトはバイトストリーム モードです。これは I_SRDOPT ioctl() 要求を使用して変更でき、 I_GRDOPT ioctl() でテストできます。 バイトストリーム モードでは、 read() は、要求バイトと同じバイト数が転送されるか、取り出すデータがなくなるまで、 STREAM からデータを取り出します。バイトストリーム モードはメッセージの境界を無視します。

STREAMS メッセージ非放棄モードでは、 read() は、要求データが転送されるまで、またはメッセージ境界に達するまで、データを取り出します。 read() がメッセージ内のすべてのデータを取り出さなかった場合は、データは STREAM に残され、次の read() 呼び出しで取り出されます。 メッセージ放棄モードも、要求データと同じバイト数が転送されるまで、またはメッセージ境界に達するまでデータを取り出します。 ただし、 read() から戻った後メッセージ内に残っている読み取られなかったデータは放棄され、次の read()、 readv()、 または getmsg() 呼び出しでは利用できません。

read() がゼロバイトの STREAMS メッセージを処理する方法は、現在の読み取りモード設定で決定されます。 バイトストリーム モードでは、 read() は、 nbyte バイトを読み取るか、読み取るデータがなくなるか、または、ゼロバイトメッセージ ブロックに遭遇するまで、データを受け入れます。次に、 read() 関数は、読み込んだバイト数を返し、ゼロバイトメッセージを STREAM に再び格納して、次の read()、 readv()、 または getmsg() によって取り出せるようにします。 メッセージ非放棄モードまたはメッセージ放棄モードでは、ゼロバイトメッセージは ０ を返し、メッセージは STREAM から削除されます。 ゼロバイトメッセージが STREAM の最初のメッセージとして読み取られた場合は、読み取りモードに関係なく、メッセージは STREAM から削除され、０ が返ります。

STREAMS ファイルから read() で読み取ると、メッセージの優先順位帯域に関係なく、データを STREAM のヘッドの読み取り待ち行列の先頭のメッセージに返します。

デフォルトでは、 STREAM はコントロール ノーマルモードです。このモードでは、 STREAMS ファイルからの read() は、制御部分ではなくデータ部分を含むメッセージだけを処理できます。 制御部分を含むメッセージが STREAM のヘッドにあった場合、 read() は失敗します。このデフォルトのアクションは、 I_SRDOPT ioctl() コマンドを使用して、 STREAM を、コントロール データモードまたはコントロール放棄モードで格納すると変更できます。 コントロール データモードでは、 read() は、制御部分をデータに変換し、同じメッセージ内に元からあるデータ部分を渡す前に、それをアプリケーションに渡します。コントロール放棄モードでは、 read() はメッセージ制御部分を切り捨てますが、メッセージ内のデータ部分をプロセスに返します。

さらに、 呼び出し前に、 STREAM のヘッドが非同時性のエラーを処理している場合は、 read() と readv() は失敗します。 この場合、 errno の値は read() または readv() の結果を反映しませんが、以前のエラーは反映します。 STREAM の読み取り中にハングアップが発生した場合、 STREAM のヘッドの読み取り待ち行列が空になるまで、 read() は、 通常の作業を続け、その後、０ を返します。

readv() 関数は read() と同等ですが、入力データを iov 配列 iov[0]、 iov[1]、 ...、 iov[iovcnt-1]) のメンバーが指定する iovcnt 個のバッファーに格納します。 iovcnt 引き数は、 {IOV_MAX} 未満の場合に有効です。

各 iovec エントリーは、データを格納するメモリーの領域の基底アドレスと大きさ (サイズ) を指定します。 readv() 関数は、次に進む前に常に領域を満たします。 iovec 構造体は、 /usr/include/sys/uio.h に定義されています。

正常終了の場合、 readv() はファイルの st_atime フィールドに更新のマークを付けます。

pread() 関数は、ファイルポインターを変更せずにファイル内の指定の位置から読み取る点を除き、 read() と同じアクションを実行します。 pread() の最初の ３ つの引き数は read() と同じであり、ファイル内の目的の位置を読み取るために ４ 番目の引き数 offset が追加されています。シーク不能なファイル上で pread() を実行しようとすると、エラーが発生します。

戻り値

正常終了すると、 read() は、実際に読み取ってバッファーに格納したバイト数を返します。 以下の場合は、この数が nbyte より少なくなります。

読み取り開始位置がファイルの末尾に達していた場合は、０ が返されます。 それ以外の場合は -1 が返され、エラーの種類を示す値が errno にセットされます。

正常終了すると、 pread()、 および readv() は、実際に読み取ったバイト数 (正整数) を返します。 失敗の場合、関数は -1 を返し、エラーの種類を表す値を errno にセットします。

エラー

read(), pread() および readv() 関数は次の場合に失敗します。

readv() 関数は次の場合に失敗します。

read(), pread() および readv() 関数は次の場合に失敗します。

readv() 関数は次の場合に失敗します。

以下の場合には、 pread() 関数は失敗し、ファイルポインターは変更されません。

例

プロセスは、次に示す read(2) の呼び出しで、ファイルから mybuf で指し示されるバッファーに BUFSIZ バイト読み取る前に、 ファイルを読み取り用にオープンしていると仮定します。

警告

ファイルのモードビットの設定の仕方によっては、 システムによってレコードロッキングが強制されることはありません lockf(2) を参照)。

特に、キャラクタ型特殊デバイスおよび raw ディスクについては、 read() の使用法に制約があります。 特定のデバイスについての詳細は、 セクション (7) のマニュアルページを参照してください。

sigvector(2) をサポートするシステムの場合、 システムを適正に使用するため、 signal(5) についてのすべての資料を確認してください。 sigvector() はこのページに記述されている動作に影響を与えることがあります。

一般に、ディレクトリの内容を調べるのに read() を使うのは避け、ライブラリルーチン readdir() を使ってください directory(3C) を参照)。

制約

著者

read() は HP、AT&T、カリフォルニア大学バークレイ校で開発されました。

参照

fcntl(2), ioctl(2), lseek(2), open(2), pipe(2), creat(2), dup(2), lockf(2), select(2), ustat(2), directory(3C), tty(7), <stropts.h>, <sys/uio.h>, <unistd.h>, 『XBD 仕様書』の第 ９ 章「一般的なターミナルインタフェース」

標準準拠

read(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4