Debian Codegraph @

upstream/debian-unstable/man3/setbuf.3

raw
1 '\" t
2 .\" Copyright 1980-1991, Regents of the University of California.
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH setbuf 3 2025-09-21 "Linux man-pages 6.18"
8 .SH NAME
9 setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
17 .BR "int setvbuf(" "size_t size;"
18 .BI " FILE *restrict " stream ", char " buf "[restrict " size ],
19 .BI " int " mode ", size_t " size );
20 .P
21 .BI "void setbuf(FILE *restrict " stream ", char *restrict " buf );
22 .BR "void setbuffer(" "size_t size;"
23 .BI " FILE *restrict " stream ", char " buf "[restrict " size ],
24 .BI " size_t " size );
25 .BI "void setlinebuf(FILE *" stream );
26 .fi
27 .P
28 .RS -4
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
31 .RE
32 .P
33 .BR setbuffer (),
34 .BR setlinebuf ():
35 .nf
36 Since glibc 2.19:
37 _DEFAULT_SOURCE
38 glibc 2.19 and earlier:
39 _BSD_SOURCE
40 .fi
41 .SH DESCRIPTION
42 The three types of buffering available are
43 unbuffered,
44 block buffered,
45 and line buffered.
46 When an output stream is unbuffered,
47 information appears on the destination file or terminal
48 as soon as written;
49 when it is block buffered,
50 many characters are saved up and written as a block;
51 when it is line buffered,
52 characters are saved up
53 until a newline is output
54 or input is read from any stream attached to a terminal device
55 (typically
56 .IR stdin ).
57 The function
58 .BR fflush (3)
59 may be used to force the block out early.
60 (See
61 .BR fclose (3).)
62 .P
63 Normally,
64 all files are block buffered.
65 If a stream refers to a terminal
66 (as
67 .I stdout
68 normally does),
69 it is line buffered.
70 The standard error stream
71 .I stderr
72 is always unbuffered by default.
73 .P
74 The
75 .BR setvbuf ()
76 function may be used on any open stream to change its buffer.
77 The
78 .I mode
79 argument must be one of the following three macros:
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 .P
92 Except for unbuffered files,
93 the
94 .I buf
95 argument should point to a buffer at least
96 .I size
97 bytes long;
98 this buffer will be used instead of the current buffer.
99 If the argument
100 .I buf
101 is NULL,
102 only the mode is affected;
103 a new buffer will be allocated
104 on the next read or write operation.
105 The
106 .BR setvbuf ()
107 function may be used only after opening a stream
108 and before any other operations have been performed on it.
109 .P
110 The other three calls are,
111 in effect,
112 simply aliases for calls to
113 .BR setvbuf ().
114 The
115 .BR setbuf ()
116 function is exactly equivalent to the call
117 .P
118 .in +4n
119 setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
120 .in
121 .P
122 The
123 .BR setbuffer ()
124 function is the same,
125 except that the size of the buffer is up to the caller,
126 rather than being determined by the default
127 .BR BUFSIZ .
128 The
129 .BR setlinebuf ()
130 function is exactly equivalent to the call:
131 .P
132 .in +4n
133 setvbuf(stream, NULL, _IOLBF, 0);
134 .in
135 .SH RETURN VALUE
136 The function
137 .BR setvbuf ()
138 returns 0 on success.
139 It returns nonzero on failure
140 .RI ( mode
141 is invalid or the request cannot be honored).
142 It may set
143 .I errno
144 on failure.
145 .P
146 The other functions do not return a value.
147 .SH ATTRIBUTES
148 For an explanation of the terms used in this section, see
149 .BR attributes (7).
150 .TS
151 allbox;
152 lbx lb lb
153 l l l.
154 Interface Attribute Value
155 T{
156 .na
157 .nh
158 .BR setbuf (),
159 .BR setbuffer (),
160 .BR setlinebuf (),
161 .BR setvbuf ()
162 T} Thread safety MT-Safe
163 .TE
164 .SH STANDARDS
165 .TP
166 .BR setbuf ()
167 .TQ
168 .BR setvbuf ()
169 C11, POSIX.1-2008.
170 .SH HISTORY
171 .TP
172 .BR setbuf ()
173 .TQ
174 .BR setvbuf ()
175 C89, POSIX.1-2001.
176 .SH CAVEATS
177 POSIX notes
178 .\" https://www.austingroupbugs.net/view.php?id=397#c799
179 .\" 0000397: setbuf and errno
180 that the value of
181 .I errno
182 is unspecified after a call to
183 .BR setbuf ()
184 and further notes that, since the value of
185 .I errno
186 is not required to be unchanged after a successful call to
187 .BR setbuf (),
188 applications should instead use
189 .BR setvbuf ()
190 in order to detect errors.
191 .SH BUGS
192 .\" The
193 .\" .BR setbuffer ()
194 .\" and
195 .\" .BR setlinebuf ()
196 .\" functions are not portable to versions of BSD before 4.2BSD, and
197 .\" are available under Linux since libc 4.5.21.
198 .\" On 4.2BSD and 4.3BSD systems,
199 .\" .BR setbuf ()
200 .\" always uses a suboptimal buffer size and should be avoided.
201 .\".P
202 You must make sure that the space that
203 .I buf
204 points to still exists by the time
205 .I stream
206 is closed, which also happens at program termination.
207 For example, the following is invalid:
208 .P
209 .\" SRC BEGIN (setbuf.c)
210 .EX
211 #include <stdio.h>
212 \&
213 int
214 main(void)
215 {
216 char buf[BUFSIZ];
217 \&
218 setbuf(stdout, buf);
219 printf("Hello, world!\[rs]n");
220 return 0;
221 }
222 .EE
223 .\" SRC END
224 .SH SEE ALSO
225 .BR stdbuf (1),
226 .BR fclose (3),
227 .BR fflush (3),
228 .BR fopen (3),
229 .BR fread (3),
230 .BR malloc (3),
231 .BR printf (3),
232 .BR puts (3)