マニュアルページ filebuf.3




名前

     filebuf - ファイル入出力用バッファクラス


形式

     #include <fstream.h>
     typedef long streampos;
     typedef long streamoff;
     class ios : virtual public unsafe_ios, public stream_MT {
     public:
             enum open_mode  {
                 in       = 0x01,  // 読み取り用にオープン
                 out      = 0x02,  // 書き込み用にオープン
                 ate      = 0x04,  // EOF までシークする
                 app      = 0x08,  // 追加モード: EOF 以降に追加
                 trunc    = 0x10,  // ファイルがあれば内容をクリア
                 nocreate = 0x20,  // ファイルがなければオープンを失敗させる
                 noreplace= 0x40   // ファイルがあればオープンを失敗させる
             };

             enum seek_dir { beg=0, cur=1, end=2 };

             // ios(3CC4)  ...
     };

     class filebuf : public streambuf {
     public:
             static const int openprot ; /* オープンに対するデフォルトの保護 */

                             filebuf() ;
                             ~filebuf() ;
                             filebuf(int f);
                             filebuf(int f, char*  p, int len) ;

             filebuf*        attach(int f) ;
             filebuf*        attach_unlocked(int);
             filebuf*        close();
             filebuf*        close_unlocked();
             int             detach() ;
             int             detach_unlocked();
             int             fd();
             int             is_open();
             int             is_open_unlocked();
             filebuf*        open(char *name, int omode, int prot=openprot) ;
             filebuf*        open_unlocked(const char*, int, int=filebuf::openprot);
             streampos       seekoff(streamoff, seek_dir, int omode) ;
             streampos       seekpos(streampos, int omode) ;
             streambuf*      setbuf(char* p, int len) ;
             int             sync() ;
     };


