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