SETBUF(3)

名称
setbuf, setbuffer, setlinebuf, setvbuf - ストリームバッファリング操作

ライブラリ
libc

書式
#include <stdio.h> void setbuf(FILE *stream, char *buf) void setbuffer(FILE *stream, char *buf, int size) int setlinebuf(FILE *stream) int setvbuf(FILE *stream, char *buf, int mode, size_t size)

解説
利用できる 3 タイプのバッファリングは、バッファリングなし、 ブロックバッファリング、および行バッファリングです。 出力ストリームがバッファリングなしの場合、情報は書き込まれると ただちに書き込み先ファイルや端末に表示されます。 出力ストリームがブロックバッファリングの場合、 多数のキャラクタが蓄積されブロックとして書き込まれます。 出力ストリームが行バッファリングの場合、改行が出力されるか、 または端末デバイスにアタッチされた任意のストリーム (通常は stdin) から入力が読み込まれるまで、キャラクタが蓄えられます。 関数 fflush(3) を使用して、早めにブロックの出力を強制することもできます ( fclose(3) を参照)。

通常、すべてのファイルはブロックバッファリングされます。 ファイルに対して最初の入出力操作が発生したとき、 malloc(3) が呼び出されて最適なサイズのバッファが獲得されます。 ( stdout が通常行うように) ストリームが端末を参照する場合は行バッファリングです。 標準エラーストリーム stderr は常にバッファリングなしです。

setvbuf() 関数は、ストリームのバッファリング動作を変更するのに使用できます。 mode パラメータは次の 3 つのマクロのどれかでなくてはなりません。

_IONBF
    バッファリングなし

_IOLBF
    行バッファリング

_IOFBF
    完全バッファリング

size パラメータは、最適サイズのバッファをいつも通りに遅延割当てさせるために 0 に設定できます。 このパラメータが 0 でない場合、バッファリングなしのファイルを除けば、 buf 引数は少なくとも長さが size バイトのバッファを指していなくてはなりません。 このバッファが現在のバッファの代わりに使用されます ( size 引数が 0 でないものの、 buf が NULL の場合、指定サイズのバッファがただちに割り振られ、 クローズ時に解放されます。 これは ANSI C の拡張です。 移植可能コードはサイズが 0 の NULL バッファを使用するはずです)。

setvbuf() 関数はいつでも使用できますが、ストリームが ``アクティブ''な場合に、 (たとえば、入力の切り捨てや出力のフラッシュ等の) 奇妙な副作用を持つことがあります。 移植可能なアプリケーションは、なんらかの入出力が実行される前に、 指定された任意のストリームに対してこの関数を一度だけ呼び出すべきです。

他の 3 つの呼び出しは、実際には、 setvbuf() 呼び出しの別名にすぎません。 戻り値がないことを除いて、 setbuf() 関数は以下の呼び出しと厳密に同じです。

    setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

setbuffer() 関数は、バッファのサイズを呼び出し元が決め、デフォルトの BUFSIZ で決定されるのではないこと以外は同じです。 setlinebuf() 関数は、次の呼び出しと厳密に同じです。

    setvbuf(stream, (char *)NULL, _IOLBF, 0);

戻り値
setvbuf() 関数は正常終了すると 0 を返します。 要求が受け入れられない場合は EOF を返します (ストリームはこの場合でも依然として機能していることに注意してください)。

setlinebuf() 関数は、同等の setvbuf() 呼び出しが返したはずの値を返します。

関連項目
fclose(3), fopen(3), fread(3), malloc(3), printf(3), puts(3)

規格
setbuf() 関数と setvbuf() 関数は isoC に適合しています。

バグ
setbuffer() 関数と setlinebuf() 関数は、 4.2BSD より前のバージョンの BSD へ移植可能ではありません。 4.2BSD システムと 4.3BSD システムでは、 setbuf() は、最適ではないバッファサイズを常に使用するので、避けてください。