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