1.\" Copyright (c) 1980, 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)setbuf.3 6.9 (Berkeley) 04/19/91 7.\" 8.Dd 9.Dt SETBUF 3 10.Os BSD 4 11.Sh NAME 12.Nm setbuf , 13.Nm setbuffer , 14.Nm setlinebuf , 15.Nm setvbuf 16.Nd stream buffering operations 17.Sh SYNOPSIS 18.Fd #include <stdio.h> 19.Ft int 20.Fn setbuf "FILE *stream" "char *buf" 21.Ft int 22.Fn setbuffer "FILE *stream" "char *buf" "size_t size" 23.Ft int 24.Fn setlinebuf "FILE *stream" 25.Ft int 26.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" 27.Sh DESCRIPTION 28The three types of buffering available are unbuffered, block buffered, 29and line buffered. 30When an output stream is unbuffered, information appears on the 31destination file or terminal as soon as written; 32when it is block buffered many characters are saved up and written as a block; 33when it is line buffered characters are saved up until a newline is 34output or input is read from any stream attached to a terminal device 35(typically stdin). 36The function 37.Xr fflush 3 38may be used to force the block out early. 39(See 40.Xr fclose 3 . ) 41Normally all files are block buffered. 42When the first 43.Tn I/O 44operation occurs on a file, 45.Xr malloc 3 46is called, 47and a buffer is obtained. 48If a stream refers to a terminal 49(as 50.Em stdout 51normally does) it is line buffered. 52The standard error stream 53.Em stderr 54is always unbuffered. 55.Pp 56The 57.Fn setvbuf 58function 59may be used at any time on any open stream 60to change its buffer. 61The 62.Fa mode 63parameter must be one of the following three macros: 64.Bl -tag -width _IOFBF -offset indent 65.It Dv _IONBF 66unbuffered 67.It Dv _IOLBF 68line buffered 69.It Dv _IOFBF 70fully buffered 71.El 72.Pp 73Except for unbuffered files, the 74.Fa buf 75argument should point to a buffer at least 76.Fa size 77bytes long; 78this buffer will be used instead of the current buffer. 79If the argument 80.Fa buf 81is NULL, 82only the mode is affected; 83a new buffer will be allocated on the next read or write operation. 84The 85.Fn setvbuf 86function 87may be used at any time, 88but can only change the mode of a stream 89when it is not ``active'': 90that is, before any 91.Tn I/O , 92or immediately after a call to 93.Xr fflush . 94.Pp 95The other three calls are, in effect, simply aliases 96for calls to 97.Fn setvbuf . 98The 99.Fn setbuf 100function 101is exactly equivalent to the call 102.Pp 103.Dl setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); 104.Pp 105The 106.Fn setbuffer 107function 108is the same, except that the size of the buffer is up to the caller, 109rather than being determined by the default 110.Dv BUFSIZ . 111The 112.Fn setlinebuf 113function 114is exactly equivalent to the call: 115.Pp 116.Dl setvbuf(stream, (char *)NULL, _IOLBF, 0); 117.Sh SEE ALSO 118.Xr fopen 3 , 119.Xr fclose 3 , 120.Xr fread 3 , 121.Xr malloc 3 , 122.Xr puts 3 , 123.Xr printf 3 124.Sh STANDARDS 125The 126.Fn setbuf 127and 128.Fn setvbuf 129functions 130conform to 131.St -ansiC . 132.Sh BUGS 133The 134.Fn setbuffer 135and 136.Fn setlinebuf 137functions are not portable to versions of 138.Bx 139before 140.Bx 4.2 . 141On 142.Bx 4.2 143and 144.Bx 4.3 145systems, 146.Fn setbuf 147always uses a suboptimal buffer size and should be avoided. 148