setvbuf

int setvbuf( FILE* stream, char* buffer,
             int mode, size_t size );

int setvbuf( FILE* restrict stream, char* restrict buffer,
             int mode, size_t size );

#define _IOFBF     /* unspecified */
#define _IOLBF     /* unspecified */
#define _IONBF     /* unspecified */

Изменяет режим буферизации заданного файлового потока stream в соответствии с аргументом mode. Кроме того,

• Если buffer — нулевой указатель, изменяет размер внутреннего буфера на size.
• Если buffer не является нулевым указателем, указывает потоку использовать предоставленный пользователем буфер размером size, начинающийся с buffer. Поток необходимо закрыть (с помощью fclose) до окончания времени жизни символов в [buffer, buffer + size). Содержимое буфера после успешного вызова setvbuf не определено, и любая попытка его использования приводит к неопределённому поведению.

Параметры

Возвращаемое значение

0 при успехе или ненулевое значение при ошибке.

Примечания

Эту функцию можно использовать только после того, как stream был связан с открытым файлом, но до выполнения любых других операций (кроме неудачного вызова setbuf/setvbuf).

Для буферизации не обязательно будут использоваться все size байт: фактический размер буфера обычно округляется вниз до кратного 2, размера страницы и т. д.

Во многих реализациях построчная буферизация доступна только для потоков ввода с терминала.

Распространённая ошибка — установить для stdin или stdout буфер, представляющий собой массив, время жизни которого заканчивается до завершения программы:

int main(void)
{
    char buf[BUFSIZ];
    setbuf(stdin, buf);
} // lifetime of buf ends, undefined behavior

Предполагается, что размер буфера по умолчанию BUFSIZ является наиболее эффективным размером буфера для файлового ввода-вывода в данной реализации, однако POSIX fstat часто позволяет получить более точную оценку.

Пример

// Make some POSIX functions, such as ‘int fileno(FILE*)’, visible:
#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 only
    {
        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 version sets errno
        return EXIT_FAILURE;
    }

    int ch;
    while((ch=fgetc(fp)) != EOF); // read entire file: use truss/strace to
                                  // observe the read(2) syscalls used
    fclose(fp);
    return EXIT_SUCCESS;
}

BUFSIZ is 8192, but optimal block size is 65536

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.23.5.6 Функция setvbuf (с. 329–330)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.21.5.6 Функция setvbuf (с. 225)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.21.5.6 Функция setvbuf (с. 308)
• Стандарт C99 (ISO/IEC 9899:1999):
• 7.19.5.6 Функция setvbuf (с. 273–274)
• Стандарт C89/C90 (ISO/IEC 9899:1990):
• 4.9.5.6 Функция setvbuf

См. также