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