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