.\" 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.
.\" 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: src/lib/libc/stdio/setbuf.3,v 1.17 2007/01/09 00:28:07 imp Exp %
.\" $FreeBSDru: frdp/doc/ru_RU.KOI8-R/man/man3/setbuf.3,v 1.8 2007/10/30 19:33:07 ru Exp $
.\" $FreeBSD$
.\"
.Dd 4 июня 1993
.Dt SETBUF 3
.Os
.Sh НАЗВАНИЕ
.Nm setbuf ,
.Nm setbuffer ,
.Nm setlinebuf ,
.Nm setvbuf
.Nd управление буферизацией потока
.Sh БИБЛИОТЕКА
.Lb libc
.Sh СИНТАКСИС
.In stdio.h
.Ft void
.Fn setbuf "FILE * restrict stream" "char * restrict buf"
.Ft void
.Fn setbuffer "FILE *stream" "char *buf" "int size"
.Ft int
.Fn setlinebuf "FILE *stream"
.Ft int
.Fn setvbuf "FILE * restrict stream" "char * restrict buf" "int mode" "size_t size"
.Sh ОПИСАНИЕ
Имеются три типа буферизации: без буферизации, поблочная буферизация и
построчная буферизация.
При отсутствии буферизации выходного потока информация в конечном файле или
на терминале появляется сразу же, как только будет выполнена операция
записи; при поблочной буферизации в буфер сохраняется некоторое количество
символов и все они выдаются за раз как один блок; при построчной буферизации
символы сохраняются в буфере до тех пор, пока в выходном потоке не встретится
символ новой строки или ввод не будет читаться с любого потока, связанного
с терминальным устройством (как правило,
.Dv stdin ) .
Для принудительного вывода блока может быть использована функция
.Xr fflush 3 .
(Обратитесь к
.Xr fclose 3 . )
.Pp
Как правило, все файлы буферизуются поблочно.
Когда над файлом впервые выполняется операция
.Tn I/O ,
вызывается функция
.Xr malloc 3
и выделяется буфер оптимального размера.
Если поток связан с терминалом
(как это обычно имеет место с потоком
.Dv stdout ) ,
то он буферизуется построчно.
Стандартный поток диагностики
.Dv stderr
всегда не буферизован.
.Pp
Функция
.Fn setvbuf
может использоваться для изменения характера буферизации потока.
Аргумент
.Fa mode
должен быть одним из следующих трёх макросов:
.Bl -tag -width _IOFBF -offset indent
.It Dv _IONBF
без буферизации
.It Dv _IOLBF
построчная буферизация
.It Dv _IOFBF
полная буферизация
.El
.Pp
Аргумент
.Fa size
в обычном случае может принимать нулевое значение для выделения буфера
оптимального размера.
Если он ненулевой, то, исключая случай небуферизованных файлов, аргумент
.Fa buf
должен указывать на буфер размером по крайней мере
.Fa size
байт;
этот буфер будет использоваться вместо текущего.
Если
.Fa buf
не равен
.Dv NULL ,
освободить этот буфер с помощью
.Xr free 3
после закрытия потока должен будет сам вызывающий код.
(Если параметр
.Fa size
не равен нулю, а
.Fa buf
равен
.Dv NULL ,
то буфер указанного размера будет выделен немедленно
и при закрытии он будет освобождён.
Это является расширением к ANSI C;
в переносимом коде необходимо указывать размер буфера равным 0, если в качестве
буфера передаётся
.Dv NULL . )
.Pp
Функция
.Fn setvbuf
может быть использована в любом месте программы,
однако она может вызвать странные побочные эффекты
(такие, как уничтожение ввода или сброс вывода),
если поток ``активен''.
Переносимые приложения должны вызывать её только один раз для каждого
конкретного потока,
и делать это до выполнения каких-либо операций
.Tn I/O .
.Pp
Другие три вызова по существу являются просто алиасами для обращений к
.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 -isoC .
.Sh ПРОБЛЕМЫ
Функции
.Fn setbuffer
и
.Fn setlinebuf
не могут быть перенесены в
.Bx
вплоть до версии
.Bx 4.2 .
В системах
.Bx 4.2
и
.Bx 4.3
функция
.Fn setbuf
всегда использует полуоптимальный размер и её использования нужно избегать.