]>
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 | .\" | |
47009d5e | 8 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
9 | .\" |
10 | .\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 | |
11 | .\" | |
12 | .\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu | |
13 | .\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, | |
14 | .\" Thomas.Koenig@ciw.uni-karlsruhe.de | |
15 | .\" Correction, Sun, 11 Apr 1999 15:55:18, | |
16 | .\" Martin Vicente <martin@netadmin.dgac.fr> | |
17 | .\" Correction, 2000-03-03, Andreas Jaeger <aj@suse.de> | |
c13182ef | 18 | .\" Added return value for setvbuf, aeb, |
fea681da | 19 | .\" |
45186a5d | 20 | .TH SETBUF 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
21 | .SH NAME |
22 | setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations | |
8fda2d65 AC |
23 | .SH LIBRARY |
24 | Standard C library | |
8fc3b2cf | 25 | .RI ( libc ", " \-lc ) |
fea681da | 26 | .SH SYNOPSIS |
a45ebabf | 27 | .nf |
fea681da | 28 | .B #include <stdio.h> |
f90f031e | 29 | .PP |
92bb261d AC |
30 | .BI "int setvbuf(FILE *restrict " stream ", char *restrict " buf , |
31 | .BI " int " mode ", size_t " size ); | |
f90f031e | 32 | .PP |
92bb261d | 33 | .BI "void setbuf(FILE *restrict " stream ", char *restrict " buf ); |
b4d9224a AC |
34 | .BI "void setbuffer(FILE *restrict " stream ", char *restrict " buf , |
35 | .BI " size_t " size ); | |
fea681da | 36 | .BI "void setlinebuf(FILE *" stream ); |
a45ebabf | 37 | .fi |
68e4db0a | 38 | .PP |
d39ad78f | 39 | .RS -4 |
cc4615cc MK |
40 | Feature Test Macro Requirements for glibc (see |
41 | .BR feature_test_macros (7)): | |
d39ad78f | 42 | .RE |
68e4db0a | 43 | .PP |
85234986 | 44 | .BR setbuffer (), |
cc4615cc | 45 | .BR setlinebuf (): |
9d281e06 | 46 | .nf |
51c612fb MK |
47 | Since glibc 2.19: |
48 | _DEFAULT_SOURCE | |
49 | Glibc 2.19 and earlier: | |
50 | _BSD_SOURCE | |
9d281e06 | 51 | .fi |
fea681da MK |
52 | .SH DESCRIPTION |
53 | The three types of buffering available are unbuffered, block buffered, and | |
c13182ef MK |
54 | line buffered. |
55 | When an output stream is unbuffered, information appears on | |
fea681da | 56 | the destination file or terminal as soon as written; when it is block |
c7c869e6 MK |
57 | buffered, many characters are saved up and written as a block; when it is |
58 | line buffered, characters are saved up until a newline is output or input is | |
9bef72b5 | 59 | read from any stream attached to a terminal device (typically \fIstdin\fP). |
c13182ef | 60 | The function |
fea681da MK |
61 | .BR fflush (3) |
62 | may be used to force the block out early. | |
c13182ef | 63 | (See |
fea681da | 64 | .BR fclose (3).) |
847e0d88 | 65 | .PP |
c13182ef | 66 | Normally all files are block buffered. |
c13182ef | 67 | If a stream refers to a terminal (as |
fea681da | 68 | .I stdout |
3fbfb6ef | 69 | normally does), it is line buffered. |
c13182ef | 70 | The standard error stream |
fea681da MK |
71 | .I stderr |
72 | is always unbuffered by default. | |
73 | .PP | |
74 | The | |
e511ffb6 | 75 | .BR setvbuf () |
fea681da MK |
76 | function may be used on any open stream to change its buffer. |
77 | The | |
78 | .I mode | |
c4bb193f | 79 | argument must be one of the following three macros: |
fea681da MK |
80 | .RS |
81 | .TP | |
82 | .B _IONBF | |
83 | unbuffered | |
84 | .TP | |
85 | .B _IOLBF | |
86 | line buffered | |
87 | .TP | |
88 | .B _IOFBF | |
89 | fully buffered | |
90 | .RE | |
91 | .PP | |
92 | Except for unbuffered files, the | |
93 | .I buf | |
94 | argument should point to a buffer at least | |
95 | .I size | |
c13182ef MK |
96 | bytes long; this buffer will be used instead of the current buffer. |
97 | If the argument | |
fea681da | 98 | .I buf |
8478ee02 | 99 | is NULL, |
fea681da | 100 | only the mode is affected; a new buffer will be allocated on the next read |
c13182ef MK |
101 | or write operation. |
102 | The | |
e511ffb6 | 103 | .BR setvbuf () |
33a0ccb2 | 104 | function may be used only after opening a stream and before any other |
fea681da MK |
105 | operations have been performed on it. |
106 | .PP | |
107 | The other three calls are, in effect, simply aliases for calls to | |
e511ffb6 | 108 | .BR setvbuf (). |
fea681da | 109 | The |
e511ffb6 | 110 | .BR setbuf () |
fea681da MK |
111 | function is exactly equivalent to the call |
112 | .PP | |
a6e2f128 | 113 | .in +4n |
fea681da | 114 | setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); |
a6e2f128 | 115 | .in |
fea681da MK |
116 | .PP |
117 | The | |
e511ffb6 | 118 | .BR setbuffer () |
fea681da MK |
119 | function is the same, except that the size of the buffer is up to the |
120 | caller, rather than being determined by the default | |
121 | .BR BUFSIZ . | |
122 | The | |
e511ffb6 | 123 | .BR setlinebuf () |
fea681da MK |
124 | function is exactly equivalent to the call: |
125 | .PP | |
a6e2f128 | 126 | .in +4n |
13f78d96 | 127 | setvbuf(stream, NULL, _IOLBF, 0); |
a6e2f128 | 128 | .in |
47297adb | 129 | .SH RETURN VALUE |
fea681da | 130 | The function |
e511ffb6 | 131 | .BR setvbuf () |
fea681da | 132 | returns 0 on success. |
c7094399 | 133 | It returns nonzero on failure |
5ab17ae7 MK |
134 | .RI ( mode |
135 | is invalid or the request cannot be honored). | |
c13182ef | 136 | It may set |
fea681da MK |
137 | .I errno |
138 | on failure. | |
847e0d88 | 139 | .PP |
5ab17ae7 | 140 | The other functions do not return a value. |
cd78e7f2 | 141 | .SH ATTRIBUTES |
eb965b5e PH |
142 | For an explanation of the terms used in this section, see |
143 | .BR attributes (7). | |
c466875e MK |
144 | .ad l |
145 | .nh | |
eb965b5e PH |
146 | .TS |
147 | allbox; | |
c466875e | 148 | lbx lb lb |
eb965b5e PH |
149 | l l l. |
150 | Interface Attribute Value | |
151 | T{ | |
cd78e7f2 PH |
152 | .BR setbuf (), |
153 | .BR setbuffer (), | |
154 | .BR setlinebuf (), | |
cd78e7f2 | 155 | .BR setvbuf () |
eb965b5e PH |
156 | T} Thread safety MT-Safe |
157 | .TE | |
c466875e MK |
158 | .hy |
159 | .ad | |
160 | .sp 1 | |
3113c7f3 | 161 | .SH STANDARDS |
fea681da | 162 | The |
e511ffb6 | 163 | .BR setbuf () |
fea681da | 164 | and |
e511ffb6 | 165 | .BR setvbuf () |
68e1685c | 166 | functions conform to C89 and C99. |
bdd65639 MK |
167 | .SH NOTES |
168 | POSIX notes | |
169 | .\" https://www.austingroupbugs.net/view.php?id=397#c799 | |
170 | .\" 0000397: setbuf and errno | |
171 | that the value of | |
172 | .I errno | |
173 | is unspecified after a call to | |
174 | .BR setbuf () | |
175 | and further notes that, since the value of | |
176 | .I errno | |
177 | is not required to be unchanged after a successful call to | |
178 | .BR setbuf (), | |
179 | applications should instead use | |
180 | .BR setvbuf () | |
181 | in order to detect errors. | |
fea681da | 182 | .SH BUGS |
eb0eae10 MK |
183 | .\" The |
184 | .\" .BR setbuffer () | |
185 | .\" and | |
186 | .\" .BR setlinebuf () | |
187 | .\" functions are not portable to versions of BSD before 4.2BSD, and | |
188 | .\" are available under Linux since libc 4.5.21. | |
189 | .\" On 4.2BSD and 4.3BSD systems, | |
190 | .\" .BR setbuf () | |
191 | .\" always uses a suboptimal buffer size and should be avoided. | |
7f740303 | 192 | .\".PP |
47b32c07 | 193 | You must make sure that the space that |
fea681da | 194 | .I buf |
47b32c07 | 195 | points to still exists by the time |
fea681da MK |
196 | .I stream |
197 | is closed, which also happens at program termination. | |
e935e108 | 198 | For example, the following is invalid: |
bdd915e2 MK |
199 | .PP |
200 | .EX | |
fea681da | 201 | #include <stdio.h> |
cf0a9ace | 202 | |
c13182ef | 203 | int |
cf0a9ace | 204 | main(void) |
fea681da MK |
205 | { |
206 | char buf[BUFSIZ]; | |
b46edd91 | 207 | setbuf(stdout, buf); |
d1a71985 | 208 | printf("Hello, world!\en"); |
fea681da MK |
209 | return 0; |
210 | } | |
b9c93deb | 211 | .EE |
47297adb | 212 | .SH SEE ALSO |
23ec905b | 213 | .BR stdbuf (1), |
fea681da MK |
214 | .BR fclose (3), |
215 | .BR fflush (3), | |
216 | .BR fopen (3), | |
217 | .BR fread (3), | |
218 | .BR malloc (3), | |
219 | .BR printf (3), | |
220 | .BR puts (3) |