マニュアルページ sbufpub.3




名前

     sbufpub - ストリームバッファ基底クラスの公開バッファ


形式

     #include <iostream.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 streambuf : public stream_MT {
     public:

             int             in_avail();
             int             out_waiting();
             int             sbumpc();
             streambuf*      setbuf(char* ptr, int len);
             streampos       seekpos(streampos, int =ios::in|ios::out);
             streampos       seekoff(streamoff, seek_dir, int =ios::in|ios::out);
             int             sgetc();
             int             sgetn(char* ptr, int n);
             int             snextc();
             int             sputbackc(char);
             int             sputc(int c);
             int             sputn(const char* s, int n);
             void            stossc();
             virtual int     sync();

             int             in_avail_unlocked();
             int             out_waiting_unlocked();
             int             sbumpc_unlocked();
             int             sgetc_unlocked();
             int             sgetn_unlocked(char* ptr, int n);
             int             snextc_unlocked();
             int             sputbackc_unlocked(char);
             int             sputc_unlocked(int c);
             int             sputn_unlocked(const char* s, int n);
             void            stossc_unlocked();
     };


機能説明

     クラス streambuf はバッファクラスの基本的な機能を定義する も
     ので、このクラスから実際のバッファクラスを派生します。この公
     開インタフェースは、どのストリームクラスからでもそのバッファ
     関連の機能を実行するときに呼び出す必要がある関数を表します。
     streambuf 型のオブジェクトを作成する必要はありません。 む し
     ろ、 バッファオブジェクトのクラスの型は、 streambuf から派生
     したものでなければなりません。そのような派生に必要な限定公開
     イ ン タフェースについては、 sbufprot(3CC4) を参照してくださ
     い。


