setbuf - ライブラリコールの説明 - Linux コマンド集 一覧表

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

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

バッファリングには unbuffered, block buffered, line buffered の3つのタイプが ある。出力ストリームのタイプが unbuffered の場合、データを書き込むとすぐに出 力先ファイルに書き込まれるかターミナルに表示される。block buffered の場合、文 字の読み書きはブロック単位でいっぺんに行われる。line buffered の場合、新しい 行が出力されるか、ターミナルデバイスに接続しているストリーム (通常、stdin) か ら新しい行が入力されるまで文字がたくわえられる。ブロックを強制的に出力するに は   fflush (3) 関数を使う。 ( fclose (3)を参照のこと) 通常、ファイルはすべて block buffered である。ファイルに対して 初めて入出力処理を行うと   malloc (3) が呼び出されバッファが獲得される。もし ストリームが (通常、 stdout がそうであるように) ターミナルを参照する場合には、ファイルは line buffered と なる。標準エラー出力 stderr はデフォルトでは常に unbuffered である。

setvbuf ()関数は、オープンしている任意のストリームに対してバッファを変更できる。 パラメータ mode は、次の 3 つのマクロのうちいずれかである:

_IONBF

unbuffered

_IOLBF

line buffered

_IOFBF

fully buffered

unbuffered のファイルを除き、 buf 引数は size バイト以上の大きさのバッファを指していなければならない。このバッファは現在の バッファの代わりに用いられる。もし、引数 buf が NULL ならば、モードだけが変更される。 新しいバッファは次に読み書きした際に割り当てられる。 setvbuf ()関数は、ストリームをオープンした後、 そのストリームに対して何らかの操作をする前にのみ使用できる。

他の 3 つの関数は setvbuf ()の呼び出しに単純に置き換えることができる。 setbuf ()関数は、

setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
と全く同等だし、 setbuffer ()関数は、バッファサイズがデフォルト値 BUFSIZ ではなく引数で与えられる点以外は同じである。 setlinebuf ()関数は

setvbuf(stream, (char *)NULL, _IOLBF, 0);
と同じである。

setvbuf ()関数は、成功した場合 0 を返す。 失敗した場合は任意の値を返すことがあり得るが、 mode が不正な場合またはリクエストが条件を満たさない場合は、0 以外を返す。 setvbuf ()関数が失敗した場合は errno を設定することもある。 その他の関数の返り値は void である。

setbuf ()関数および setvbuf ()関数は C89 と C99 に準拠している。

setbuffer ()関数および setlinebuf ()関数は 4.2BSD より前の BSD とは互換性がない。また Linux でも(古いバージョン では)利用できないかもしれない。4.2BSD および 4.3BSD のシステムでは setbuf ()は必ず追加のバッファーのサイズを使用するので、これも使うべきでない。

stream を閉じる時 (プログラムを終了する際にもこれは起きる) には、 buf と その指し示す空間とが存在していることを保証しなければならない。

例えば、次のような使い方は許されない:

#include <stdio.h>
int main()
{
    char buf[BUFSIZ];
    setbuf(stdin, buf);
    printf("Hello, world!\n");
    return 0;
}

  fclose (3),   fflush (3),   fopen (3),   fread (3),   malloc (3),   printf (3),   puts (3)