1.\" $NetBSD: setbuf.3,v 1.3 1995/02/02 01:15:54 jtc Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)setbuf.3 8.1 (Berkeley) 6/4/93 39.\" 40.Dd June 4, 1993 41.Dt SETBUF 3 42.Os BSD 4 43.Sh NAME 44.Nm setbuf , 45.Nm setbuffer , 46.Nm setlinebuf , 47.Nm setvbuf 48.Nd stream buffering operations 49.Sh SYNOPSIS 50.Fd #include <stdio.h> 51.Ft void 52.Fn setbuf "FILE *stream" "char *buf" 53.Ft void 54.Fn setbuffer "FILE *stream" "char *buf" "size_t size" 55.Ft int 56.Fn setlinebuf "FILE *stream" 57.Ft int 58.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" 59.Sh DESCRIPTION 60The three types of buffering available are unbuffered, block buffered, 61and line buffered. 62When an output stream is unbuffered, information appears on the 63destination file or terminal as soon as written; 64when it is block buffered many characters are saved up and written as a block; 65when it is line buffered characters are saved up until a newline is 66output or input is read from any stream attached to a terminal device 67(typically stdin). 68The function 69.Xr fflush 3 70may be used to force the block out early. 71(See 72.Xr fclose 3 . ) 73.Pp 74Normally all files are block buffered. 75When the first 76.Tn I/O 77operation occurs on a file, 78.Xr malloc 3 79is called, 80and an optimally-sized buffer is obtained. 81If a stream refers to a terminal 82(as 83.Em stdout 84normally does) it is line buffered. 85The standard error stream 86.Em stderr 87is always unbuffered. 88.Pp 89The 90.Fn setvbuf 91function 92may be used to alter the buffering behavior of a stream. 93The 94.Fa mode 95parameter must be one of the following three macros: 96.Bl -tag -width _IOFBF -offset indent 97.It Dv _IONBF 98unbuffered 99.It Dv _IOLBF 100line buffered 101.It Dv _IOFBF 102fully buffered 103.El 104.Pp 105The 106.Fa size 107parameter may be given as zero 108to obtain deferred optimal-size buffer allocation as usual. 109If it is not zero, 110then except for unbuffered files, the 111.Fa buf 112argument should point to a buffer at least 113.Fa size 114bytes long; 115this buffer will be used instead of the current buffer. 116(If the 117.Fa size 118argument 119is not zero but 120.Fa buf 121is 122.Dv NULL , 123a buffer of the given size will be allocated immediately, 124and released on close. 125This is an extension to ANSI C; 126portable code should use a size of 0 with any 127.Dv NULL 128buffer.) 129.Pp 130The 131.Fn setvbuf 132function may be used at any time, 133but may have peculiar side effects 134(such as discarding input or flushing output) 135if the stream is ``active''. 136Portable applications should call it only once on any given stream, 137and before any 138.Tn I/O 139is performed. 140.Pp 141The other three calls are, in effect, simply aliases for calls to 142.Fn setvbuf . 143Except for the lack of a return value, the 144.Fn setbuf 145function is exactly equivalent to the call 146.Pp 147.Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" 148.Pp 149The 150.Fn setbuffer 151function 152is the same, except that the size of the buffer is up to the caller, 153rather than being determined by the default 154.Dv BUFSIZ . 155The 156.Fn setlinebuf 157function 158is exactly equivalent to the call: 159.Pp 160.Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" 161.Sh RETURN VALUES 162The 163.Fn setvbuf 164function returns 0 on success, or 165.Dv EOF 166if the request cannot be honored 167(note that the stream is still functional in this case). 168.Pp 169The 170.Fn setlinebuf 171function returns what the equivalent 172.Fn setvbuf 173would have returned. 174.Sh SEE ALSO 175.Xr fopen 3 , 176.Xr fclose 3 , 177.Xr fread 3 , 178.Xr malloc 3 , 179.Xr puts 3 , 180.Xr printf 3 181.Sh STANDARDS 182The 183.Fn setbuf 184and 185.Fn setvbuf 186functions 187conform to 188.St -ansiC . 189.Sh BUGS 190The 191.Fn setbuffer 192and 193.Fn setlinebuf 194functions are not portable to versions of 195.Bx 196before 197.Bx 4.2 . 198On 199.Bx 4.2 200and 201.Bx 4.3 202systems, 203.Fn setbuf 204always uses a suboptimal buffer size and should be avoided. 205