# マニュアルページ 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 も報告しません。