機能説明


     クラス filebuf は、文字の入力元または出力先としてファイル を
     使 用するように特殊化した streambuf です。文字はファイルから
     フェッチ (入力) され、ファイルによって消費され (ファイルに書
     き込まれ) ます。 filebuf がオープンファイルに接続 ( 
     ) されているとき、その filebuf は「オープンしている」とい い
     ます。一方、オープンファイルに接続されていないとき、 filebuf
     はクローズしていることになります。デフォルトでは、ファイルは
     保護モード filebuf::openprot (0666) でオープンされます。

     アタッチされているファイルがシーク可能なとき、 filebuf で は
     シーク操作が可能です。たとえば、通常のディスクファイルはシー
     ク可能ですが、端末はシークできません。アタッチされたファイル
     で 読み取り (書き込み) が可能な場合は、 filebuf でフェッチ (
     格納) が可能です。たとえば、標準入力では読み取りだけが 可 能
     で、 標 準 出 力 で は書き込みだけが可能です。C の標準入出力
     (stdio) とは異なり、同じ filebuf に対する入力操作と出力操 作
     の 間でシークは不要です。初期設定では 4 文字の書き戻しが可能
     です。

     streambuf の基本的な操作については  sbufprot(3CC4)  お よ び
     sbufpub(3CC4) で説明します。バッファ領域は、コンストラクタに
     与えられていない場合は自動的に割り当てられます。また、  set-
     buf  の呼び出しにより明示的に割り当てられます (通常、 setbuf
     の呼び出しが使用されます)。 filebuf をバッファリングしないよ
     うにすると、入力または出力の対象となる各文字に対してシステム
     コールが必要になります。入力ポインタと出力ポインタは概念的に
     は統合されていて、1 つのポインタとして動作します。

     filebuf は、UNIX のファイル記述子 (システムコールで渡され る
     小さな整数) を介してファイルを操作します。C の標準入出力は使
     用されません。提供されているファイル記述子については、妥当性
     検査を行わないので注意してください。

     いくつかのメンバー関数には 2 種類の定義が行われていま す。 1
     つ は unsafe (マルチスレッド環境で使用できない) バージョン (
     接尾辞 "_unlocked"を持つもの) で、複数のスレッドからのアクセ
     スに対して保護されていません。もう 1 つは、safe バージョン (
     デフォルト) で、mutex ロックを使用して複数のスレッドからの同
     時アクセスに対する保護を行います。

     filebuf() クローズした filebuf を作成します。

     filebuf(f)
          ファイル記述子 f にアタッチされた、オープン し て い る
          filebuf を作成します。

     filebuf(f, p, len)
          ファイル記述子 f にアタッチされた、オープン し て い る
          filebuf  を作成します。このファイル記述子はオープンして
          いると想定されます。初期のバッファ領域として p で始まる
          len  文 字の char 配列が使用されます。 p がゼロ、または
          len がゼロ以下のとき、 filebuf でバッファリングは行われ
          ません。

  メンバー関数
     filebuf* fb = fbuf.attach(f)
          fbuf がクローズしているとき、それをファイル記述子  f  (
          オー プンしていると想定) にアタッチし、 fbuf のアドレス
          を返します。 fbuf がすでにオープンしている場合は f を無
          視してゼロを返します。このメンバーは MT-safe です。

     filebuf *fb = fbuf.attach_unlocked(f)
          機能的には attach と同じですが、mutex ロックをいっさ い
          行わないため、MT-safe ではありません。

     int i = fbuf.detach()
          ファイル記述子に対応づけられているファイルへの待機中 の
          出 力 を フラッシュし、f からファイル記述子を切り離しま
          す。ファイル記述子を返します。アタッチされているファ イ
          ル記述子を close() によってクローズさせたくない場合は、
          close() の前にこの関数を呼び出してください。こ の メ ン
          バーは MT-safe です。

     int i = fbuf.detach_unlocked()
          機能的には detach と同じですが、mutex ロックをいっさ い
          行わないため、MT-safe ではありません。

     filebuf* fb = fbuf.close()
          保留中の出力をフラッシュし、ファイル記述子を無条件に ク
          ロー ズし、 fbuf をクローズします。戻り値は、エラー時に
          はゼロ、正常終了時には fbuf となります。このメンバー は
          MT-safe です。

     filebuf* fb = fbuf.close_unlocked()
          機能的には close と同じですが、mutex ロックをいっさい行
          わないため、MT-safe ではありません。

     int f = fbuf.fd()
          fbuf にアタッチされているファイル記述子を 返 し ま す。
          fbuf がオープンしていない場合は EOF を返します。

     int i = fbuf.is_open()
          fbuf がオープンしていれば (ファイル記述子に接続されてい
          れ ば) ゼロ以外の値、オープンしていない場合はゼロを返し
          ます。このメンバーは MT-safe です。

     int i = fbuf.is_open_unlocked()
          機能的には is_open と同じですが、mutex 相互排他ロックを
          いっさい行わないため、MT-safe ではありません。

     filebuf* fb = fbuf.open(name, mode, prot)
          fbuf がまだオープンしていない場合は、ファイル  name  を
          オー プ ン し、そのファイル記述子を fbuf に接続します。
          fbuf がオープンしている場合はエラーになります。ファイル
          が存在せず、かつ mode に ios::nocreate がセットされてい
          ない場合は、 prot で指定された保護ビット (デフォルト 値
          は 0666) でファイルを作成しようとします。 mode パラメタ
          は、 fstream(3CC4) で説明されている  ios::open_mode  の
          ビッ トの集まりです。これらのビットの論理和をとることが
          できます。この関数の戻り値は、正常終了時には fbuf の ア
          ド レス、何らかの異常があった場合はゼロになります。この
          メンバーは MT-safe です。

     filebuf* fb = fbuf.open_unlocked(name, mode, prot)
          機能的には open と同じですが、mutex 相互排他 ロッ ク を
          いっさい行わないので MT-safe ではありません。

     streampos pos2 = fbuf.seekoff(off, dir, mode)
          sbufpub(3CC4) で説明しているように、 off と  dir  に よ
          り、 入力ポインタと出力ポインタの一方または両方の位置を
          変更します。ただし、 mode パラメタは無視しま す。  fbuf
          が オープンしていない、アタッチされたファイルがシークを
          サポートしていない、シークをサポートしていても実行で き
          な い (ファイルの先頭または終端を越える) のいずれかの場
          合は異常終了します。 off は、ファイル内の dir によっ て
          指 定された位置からのオフセットです。戻り値は、正常終了
          時にはファイルの新しい位置、異常終了時には EOF になりま
          す。エラー時のファイルの位置は未定義です。

     streampos pos2 = fbuf.seekpos(pos, mode)
          fbuf.seekoff((streamoff)pos, ios::beg, mode) の呼び出し
          と等価です。 pos の値は、 seekoff または seekpos をあら
          かじめ呼び出して取得したもの、またはファイルの先頭を 表
          すゼロでなければなりません。 sbufpub(3CC4) も参照してく
          ださい。

     streambuf* sb = fbuf.setbuf(p, len)
          fbuf がオープンしていて、バッファ領域が割り当てられてい
          れ ば、 setbuf は何も変更を行わずにゼロを返します。それ
          以外の場合、 p が指す位置から始まる len 文字の 長 さ の
          char 配列を新しいバッファ領域として割り当てます。このと
          きの戻り値は fbuf のアドレスです。 p がゼロ、または len
          が ゼ ロ以下のとき、バッファ領域は割り当てられず、 fbuf
          でバッファリングは行われません。

     int i = fbuf.sync()
          入力 / 出力ポインタをアタッチされたファイルの実際の位置
          と 一致させるように試みます。これにより、まだ書き込まれ
          ていない文字をフラッシュしたり、すでに入力された文字 の
          上 に ファ イルをバックアップすることがあります。戻り値
          は、正常終了時にはゼロ、エラー時には EOF になります。
          文字のグループをファイルに書き込むときに、そのグルー プ
          を 構成するすべての文字が同時に書き込まれることを確実に
          するためには、割り当てるバッファ領域のサイズを最大の グ
          ルー プよりも大きくし、文字を格納する直前に sync を実行
          し、文字を格納した直後にもう一度 sync を実行してくだ さ
          い。


関連項目

     ios.intro(3CC4)、 fstream(3CC4)、 ios(3CC4)、
     sbufprot(3CC4)、 sbufpub(3CC4)、 stream_locker(3CC4)、
     stream_MT(3CC4)、『C++ ライブラリ・リファレンス』の第 3 章
     「従来型の iostream ライブラリ」および第 4 章「マルチスレッ
     ド環境での従来型の iostream ライブラリの使用」


警告

     通常、UNIX はシークの異常を報告し ま せ ん。 し た がっ て、
     filebuf も報告しません。