setvbuf 的 man 手册翻译

SETBUF(3)                                   Linux Programmer's Manual                                   SETBUF(3)

NAME
       setbuf, setbuffer, setlinebuf, setvbuf - stream buffering operations/*流缓存操作*/

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

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       setbuffer(), setlinebuf(): _BSD_SOURCE

DESCRIPTION
       The  three types of buffering available are unbuffered, block buffered, and line buffered.  When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when  it
       is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream  attached  to  a  terminal  device
       (typically stdin).  The function fflush(3) may be used to force the block out early.  (See fclose(3).)
	   /*三种缓存类型分别为：无缓存、块缓存和行缓存。如果输出流是无缓存，那么信息一旦被写入就立马出现在目标文件或
	   终端上；当为块缓存时，大量的字符会被写入并保存成一个块；当行缓存时，字符会被保存起来直到遇到换行符或者输入
	   被任何附加到终端设备的流读取（通常是stdin），fflush 函数可以用来强制刷新  */

       Normally  all files are block buffered.  If a stream refers to a terminal (as stdout normally does), it is line buffered.  The standard error stream stderr is always unbuffered by default.
	   /*通常所有的文件都是块缓存。如果一个流引用了一个终端（向标准输出那样），那么它就是行缓存。标准错误流 stderr 
	   默认总是无缓存*/

       The setvbuf() function may be used on any open stream to change its buffer.  The mode argument must be one of the following three macros:

              _IONBF unbuffered

              _IOLBF line buffered

              _IOFBF fully buffered
			  
	   /*setvbuf 函数用于更改任何打开流的缓存区。mode 参数必须为下面三种宏之一：
	   _IONBF unbuffered（无缓存）
	   _IOLBF line buffered（行缓存）
	   _IOFBF fully buffered（全缓存）*/
	   
       Except for unbuffered files, the buf argument should point to a buffer at least size bytes long; this buffer will be used instead of the current buffer.  If the argument buf is NULL, only the mode is affected; a
       new buffer will be allocated on the next read or write operation.  The setvbuf() function may be used only after opening a stream and before any other operations have been performed on it.
	   /*除了无缓存文件，参数 buf 指向的数组 buffer 大小至至少要有一个 long 大小，这个 buffer 将会用于替代当前的
	   缓存区。如果 buf 参数为 NULL，那么只有 mode 参数会收到影响，一个新的缓存将会用于下一次的读写操作。setvbuf 
	   函数必须在一个流打开之后并且执行其他操作（如定位、读写等）之前被使用*/

       The other three calls are, in effect, simply aliases for calls to setvbuf().   The  setbuf()  function  is exactly equivalent to the call
	   /*其他三种调用函数只不过是 setvbuf 的特定参数下的形式。setbuf 函数相当于 setvbuf 函数做如下处理：*/

           setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);	// BUFSIZ = 8192 <sdtio.h>

       The  setbuffer() function is the same, except that the size of the buffer is up to the caller, rather than being determined by the default BUFSIZ.  The setlinebuf() function is exactly equivalent to the call:
	   /*setbuffer 函数和 setbuf 相同，只不过缓存区的大小是由用户设置的而非默认大小。setlinebuf 等价于下面形式：*/

           setvbuf(stream, NULL, _IOLBF, 0);

RETURN VALUE
       The function setvbuf() returns 0 on success.  It returns nonzero  on  failure  (mode  is  invalid  or  the request cannot be honored).  It may set errno on failure.
	   /*setvbuf 函数成功返回 0，失败返回非 0（一般为 mode 参数无效或者请求无法满足），错误值会被 errno 保存起来*/

       The other functions do not return a value.
	   /*其他函数无返回值*/

ATTRIBUTES
       For an explanation of the terms used in this section, see attributes(7).
		/*本节中一些术语解释
		
       ┌────────────────────────┬───────────────┬─────────┐
       │函数接口                 │ 属性          │ 值      │
       ├────────────────────────┼───────────────┼─────────┤
       │setbuf(), setbuffer(),  │ 线程安全       │ MT-Safe │
       │setlinebuf(), setvbuf() │               │         │
       └────────────────────────┴───────────────┴─────────┘*/
       ┌────────────────────────┬───────────────┬─────────┐
       │Interface               │ Attribute     │ Value   │
       ├────────────────────────┼───────────────┼─────────┤
       │setbuf(), setbuffer(),  │ Thread safety │ MT-Safe │
       │setlinebuf(), setvbuf() │               │         │
       └────────────────────────┴───────────────┴─────────┘
CONFORMING TO
       The setbuf() and setvbuf() functions conform to C89 and C99.

BUGS
       You must make sure that the space that buf points to still exists by the time stream is closed, which also happens at program termination.  For example, the following is invalid:
	   /*您必须确保 buf 指向的空间在流关闭的那一刻或者在程序终止时仍然存在。例如，下面的调用就是无效的*/

       #include <stdio.h>

       int main(void)
       {
           char buf[BUFSIZ];
           setbuf(stdin, buf);
           printf("Hello, world!\n");
           return 0;
       }
	/*本例说明的是一旦对应的流关闭时或者程序结束时，那么 setbuf 设置的 buf 也就不起作用了*/
SEE ALSO
       fclose(3), fflush(3), fopen(3), fread(3), malloc(3), printf(3), puts(3)

COLOPHON
       This page is part of release 4.04 of the Linux man-pages project.  A description of the project,  information   about   reporting   bugs,   and   the   latest   version   of   this   page,   can   be   found  at
       http://www.kernel.org/doc/man-pages/.

Linux                                               2015-05-07                                          SETBUF(3)