環境

     streambuf を MT-safe、すなわちマルチスレッド環境で正しく機能
     するようにするため、公開メンバー関数のそれぞれにロックが使用
     されています。パフォーマンスが重要になるシングルスレッドのア
     プリケーションのために、各関数にロックを使用しないバージョン
     が導入されました。ロックを使用しない関数は、オリジナルの関数
     名 に _unlocked という接尾辞が付いています。マルチスレッド環
     境で使用できない (MT-unsafe) であることを除き、ロックを使 用
     しない関数はそれぞれのオリジナルの関数と同じ機能を持ちます。
     詳細については、 MT-Safe libC Programmer's Guide を参照し て
     ください。

     クラス streambuf は、抽象バッファクラスをサポートします。 論
     理的には、文字の列と、格納またはフェッチ、またはその両方が行
     われる次の文字の場所を定義する 1 つまたは 2 つのポインタで構
     成されます。入力 (または出力) だけを目的にしたバッファクラス
     は、 get (または put ) ポインタの一方しか持っていません。 入
     出力の両方を目的にしたバッファクラスは両方のポインタを持って
     います。

     入力ポインタと出力ポインタは、列の中の各文字の間を指している
     と考えてください。入力バッファから次に取り出す文字は、入力ポ
     インタのすぐ後ろの文字です。出力ストリームに置かれている次の
     文字は、出力ポインタのすぐ後ろに格納されます。ポインタは、列
     の先頭では先頭の文字のすぐ前を指し、列の終端では最後の文字の
     すぐ後ろを指します。

     複数の異なるデバイスを使用する場合は、異なる方法を用いた複数
     の 種 類 のバッファ(確保領域ともいう) が存在することがありま
     す。 strstreambuf( ssbuf(3CC4) 参照) などの「キュー」型 バッ
     ファ は、 入 力 ポインタと出力ポインタを別々に持っています。
     strstreambuf はメモリー内の文字配列であり、格納 (出 力 )  と
     フェッ チ (入力) を任意の場所で行うことができます。 filebuf(
     filebuf(3CC4) 参照) などの「ファイル」型バッファは、入力操作
     と 出力操作の両方が行われる場合がありますが、実質上は 1 つの
     ポインタしか持っていません。次の入力または出力は、必ず現在の
     位 置で行われます (実際には 2 つのポインタが存在する場合もあ
     りますが、その場合でも 2 つのポインタは必ず同じ位置を指し ま
     す)。


     streambuf は文字配列をバッファとして使用し、空の入力バッファ
     にデータを入れたり、フル状態になった出力バッファをフラッシュ
     する場合は関数を呼び出します (詳細については  sbufprot(3CC4)
     を 参 照 )。通常、できるだけ効率を高めるために、格納、フェッ
     チ、ポインタ操作を行う関数はインラインにします。これらの関数
     について、以下に示します。

  入力関数
     int c = sbuf.sgetc()
          入力ポインタの後ろの文字を返します。入力ポインタが列 の
          終 端にある場合はを返します。その名前にかかわらず、入力
          ポインタは移動しません。

     int c = sbuf.snextc()
          入力ポインタを 1 つ進め (文字列の後ろに向かって 1 文 字
          分移動し)、ポインタの新しい位置の後ろの文字を返します。
          この関数の呼び出しの前または後に、入力ポインタが入力 文
          字 列 の 終端にあるとき (取得できる文字がないとき) は、
          EOF を返します。たとえば、入力バッファの内容が次のよ う
          な場合を考えます (`|' は入力ポインタの位置を示します)。
               abc|def
          ここで `|' は入力ポインタの位置を示しています。この関数
          は、入力ポインタを進め、`e' を返します。

     int c = sbuf.sbumpc()
          この関数はおそらく ``sgetc'' と名付けられるべきです。入
          力ポインタを 1 つ進め、新しいポインタ位置の前の文字を返
          します。入力ポインタが入力文字列の終端に位置している 場
          合は、 EOF を返します。

     sbuf.stossc()
          入力ポインタを 1 つ進め、何も返しません。 sgetc とこ の
          関 数を組み合わせれば、プットバックを行わないでスキャナ
          を実装できます。

     int i = sbuf.sgetn(ptr, len)
          入力ポインタの後ろの len 個の文字を取得し、 ptr が指 す
          char 型配列にコピーします。入力ポインタは、最後にフェッ
          チした文字の後ろに移動します。バッファ内に残されてい る
          文字数が len より少ないときは、残されている文字のすべて
          を取得します。戻り値はフェッチした文字数です。

     int c = sbuf.sputbackc(c)
          入力ポインタを 1 つ戻し (入力文字列の先頭に向かっ て  1
          文 字分移動し)、その新しい位置に c を置こうとします。使
          用しているバッファ機構によっては、ポインタを返した り、
          その位置に c を格納できない場合があります。したがって、
          入力ポインタの後ろにある文字と c とが同じでない場合、関
          数 が正しく機能したかどうかはっきりしません。使用してい
          るバッファ機構によっては、外部のデバイスと同期しなお す
          必要があります。プットバックに失敗した場合は、 EOF を返
          します。失敗の原因は、実際のバッファクラスの具体的な 内
          容によって異なりますが、その 1 つとして、すでにデバイス
          の先頭に位置していることがあります。

     int i = sbuf.in_avail()
          get 領域ですぐに利用できる文字の数を返します。 こ の 結
          果、外部のどのデバイスにアクセスしなくても、 i 個の文字
          をエラーなしでフェッチできることが確かになります。

  出力関数
     int i = sbuf.sputc(c)
          出力ポインタのすぐ後ろに c を格納し、ポインタを 1 文 字
          分  (文字列の終端方向に) 進めます。このとき、文字列はお
          そらく拡大されます。戻り値は、正常終了の場合は c  、 エ
          ラー時には EOF です。エラーの原因は、実際の派生バッファ
          クラスによって異なります。

     int i = sbuf.sputn(ptr, len)
          ptr が指している位置から、出力ポインタの後ろに 正 確 に
          len  個の文字を格納し、出力ポインタを最後の文字のすぐ後
          ろに進めます。戻り値は格納された文字の数で、 len と等し
          くなければなりません。格納された引数の数が len より少な
          いとき (戻り値が len より小さいとき) は、何らかのエラー
          が発生したことを示します。

     int i = sbuf.out_waiting()
          出力領域内の文字数、すなわち、最終的な宛先への出力が 保
          留されている文字の数を返します。

  位置決め関数
     streampos pos = sbuf.seekoff(off, dir, mode)
          mode でセットされているビットに従って、入力ポインタと出
          力 ポインタの一方または両方の位置を変更します。 mode で
          ios::in がセットされている場合は、入力ポインタを移動 し
          ま す。 mode で ios::out がセットされている場合は、出力
          ポインタを移動します。移動距離は符号つきの値 off によっ
          て指定します。 dirに指定可能な値は次の 3 種類です。
               ios::beg - ストリームの先頭から off バイト移 動 す
               る。
               ios::cur - 現在の位置から off バイト移動する。
               ios::end - ストリームの終端から off バイト移 動 す
               る。
          戻り値は新しい位置です。ポインタの位置を指定されたと お
          りに設定できなかった場合は、 EOF を返します。この関数で
          ポインタの位置を変更できないストリームもあるので注意 し
          てください。また、返された位置 ( streampos 型) は算術演
          算のサブジェクトとして使用しないで、「マジック」値と し
          て扱ってください。

     streampos newpos = sbuf.seekpos(pos, mode)
          mode でセットされているビットと pos で指定される位置 に
          従っ て、入力ポインタと出力ポインタの一方または両方の位
          置を変更します。 mode で ios::in がセットされている場合
          は、 入力ポインタを移動します。 mode で ios::out がセッ
          トされている場合は、出力ポインタを移動します。 pos の値
          は、  seekoff または seekpos の呼び出しによって返された
          ものでなければなりません。例外として、従来の意味を持 つ
          次の 2 つの値が用意されています。
               (streampos)0    - ストリームの先頭
               (streampos)EOF  - エラー指示子

     int i = sbuf.sync()
          streambuf をその実際の文字ストリームと同期させます。 詳
          細 は、 個々の派生バッファクラスに依存します。通常、put
          領域内のすべての文字をその最終的な宛先にフラッシュ し、
          可 能であれば、入力バッファ内のすべての文字をその入力元
          に戻します。これは通常、 sync の後には、 in_avail()  と
          out_waiting()  が と もにゼロを返すということを意味しま
          す。戻り値は、エラー発生時には EOF 、正常終了時にはゼロ
          となります。

  その他の関数
     streambuf* sb = sbuf.setbuf(ptr, len)
          この関数は論理的には限定公開インタフェースに属してい ま
          す が、オリジナルのストリーム・パッケージと互換性をとる
          ために公開インタフェースに置かれています。 ptr が指して
          いる位置から始まる len バイトの配列をバッファ領域として
          使用しようとします。 ptr の値がゼロ、または len の値 が
          ゼ ロ以下の場合は、バッファリングなし (unbuffered) 状態
          を要求します。派生クラスの詳細によっては、この要求を 受
          け 入れることが可能な場合があります。戻り値は、正常終了
          時には streambuf を指すポインタ、要求を受け入れることが
          できた場合はゼロになります。


関連項目

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