1*0a6a1f1dSLionel Sambuc.\" $NetBSD: setbuf.3,v 1.14 2015/07/15 19:08:43 christos Exp $ 22fe8fb19SBen Gras.\" 32fe8fb19SBen Gras.\" Copyright (c) 1980, 1991, 1993 42fe8fb19SBen Gras.\" The Regents of the University of California. All rights reserved. 52fe8fb19SBen Gras.\" 62fe8fb19SBen Gras.\" This code is derived from software contributed to Berkeley by 72fe8fb19SBen Gras.\" the American National Standards Committee X3, on Information 82fe8fb19SBen Gras.\" Processing Systems. 92fe8fb19SBen Gras.\" 102fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 112fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 122fe8fb19SBen Gras.\" are met: 132fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 142fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 152fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 162fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 172fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 182fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors 192fe8fb19SBen Gras.\" may be used to endorse or promote products derived from this software 202fe8fb19SBen Gras.\" without specific prior written permission. 212fe8fb19SBen Gras.\" 222fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 232fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 242fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 252fe8fb19SBen Gras.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 262fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 272fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 282fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 292fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 302fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 312fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 322fe8fb19SBen Gras.\" SUCH DAMAGE. 332fe8fb19SBen Gras.\" 342fe8fb19SBen Gras.\" @(#)setbuf.3 8.1 (Berkeley) 6/4/93 352fe8fb19SBen Gras.\" 362fe8fb19SBen Gras.Dd June 4, 1993 372fe8fb19SBen Gras.Dt SETBUF 3 382fe8fb19SBen Gras.Os 392fe8fb19SBen Gras.Sh NAME 402fe8fb19SBen Gras.Nm setbuf , 412fe8fb19SBen Gras.Nm setbuffer , 422fe8fb19SBen Gras.Nm setlinebuf , 432fe8fb19SBen Gras.Nm setvbuf 442fe8fb19SBen Gras.Nd stream buffering operations 452fe8fb19SBen Gras.Sh LIBRARY 462fe8fb19SBen Gras.Lb libc 472fe8fb19SBen Gras.Sh SYNOPSIS 482fe8fb19SBen Gras.In stdio.h 492fe8fb19SBen Gras.Ft void 502fe8fb19SBen Gras.Fn setbuf "FILE * restrict stream" "char * restrict buf" 512fe8fb19SBen Gras.Ft void 522fe8fb19SBen Gras.Fn setbuffer "FILE *stream" "char *buf" "size_t size" 532fe8fb19SBen Gras.Ft int 542fe8fb19SBen Gras.Fn setlinebuf "FILE *stream" 552fe8fb19SBen Gras.Ft int 562fe8fb19SBen Gras.Fn setvbuf "FILE * restrict stream" "char * restrict buf" "int mode" "size_t size" 572fe8fb19SBen Gras.Sh DESCRIPTION 582fe8fb19SBen GrasThe three types of buffering available are unbuffered, block buffered, 592fe8fb19SBen Grasand line buffered. 602fe8fb19SBen GrasWhen an output stream is unbuffered, information appears on the 612fe8fb19SBen Grasdestination file or terminal as soon as written; 622fe8fb19SBen Graswhen it is block buffered many characters are saved up and written as a block; 632fe8fb19SBen Graswhen it is line buffered characters are saved up until a newline is 642fe8fb19SBen Grasoutput or input is read from any stream attached to a terminal device 652fe8fb19SBen Gras(typically stdin). 66*0a6a1f1dSLionel Sambuc.Pp 67*0a6a1f1dSLionel SambucThe default buffer settings can be overwritten per descriptor 68*0a6a1f1dSLionel Sambuc.Dv ( STDBUFn ) 69*0a6a1f1dSLionel Sambucwhere 70*0a6a1f1dSLionel Sambuc.Dv n 71*0a6a1f1dSLionel Sambucis the numeric value of the file descriptor represented by the stream, or 72*0a6a1f1dSLionel Sambucfor all descriptors 73*0a6a1f1dSLionel Sambuc.Dv ( STDBUF ) . 74*0a6a1f1dSLionel SambucThe environment variable value is a letter followed by an optional numeric 75*0a6a1f1dSLionel Sambucvalue indicating the size of the buffer. 76*0a6a1f1dSLionel SambucValid sizes range from 0B to 1MB. 77*0a6a1f1dSLionel SambucValid letters are: 78*0a6a1f1dSLionel Sambuc.Bl -tag -width X -indent 79*0a6a1f1dSLionel Sambuc.It Dv Li U 80*0a6a1f1dSLionel SambucUnbuffered. 81*0a6a1f1dSLionel Sambuc.It Dv Li L 82*0a6a1f1dSLionel SambucLine-buffered. 83*0a6a1f1dSLionel Sambuc.It Dv Li F 84*0a6a1f1dSLionel SambucFully-buffered. 85*0a6a1f1dSLionel Sambuc.El 86*0a6a1f1dSLionel Sambuc.Pp 872fe8fb19SBen GrasThe function 882fe8fb19SBen Gras.Xr fflush 3 892fe8fb19SBen Grasmay be used to force the block out early. 902fe8fb19SBen Gras(See 912fe8fb19SBen Gras.Xr fclose 3 . ) 922fe8fb19SBen Gras.Pp 932fe8fb19SBen GrasNormally all files are block buffered. 942fe8fb19SBen GrasWhen the first 952fe8fb19SBen Gras.Tn I/O 962fe8fb19SBen Grasoperation occurs on a file, 972fe8fb19SBen Gras.Xr malloc 3 982fe8fb19SBen Grasis called, 992fe8fb19SBen Grasand an optimally-sized buffer is obtained. 1002fe8fb19SBen GrasIf a stream refers to a terminal 1012fe8fb19SBen Gras(as 1022fe8fb19SBen Gras.Em stdout 1032fe8fb19SBen Grasnormally does) it is line buffered. 1042fe8fb19SBen GrasThe standard error stream 1052fe8fb19SBen Gras.Em stderr 1062fe8fb19SBen Grasis initially unbuffered. 1072fe8fb19SBen Gras.Pp 1082fe8fb19SBen GrasThe 1092fe8fb19SBen Gras.Fn setvbuf 1102fe8fb19SBen Grasfunction 1112fe8fb19SBen Grasmay be used to alter the buffering behavior of a stream. 1122fe8fb19SBen GrasThe 1132fe8fb19SBen Gras.Fa mode 1142fe8fb19SBen Grasparameter must be one of the following three macros: 1152fe8fb19SBen Gras.Bl -tag -width _IOFBF -offset indent 1162fe8fb19SBen Gras.It Dv _IONBF 1172fe8fb19SBen Grasunbuffered 1182fe8fb19SBen Gras.It Dv _IOLBF 1192fe8fb19SBen Grasline buffered 1202fe8fb19SBen Gras.It Dv _IOFBF 1212fe8fb19SBen Grasfully buffered 1222fe8fb19SBen Gras.El 1232fe8fb19SBen Gras.Pp 1242fe8fb19SBen GrasThe 1252fe8fb19SBen Gras.Fa size 1262fe8fb19SBen Grasparameter may be given as zero 1272fe8fb19SBen Grasto obtain deferred optimal-size buffer allocation as usual. 1282fe8fb19SBen GrasIf it is not zero, 1292fe8fb19SBen Grasthen except for unbuffered files, the 1302fe8fb19SBen Gras.Fa buf 1312fe8fb19SBen Grasargument should point to a buffer at least 1322fe8fb19SBen Gras.Fa size 1332fe8fb19SBen Grasbytes long; 1342fe8fb19SBen Grasthis buffer will be used instead of the current buffer. 1352fe8fb19SBen Gras(If the 1362fe8fb19SBen Gras.Fa size 1372fe8fb19SBen Grasargument 1382fe8fb19SBen Grasis not zero but 1392fe8fb19SBen Gras.Fa buf 1402fe8fb19SBen Grasis 1412fe8fb19SBen Gras.Dv NULL , 1422fe8fb19SBen Grasa buffer of the given size will be allocated immediately, 1432fe8fb19SBen Grasand released on close. 1442fe8fb19SBen GrasThis is an extension to ANSI C; 1452fe8fb19SBen Grasportable code should use a size of 0 with any 1462fe8fb19SBen Gras.Dv NULL 1472fe8fb19SBen Grasbuffer.) 1482fe8fb19SBen Gras.Pp 1492fe8fb19SBen GrasThe 1502fe8fb19SBen Gras.Fn setvbuf 1512fe8fb19SBen Grasfunction may be used at any time, 1522fe8fb19SBen Grasbut may have peculiar side effects 1532fe8fb19SBen Gras(such as discarding input or flushing output) 1542fe8fb19SBen Grasif the stream is ``active''. 1552fe8fb19SBen GrasPortable applications should call it only once on any given stream, 1562fe8fb19SBen Grasand before any 1572fe8fb19SBen Gras.Tn I/O 1582fe8fb19SBen Grasis performed. 1592fe8fb19SBen Gras.Pp 1602fe8fb19SBen GrasThe other three calls are, in effect, simply aliases for calls to 1612fe8fb19SBen Gras.Fn setvbuf . 1622fe8fb19SBen GrasExcept for the lack of a return value, the 1632fe8fb19SBen Gras.Fn setbuf 1642fe8fb19SBen Grasfunction is exactly equivalent to the call 1652fe8fb19SBen Gras.Pp 1662fe8fb19SBen Gras.Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" 1672fe8fb19SBen Gras.Pp 1682fe8fb19SBen GrasThe 1692fe8fb19SBen Gras.Fn setbuffer 1702fe8fb19SBen Grasfunction 1712fe8fb19SBen Grasis the same, except that the size of the buffer is up to the caller, 1722fe8fb19SBen Grasrather than being determined by the default 1732fe8fb19SBen Gras.Dv BUFSIZ . 1742fe8fb19SBen GrasThe 1752fe8fb19SBen Gras.Fn setlinebuf 1762fe8fb19SBen Grasfunction 1772fe8fb19SBen Grasis exactly equivalent to the call: 1782fe8fb19SBen Gras.Pp 1792fe8fb19SBen Gras.Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" 1802fe8fb19SBen Gras.Sh RETURN VALUES 1812fe8fb19SBen GrasThe 1822fe8fb19SBen Gras.Fn setvbuf 1832fe8fb19SBen Grasfunction returns 0 on success, or 1842fe8fb19SBen Gras.Dv EOF 1852fe8fb19SBen Grasif the request cannot be honored 1862fe8fb19SBen Gras(note that the stream is still functional in this case). 1872fe8fb19SBen Gras.Pp 1882fe8fb19SBen GrasThe 1892fe8fb19SBen Gras.Fn setlinebuf 1902fe8fb19SBen Grasfunction returns what the equivalent 1912fe8fb19SBen Gras.Fn setvbuf 1922fe8fb19SBen Graswould have returned. 1932fe8fb19SBen Gras.Sh SEE ALSO 1942fe8fb19SBen Gras.Xr fclose 3 , 1952fe8fb19SBen Gras.Xr fopen 3 , 1962fe8fb19SBen Gras.Xr fread 3 , 1972fe8fb19SBen Gras.Xr malloc 3 , 1982fe8fb19SBen Gras.Xr printf 3 , 1992fe8fb19SBen Gras.Xr puts 3 2002fe8fb19SBen Gras.Sh STANDARDS 2012fe8fb19SBen GrasThe 2022fe8fb19SBen Gras.Fn setbuf 2032fe8fb19SBen Grasand 2042fe8fb19SBen Gras.Fn setvbuf 2052fe8fb19SBen Grasfunctions 2062fe8fb19SBen Grasconform to 2072fe8fb19SBen Gras.St -ansiC . 2082fe8fb19SBen Gras.Sh BUGS 2092fe8fb19SBen GrasThe 2102fe8fb19SBen Gras.Fn setbuffer 2112fe8fb19SBen Grasand 2122fe8fb19SBen Gras.Fn setlinebuf 2132fe8fb19SBen Grasfunctions are not portable to versions of 2142fe8fb19SBen Gras.Bx 2152fe8fb19SBen Grasbefore 2162fe8fb19SBen Gras.Bx 4.2 . 2172fe8fb19SBen GrasOn 2182fe8fb19SBen Gras.Bx 4.2 2192fe8fb19SBen Grasand 2202fe8fb19SBen Gras.Bx 4.3 2212fe8fb19SBen Grassystems, 2222fe8fb19SBen Gras.Fn setbuf 2232fe8fb19SBen Grasalways uses a suboptimal buffer size and should be avoided. 224