]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" 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 | .\" | |
a9cd9cb7 | 8 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
9 | .\" Redistribution and use in source and binary forms, with or without |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" 3. All advertising materials mentioning features or use of this software | |
18 | .\" must display the following acknowledgement: | |
19 | .\" This product includes software developed by the University of | |
20 | .\" California, Berkeley and its contributors. | |
21 | .\" 4. Neither the name of the University nor the names of its contributors | |
22 | .\" may be used to endorse or promote products derived from this software | |
23 | .\" without specific prior written permission. | |
24 | .\" | |
25 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
26 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
27 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
28 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
29 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
30 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
31 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
32 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
33 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
34 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
35 | .\" SUCH DAMAGE. | |
8c9302dc | 36 | .\" %%%LICENSE_END |
fea681da MK |
37 | .\" |
38 | .\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 | |
39 | .\" | |
40 | .\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu | |
41 | .\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, | |
42 | .\" Thomas.Koenig@ciw.uni-karlsruhe.de | |
43 | .\" Correction, Sun, 11 Apr 1999 15:55:18, | |
44 | .\" Martin Vicente <martin@netadmin.dgac.fr> | |
45 | .\" Correction, 2000-03-03, Andreas Jaeger <aj@suse.de> | |
c13182ef | 46 | .\" Added return value for setvbuf, aeb, |
fea681da | 47 | .\" |
4b8c67d9 | 48 | .TH SETBUF 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
49 | .SH NAME |
50 | setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations | |
51 | .SH SYNOPSIS | |
a45ebabf | 52 | .nf |
fea681da | 53 | .B #include <stdio.h> |
f90f031e | 54 | .PP |
fea681da | 55 | .BI "void setbuf(FILE *" stream ", char *" buf ); |
f90f031e | 56 | .PP |
fea681da | 57 | .BI "void setbuffer(FILE *" stream ", char *" buf ", size_t " size ); |
f90f031e | 58 | .PP |
fea681da | 59 | .BI "void setlinebuf(FILE *" stream ); |
f90f031e | 60 | .PP |
a45ebabf MK |
61 | .BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode \ |
62 | ", size_t " size ); | |
63 | .fi | |
68e4db0a | 64 | .PP |
cc4615cc MK |
65 | .in -4n |
66 | Feature Test Macro Requirements for glibc (see | |
67 | .BR feature_test_macros (7)): | |
68 | .in | |
68e4db0a | 69 | .PP |
85234986 | 70 | .BR setbuffer (), |
cc4615cc | 71 | .BR setlinebuf (): |
51c612fb MK |
72 | Since glibc 2.19: |
73 | _DEFAULT_SOURCE | |
74 | Glibc 2.19 and earlier: | |
75 | _BSD_SOURCE | |
fea681da MK |
76 | .SH DESCRIPTION |
77 | The three types of buffering available are unbuffered, block buffered, and | |
c13182ef MK |
78 | line buffered. |
79 | When an output stream is unbuffered, information appears on | |
fea681da MK |
80 | the destination file or terminal as soon as written; when it is block |
81 | buffered many characters are saved up and written as a block; when it is | |
82 | line buffered characters are saved up until a newline is output or input is | |
9bef72b5 | 83 | read from any stream attached to a terminal device (typically \fIstdin\fP). |
c13182ef | 84 | The function |
fea681da MK |
85 | .BR fflush (3) |
86 | may be used to force the block out early. | |
c13182ef | 87 | (See |
fea681da | 88 | .BR fclose (3).) |
847e0d88 | 89 | .PP |
c13182ef | 90 | Normally all files are block buffered. |
c13182ef | 91 | If a stream refers to a terminal (as |
fea681da | 92 | .I stdout |
3fbfb6ef | 93 | normally does), it is line buffered. |
c13182ef | 94 | The standard error stream |
fea681da MK |
95 | .I stderr |
96 | is always unbuffered by default. | |
97 | .PP | |
98 | The | |
e511ffb6 | 99 | .BR setvbuf () |
fea681da MK |
100 | function may be used on any open stream to change its buffer. |
101 | The | |
102 | .I mode | |
c4bb193f | 103 | argument must be one of the following three macros: |
fea681da MK |
104 | .RS |
105 | .TP | |
106 | .B _IONBF | |
107 | unbuffered | |
108 | .TP | |
109 | .B _IOLBF | |
110 | line buffered | |
111 | .TP | |
112 | .B _IOFBF | |
113 | fully buffered | |
114 | .RE | |
115 | .PP | |
116 | Except for unbuffered files, the | |
117 | .I buf | |
118 | argument should point to a buffer at least | |
119 | .I size | |
c13182ef MK |
120 | bytes long; this buffer will be used instead of the current buffer. |
121 | If the argument | |
fea681da | 122 | .I buf |
8478ee02 | 123 | is NULL, |
fea681da | 124 | only the mode is affected; a new buffer will be allocated on the next read |
c13182ef MK |
125 | or write operation. |
126 | The | |
e511ffb6 | 127 | .BR setvbuf () |
33a0ccb2 | 128 | function may be used only after opening a stream and before any other |
fea681da MK |
129 | operations have been performed on it. |
130 | .PP | |
131 | The other three calls are, in effect, simply aliases for calls to | |
e511ffb6 | 132 | .BR setvbuf (). |
fea681da | 133 | The |
e511ffb6 | 134 | .BR setbuf () |
fea681da MK |
135 | function is exactly equivalent to the call |
136 | .PP | |
a6e2f128 | 137 | .in +4n |
fea681da | 138 | setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); |
a6e2f128 | 139 | .in |
fea681da MK |
140 | .PP |
141 | The | |
e511ffb6 | 142 | .BR setbuffer () |
fea681da MK |
143 | function is the same, except that the size of the buffer is up to the |
144 | caller, rather than being determined by the default | |
145 | .BR BUFSIZ . | |
146 | The | |
e511ffb6 | 147 | .BR setlinebuf () |
fea681da MK |
148 | function is exactly equivalent to the call: |
149 | .PP | |
a6e2f128 | 150 | .in +4n |
13f78d96 | 151 | setvbuf(stream, NULL, _IOLBF, 0); |
a6e2f128 | 152 | .in |
47297adb | 153 | .SH RETURN VALUE |
fea681da | 154 | The function |
e511ffb6 | 155 | .BR setvbuf () |
fea681da | 156 | returns 0 on success. |
c7094399 | 157 | It returns nonzero on failure |
5ab17ae7 MK |
158 | .RI ( mode |
159 | is invalid or the request cannot be honored). | |
c13182ef | 160 | It may set |
fea681da MK |
161 | .I errno |
162 | on failure. | |
847e0d88 | 163 | .PP |
5ab17ae7 | 164 | The other functions do not return a value. |
cd78e7f2 | 165 | .SH ATTRIBUTES |
eb965b5e PH |
166 | For an explanation of the terms used in this section, see |
167 | .BR attributes (7). | |
168 | .TS | |
169 | allbox; | |
170 | lbw23 lb lb | |
171 | l l l. | |
172 | Interface Attribute Value | |
173 | T{ | |
cd78e7f2 PH |
174 | .BR setbuf (), |
175 | .BR setbuffer (), | |
eb965b5e | 176 | .br |
cd78e7f2 | 177 | .BR setlinebuf (), |
cd78e7f2 | 178 | .BR setvbuf () |
eb965b5e PH |
179 | T} Thread safety MT-Safe |
180 | .TE | |
47297adb | 181 | .SH CONFORMING TO |
fea681da | 182 | The |
e511ffb6 | 183 | .BR setbuf () |
fea681da | 184 | and |
e511ffb6 | 185 | .BR setvbuf () |
68e1685c | 186 | functions conform to C89 and C99. |
fea681da | 187 | .SH BUGS |
eb0eae10 MK |
188 | .\" The |
189 | .\" .BR setbuffer () | |
190 | .\" and | |
191 | .\" .BR setlinebuf () | |
192 | .\" functions are not portable to versions of BSD before 4.2BSD, and | |
193 | .\" are available under Linux since libc 4.5.21. | |
194 | .\" On 4.2BSD and 4.3BSD systems, | |
195 | .\" .BR setbuf () | |
196 | .\" always uses a suboptimal buffer size and should be avoided. | |
11ac5b51 | 197 | .PP |
47b32c07 | 198 | You must make sure that the space that |
fea681da | 199 | .I buf |
47b32c07 | 200 | points to still exists by the time |
fea681da MK |
201 | .I stream |
202 | is closed, which also happens at program termination. | |
e935e108 | 203 | For example, the following is invalid: |
bdd915e2 MK |
204 | .PP |
205 | .EX | |
fea681da | 206 | #include <stdio.h> |
cf0a9ace | 207 | |
c13182ef | 208 | int |
cf0a9ace | 209 | main(void) |
fea681da MK |
210 | { |
211 | char buf[BUFSIZ]; | |
212 | setbuf(stdin, buf); | |
213 | printf("Hello, world!\\n"); | |
214 | return 0; | |
215 | } | |
b9c93deb | 216 | .EE |
47297adb | 217 | .SH SEE ALSO |
23ec905b | 218 | .BR stdbuf (1), |
fea681da MK |
219 | .BR fclose (3), |
220 | .BR fflush (3), | |
221 | .BR fopen (3), | |
222 | .BR fread (3), | |
223 | .BR malloc (3), | |
224 | .BR printf (3), | |
225 | .BR puts (3) |