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.11 (Berkeley) 12/04/92 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 void 24.Fn setbuf "FILE *stream" "char *buf" 25.Ft void 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 . ) 45.Pp 46Normally all files are block buffered. 47When the first 48.Tn I/O 49operation occurs on a file, 50.Xr malloc 3 51is called, 52and an optimally-sized buffer is obtained. 53If a stream refers to a terminal 54(as 55.Em stdout 56normally does) it is line buffered. 57The standard error stream 58.Em stderr 59is always unbuffered. 60.Pp 61The 62.Fn setvbuf 63function 64may be used to alter the buffering behavior of a stream. 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 77The 78.Fa size 79parameter may be given as zero 80to obtain deferred optimal-size buffer allocation as usual. 81If it is not zero, 82then except for unbuffered files, the 83.Fa buf 84argument should point to a buffer at least 85.Fa size 86bytes long; 87this buffer will be used instead of the current buffer. 88(If the 89.Fa size 90argument 91is not zero but 92.Fa buf 93is 94.Dv NULL , 95a buffer of the given size will be allocated immediately, 96and released on close. 97This is an extension to ANSI C; 98portable code should use a size of 0 with any 99.Dv NULL 100buffer.) 101.Pp 102The 103.Fn setvbuf 104function may be used at any time, 105but may have peculiar side effects 106(such as discarding input or flushing output) 107if the stream is ``active''. 108Portable applications should call it only once on any given stream, 109and before any 110.Tn I/O 111is performed. 112.Pp 113The other three calls are, in effect, simply aliases for calls to 114.Fn setvbuf . 115Except for the lack of a return value, the 116.Fn setbuf 117function is exactly equivalent to the call 118.Pp 119.Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" 120.Pp 121The 122.Fn setbuffer 123function 124is the same, except that the size of the buffer is up to the caller, 125rather than being determined by the default 126.Dv BUFSIZ . 127The 128.Fn setlinebuf 129function 130is exactly equivalent to the call: 131.Pp 132.Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" 133.Sh RETURN VALUES 134The 135.Fn setvbuf 136function returns 0 on success, or 137.Dv EOF 138if the request cannot be honored 139(note that the stream is still functional in this case). 140.Pp 141The 142.Fn setlinebuf 143function returns what the equivalent 144.Fn setvbuf 145would have returned. 146.Sh SEE ALSO 147.Xr fopen 3 , 148.Xr fclose 3 , 149.Xr fread 3 , 150.Xr malloc 3 , 151.Xr puts 3 , 152.Xr printf 3 153.Sh STANDARDS 154The 155.Fn setbuf 156and 157.Fn setvbuf 158functions 159conform to 160.St -ansiC . 161.Sh BUGS 162The 163.Fn setbuffer 164and 165.Fn setlinebuf 166functions are not portable to versions of 167.Bx 168before 169.Bx 4.2 . 170On 171.Bx 4.2 172and 173.Bx 4.3 174systems, 175.Fn setbuf 176always uses a suboptimal buffer size and should be avoided. 177