.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)setbuf.3 8.1 (Berkeley) 6/4/93
.\"
.\" $FreeBSD$
.Dd June 4, 1993
.Dt SETBUF 3
.Os BSD 4
.Sh 名称
.Nm setbuf ,
.Nm setbuffer ,
.Nm setlinebuf ,
.Nm setvbuf
.Nd ストリームバッファリング操作
.Sh 書式
.Fd #include <stdio.h>
.Ft void
.Fn setbuf "FILE *stream" "char *buf"
.Ft void
.Fn setbuffer "FILE *stream" "char *buf" "int size"
.Ft int
.Fn setlinebuf "FILE *stream"
.Ft int
.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size"
.Sh 解説
利用できる
3 タイプのバッファリングは、バッファリングなし、ブロックバッファリング、
および行バッファリングです。
出力ストリームがバッファリングなしの場合、情報は書き込まれると
ただちに宛先ファイルや端末に表示されます。出力ストリームが
ブロックバッファリングの場合、多数のキャラクタが蓄積されブロックとして
書き込まれます。出力ストリームが行バッファリングの場合、改行が
出力されるか、または端末デバイスにアタッチされた任意のストリーム
(
通常は
stdin
)
から入力が読み込まれるまで、キャラクタが蓄えられます。関数
.Xr fflush 3
を使用して早めのブロックアウトを強制することもできます
(
.Xr fclose 3
を参照
)
。
.Pp
通常、すべてのファイルがブロックバッファリングされます。
ファイルに対して最初の入出力操作が発生したとき、
.Xr malloc 3
が呼び出されて最適なサイズのバッファが獲得されます。
(
.Em stdout
が通常行うように
)
ストリームが端末を参照する場合は行バッファリングです。
標準エラーストリーム
.Em stderr
は必ずバッファリングなしです。
.Pp
.Fn setvbuf
関数は、ストリームのバッファリング動作を変更するのに使用できます。
.Fa mode
パラメータは次の
3 つのマクロのどれかでなくてはなりません。
.Bl -tag -width _IOFBF -offset indent
.It Dv _IONBF
バッファリングなし
.It Dv _IOLBF
行バッファリング
.It Dv _IOFBF
完全バッファリング
.El
.Pp
.Fa size
パラメータは、最適サイズのバッファをいつも通りに遅延割当てさせるために
0
に設定できます。このパラメータが
0
でない場合、バッファリングされていないファイルを除けば、
.Fa buf
引数は少なくとも長さが
.Fa size
バイトのバッファを指さなくてはなりません。
このバッファが現在のバッファの代わりに使用されます
(
.Fa size
引数がゼロでないものの、
.Fa buf
が
.Dv NULL
の場合、指定サイズのバッファがただちに割り振られ、
クローズ時に解放されます。これは
ANSI C
の拡張です。移植可能コードはサイズが
0
の
.Dv NULL
バッファを使用するはずです
)
。
.Pp
.Fn setvbuf
関数はいつでも使用できますが、ストリームが
``アクティブ''な場合に、
(
たとえば、入力の切り捨てや出力のフラッシュ等の
)
奇妙な副作用を持つことがあります。
移植可能なアプリケーションは、なんらかの入出力が実行される前に、
指定された任意のストリームに対してこの関数を一度だけ呼び出すべきです。
.Pp
他の
3
つの呼び出しは、実際には、
.Fn setvbuf
呼び出しの別名にすぎません。戻り値がないことを除いて、
.Fn setbuf
関数は以下の呼び出しと厳密に同じです。
.Pp
.Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);"
.Pp
.Fn setbuffer
関数は、バッファのサイズを呼び出し元が決め、デフォルトの
.Dv BUFSIZ
で決定されるのではないこと以外は同じです。
.Fn setlinebuf
関数は、次の呼び出しと厳密に同じです。
.Pp
.Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);"
.Sh 戻り値
.Fn setvbuf
関数は正常終了すると
0
を返します。要求が受け入れられない場合は
.Dv EOF
を返します
(
ストリームはこの場合でも依然として機能していることに
注意してください
)
。
.Pp
.Fn setlinebuf
関数は、同等の
.Fn setvbuf
呼び出しが返したはずの値を返します。
.Sh 関連項目
.Xr fclose 3 ,
.Xr fopen 3 ,
.Xr fread 3 ,
.Xr malloc 3 ,
.Xr printf 3 ,
.Xr puts 3
.Sh 規格
.Fn setbuf
関数と
.Fn setvbuf
関数は
.St -ansiC
に準拠しています。
.Sh バグ
.Fn setbuffer
関数と
.Fn setlinebuf
関数は、
.Bx 4.2
より前のバージョンの
.Bx
へ移植可能ではありません。
.Bx 4.2
システムと
.Bx 4.3
システムでは、
.Fn setbuf
は、最適ではないバッファサイズを必ず使用するので、
避けてください。
