名前

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);

glibc 向けの機能検査マクロの要件 ( feature_test_macros(7) 参照):

setbuffer(), setlinebuf(): _BSD_SOURCE

説明

バッファリングには 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 つのマクロのうちいずれかである:

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

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

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

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

setvbuf(stream, NULL, _IOLBF, 0);

返り値

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

準拠

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

バグ

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

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

#include <stdio.h>

int
main(void)
{
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)

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。