.\" Copyright (c) 1980, 1991 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	6.10 (Berkeley) 6/29/91
.\"
.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu
.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995,
.\"                   Thomas.Koenig@ciw.uni-karlsruhe.de
.\" Correction,  Sun, 11 Apr 1999 15:55:18,
.\"     Martin Vicente <martin@netadmin.dgac.fr>
.\" Correction,  2000-03-03, Andreas Jaeger <aj@suse.de>
.\" Added return value for setvbuf, aeb, 
.\"
.TH SETBUF 3  2001-06-09 "Linux" "Linux Programmer's Manual"
.SH NAME
setbuf, setbuffer, setlinebuf, setvbuf \- 流缓冲操作
.SH "SYNOPSIS 总览"
.na
.B #include <stdio.h>
.sp
.BI "void setbuf(FILE *" stream ", char *" buf );
.br
.BI "void setbuffer(FILE *" stream ", char *" buf ", size_t "  size );
.br
.BI "void setlinebuf(FILE *" stream );
.br
.BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode
.BI ", size_t " size );
.ad
.SH "DESCRIPTION 描述"
有三种类型的缓冲策略，它们是无缓冲，块缓冲和行缓冲。当输出流无缓冲时，信息在写的同时出现于目标文件或终端上；当是块缓冲时，字符被暂存，然后一起写入；当是行缓冲时，字符被暂存，直到要输出一个新行符，或者从任何与终端设备连接的流中 (典型的是 stdin) 读取输入时才输出。函数
.BR fflush (3)
可以用来强制提前输出。(参见
.BR fclose (3))
通常所有文件都是块缓冲的。当文件 I/O 操作在文件上发生时，将调用
.BR malloc (3)
，获得一个缓冲。如果流指向一个终端 (通常
.I stdout
都是这样)，那么它是行缓冲的。标准错误流
.I stderr
默认总是无缓冲的。
.PP
函数
.B setvbuf
可以用在任何打开的流上，改变它的缓冲。参数
.I mode
必须是下列三个宏之一：
.RS
.TP
.B _IONBF
无缓冲
.TP
.B _IOLBF
行缓冲
.TP
.B _IOFBF
完全缓冲
.RE
.PP
除非是无缓冲的文件，否则参数
.I buf
应当指向一个长度至少为
.I size
字节的缓冲；这个缓冲将取代当前的缓冲。如果参数
.I buf
是
.BR NULL
，只有这个模式会受到影响；下次 read 或 write 操作还将分配一个新的缓冲。函数
.B setvbuf
只能在打开一个流，还未对它进行任何其他操作之前使用。
.PP
其他三个函数调用是函数
.BR setvbuf
的别名，函数
.B setbuf
与使用下列语句完全等价：
.PP
.RS
setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
.RE
.PP
函数
.B setbuffer
与此相同，但是缓冲的长度由用户决定，而不是由默认值
.BR BUFSIZ
决定。函数
.B setlinebuf
与使用下列语句完全等价：
.PP
.RS
setvbuf(stream, (char *)NULL, _IOLBF, 0);
.RE
.SH "RETURN VALUE 返回值"
函数
.B setvbuf
成功执行时返回 0。它失败时可能返回任何值，但是当
It can return any value on failure, but returns nonzero when
.I mode
不正确，或者不能实现请求时，必须返回非零值。它在失败时可能设置
.I errno
。其他函数没有返回值。
.SH "CONFORMING TO 标准参考"
函数
.B setbuf
和
.B setvbuf
遵循 ANSI X3.159-1989 (``ANSI C'') 标准。
.SH BUGS
函数
.B setbuffer
和
.B setlinebuf
无法移植到 4.2BSD 之前的 BSD 版本，在 Linux 中仅在 libc 4.5.21 之后的系统中可用。在 4.2BSD 和 4.3BSD 系统中，
.B setbuf
总是使用非最优的缓冲大小，应当避免使用它。
.P
在
.I stream
被关闭时，必须确保
.I buf
和它指向的空间仍然存在。这通常发生在程序终止时。
.P
例如，下列调用是非法的：
.nf
.sp
#include <stdio.h>
int main()
{
    char buf[BUFSIZ];
    setbuf(stdin, buf);
    printf("Hello, world!\\n");
    return 0;
}
.fi
.sp
.SH "SEE ALSO 参见"
.BR fclose (3),
.BR fflush (3),
.BR fopen (3),
.BR fread (3),
.BR malloc (3),
.BR printf (3),
.BR puts (3)