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