setvbuf

来自cppreference.com
< c | io
 
C
 
文件输入/输出
类型与对象
        
函数
文件访问
(C11)
(C11)  
(C95)
无格式输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)

有格式输入
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)  
 
在标头 <stdio.h> 定义 
int setvbuf( FILE *         stream, char *         buffer, 
             int mode, size_t size );
(C99 前) 
int setvbuf( FILE *restrict stream, char *restrict buffer, 
             int mode, size_t size );
(C99 起) 
#define _IOFBF     /* 未指明 */
#define _IOLBF     /* 未指明 */
#define _IONBF     /* 未指明 */

以 mode 所指示值更改给定文件流 stream 的缓冲模式。另外，

  • 若 buffer 为空指针，则重设内部缓冲区大小为 size 。
  • 若 buffer 不是空指针，则指示流使用始于 buffer 而大小为 size 的用户提供缓冲区。必须在 buffer 所指向的数组的生存期结束前（用 fclose ）关闭流。成功调用 setvbuf 后，数组内容不确定，而任何使用它的尝试是未定义行为。

参数

stream - 要设置缓冲的文件流
buffer - 指向要使用的流缓冲区的指针，或若仅更改大小和模式则为空指针
mode - 使用的缓冲模式。它能是下列值之一：
_IOFBF 全缓冲：当缓冲区为空时，从流读入数据。或者当缓冲区满时，向流写入数据。
_IOLBF 行缓冲：每次从流中读入一行数据或向流中写入一行数据。
_IONBF 无缓冲：直接从流中读入数据或直接向流中写入数据，缓冲设置无效。
size - 缓冲区的大小

返回值

成功时为 0 ，失败时为非零。

注意

此函数仅可在已将 stream 关联到打开的文件后，但要在任何其他操作（除了对 setbuf/setvbuf 的失败调用）前使用。

不是所有 size 字节都需要用于缓冲：实际缓冲区大小通常向下取整到 2 的倍数、页面大小的倍数等。

多数实现上，行缓冲仅对终端输入流可用。

一个常见错误是设置 stdin 或 stdout 的缓冲区为生存期在程序终止前结束的数组： 

int main(void) {
    char buf[BUFSIZ];
    setbuf(stdin, buf);
} // buf 的生存期结束，未定义行为

期待默认缓冲区大小 BUFSIZ 为实现上文件 I/O 的最高效缓冲区大小，但 POSIX fstat 经常提供更好的估计。

示例

在已知更好的大小时更改缓冲区大小的使用样例。（这个示例使用了一些 POSIX 函数，比如 fileno。另见 SO帖子：#1 和#2）

运行此代码
// 使得一些 POSIX 函数可见，诸如 `int fileno(FILE*)`:
#define _POSIX_SOURCE

#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>

int main(void)
{
    FILE* fp = fopen("/tmp/test.txt", "w+");
    if (fp == NULL)
    {
        perror("fopen");
        return EXIT_FAILURE;
    }

    struct stat stats;
    if (fstat(fileno(fp), &stats) == -1) // 仅限 POSIX
    {
        perror("fstat");
        return EXIT_FAILURE;
    }

    printf("BUFSIZ is %d, but optimal block size is %ld\n", BUFSIZ, stats.st_blksize);
    if (setvbuf(fp, NULL, _IOFBF, stats.st_blksize) != 0)
    {
        perror("setvbuf failed"); // POSIX 版本设置 errno
        return EXIT_FAILURE;
    }

    int ch;
    while((ch=fgetc(fp)) != EOF); // read entire file: use truss/strace to
                                  // observe the read(2) syscalls used
    while((ch=fgetc(fp)) != EOF); // 读整个文件：可用 truss/strace 观察
                                  // 所使用的 read(2) 系统调用

    fclose(fp);
    return EXIT_SUCCESS;
}

可能的输出： 

BUFSIZ is 8192, but optimal block size is 65536

引用

  • C17 标准（ISO/IEC 9899:2018）：
  • 7.21.5.6 The setvbuf function （第 225 页）
  • C11 标准（ISO/IEC 9899:2011）：
  • 7.21.5.6 The setvbuf function （第 308 页）
  • C99 标准（ISO/IEC 9899:1999）：
  • 7.19.5.6 The setvbuf function （第 273-274 页）
  • C89/C90 标准（ISO/IEC 9899:1990）：
  • 4.9.5.6 The setvbuf function

参阅

 为文件流设置缓冲区
(函数)
setvbuf 的 C++ 文档