]>
Commit | Line | Data |
---|---|---|
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 | |
71 | Three types of buffering are available: | |
72 | unbuffered, block buffered, and line buffered. | |
73 | When an output stream is unbuffered, information appears on the | |
74 | destination file or terminal as soon as written; | |
75 | when it is block buffered, | |
76 | many characters are saved up and written as a block; | |
77 | when it is line buffered, | |
78 | characters are saved up until a newline is output | |
79 | or input is read from any stream attached to a terminal device | |
80 | (typically | |
81 | .Dv stdin ) . | |
82 | The function | |
83 | .Xr fflush 3 | |
84 | may be used to force the block out early. | |
85 | (See | |
86 | .Xr fclose 3 . ) | |
87 | .Pp | |
88 | Normally, all files are block buffered. | |
89 | When the first | |
90 | .Tn I/O | |
91 | operation occurs on a file, | |
92 | .Xr malloc 3 | |
93 | is called and an optimally-sized buffer is obtained. | |
94 | If a stream refers to a terminal | |
95 | (as | |
96 | .Dv stdout | |
97 | normally does), it is line buffered. | |
98 | The standard error stream | |
99 | .Dv stderr | |
100 | is always unbuffered. | |
101 | .Pp | |
102 | The | |
103 | .Fn setvbuf | |
104 | function | |
105 | may be used to alter the buffering behavior of a stream. | |
106 | The | |
107 | .Fa type | |
108 | argument must be one of the following three macros: | |
109 | .Bl -tag -width _IOFBF -offset indent | |
110 | .It Dv _IONBF | |
111 | unbuffered | |
112 | .It Dv _IOLBF | |
113 | line buffered | |
114 | .It Dv _IOFBF | |
115 | fully buffered | |
116 | .El | |
117 | .Pp | |
118 | The | |
119 | .Fa size | |
120 | argument may be given as zero | |
121 | to obtain deferred optimal-size buffer allocation as usual. | |
122 | If it is not zero, | |
123 | then except for unbuffered files, the | |
124 | .Fa buf | |
125 | argument should point to a buffer at least | |
126 | .Fa size | |
127 | bytes long; | |
128 | this buffer will be used instead of the current buffer. | |
129 | If | |
130 | .Fa buf | |
1f2f436a A |
131 | is not |
132 | .Dv NULL , | |
133 | it is the caller's responsibility to | |
224c7076 A |
134 | .Xr free 3 |
135 | this buffer after closing the stream. | |
136 | (If the | |
137 | .Fa size | |
138 | argument | |
139 | is not zero but | |
140 | .Fa buf | |
141 | is | |
142 | .Dv NULL , | |
143 | a buffer of the given size will be allocated immediately, | |
144 | and released on close. | |
145 | This is an extension to ANSI C; | |
146 | portable code should use a size of 0 with any | |
147 | .Dv NULL | |
148 | buffer.) | |
149 | .Pp | |
150 | The | |
151 | .Fn setvbuf | |
152 | function may be used at any time, | |
153 | but may have peculiar side effects | |
154 | (such as discarding input or flushing output) | |
155 | if the stream is ``active''. | |
156 | Portable applications should call it only once on any given stream, | |
157 | and before any | |
158 | .Tn I/O | |
159 | is performed. | |
160 | .Pp | |
161 | The other three calls are, in effect, simply aliases for calls to | |
162 | .Fn setvbuf . | |
163 | Except for the lack of a return value, the | |
164 | .Fn setbuf | |
165 | function is exactly equivalent to the call | |
166 | .Pp | |
167 | .Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" | |
168 | .Pp | |
169 | The | |
170 | .Fn setbuffer | |
171 | function | |
172 | is the same, except that the size of the buffer is up to the caller, | |
173 | rather than being determined by the default | |
174 | .Dv BUFSIZ . | |
175 | The | |
176 | .Fn setlinebuf | |
177 | function | |
178 | is exactly equivalent to the call: | |
179 | .Pp | |
180 | .Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" | |
181 | .Sh RETURN VALUES | |
182 | The | |
183 | .Fn setvbuf | |
184 | function returns 0 on success, or | |
185 | .Dv EOF | |
186 | if the request cannot be honored | |
187 | (note that the stream is still functional in this case). | |
188 | .Pp | |
189 | The | |
190 | .Fn setlinebuf | |
191 | function returns what the equivalent | |
192 | .Fn setvbuf | |
193 | would 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 | |
202 | The | |
203 | .Fn setbuf | |
204 | and | |
205 | .Fn setvbuf | |
206 | functions | |
207 | conform to | |
208 | .St -isoC . | |
209 | .Sh BUGS | |
210 | The | |
211 | .Fn setbuffer | |
212 | and | |
213 | .Fn setlinebuf | |
214 | functions are not portable to versions of | |
215 | .Bx | |
216 | before | |
217 | .Bx 4.2 . | |
218 | On | |
219 | .Bx 4.2 | |
220 | and | |
221 | .Bx 4.3 | |
222 | systems, | |
223 | .Fn setbuf | |
224 | always uses a suboptimal buffer size and should be avoided. |