xref: /minix3/lib/libc/stdio/setbuf.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
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