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