]>
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 MK |
45 | .\" |
46 | .TH SETBUF 3 2001-06-09 "Linux" "Linux Programmer's Manual" | |
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 | |
62 | .SH DESCRIPTION | |
63 | The three types of buffering available are unbuffered, block buffered, and | |
c13182ef MK |
64 | line buffered. |
65 | When an output stream is unbuffered, information appears on | |
fea681da MK |
66 | the destination file or terminal as soon as written; when it is block |
67 | buffered many characters are saved up and written as a block; when it is | |
68 | line buffered characters are saved up until a newline is output or input is | |
c13182ef MK |
69 | read from any stream attached to a terminal device (typically stdin). |
70 | The function | |
fea681da MK |
71 | .BR fflush (3) |
72 | may be used to force the block out early. | |
c13182ef | 73 | (See |
fea681da | 74 | .BR fclose (3).) |
c13182ef MK |
75 | Normally all files are block buffered. |
76 | When the first I/O operation occurs on a file, | |
fea681da | 77 | .BR malloc (3) |
c13182ef MK |
78 | is called, and a buffer is obtained. |
79 | If a stream refers to a terminal (as | |
fea681da | 80 | .I stdout |
c13182ef MK |
81 | normally does) it is line buffered. |
82 | The standard error stream | |
fea681da MK |
83 | .I stderr |
84 | is always unbuffered by default. | |
85 | .PP | |
86 | The | |
e511ffb6 | 87 | .BR setvbuf () |
fea681da MK |
88 | function may be used on any open stream to change its buffer. |
89 | The | |
90 | .I mode | |
91 | parameter must be one of the following three macros: | |
92 | .RS | |
93 | .TP | |
94 | .B _IONBF | |
95 | unbuffered | |
96 | .TP | |
97 | .B _IOLBF | |
98 | line buffered | |
99 | .TP | |
100 | .B _IOFBF | |
101 | fully buffered | |
102 | .RE | |
103 | .PP | |
104 | Except for unbuffered files, the | |
105 | .I buf | |
106 | argument should point to a buffer at least | |
107 | .I size | |
c13182ef MK |
108 | bytes long; this buffer will be used instead of the current buffer. |
109 | If the argument | |
fea681da | 110 | .I buf |
8478ee02 | 111 | is NULL, |
fea681da | 112 | only the mode is affected; a new buffer will be allocated on the next read |
c13182ef MK |
113 | or write operation. |
114 | The | |
e511ffb6 | 115 | .BR setvbuf () |
fea681da MK |
116 | function may only be used after opening a stream and before any other |
117 | operations have been performed on it. | |
118 | .PP | |
119 | The other three calls are, in effect, simply aliases for calls to | |
e511ffb6 | 120 | .BR setvbuf (). |
fea681da | 121 | The |
e511ffb6 | 122 | .BR setbuf () |
fea681da MK |
123 | function is exactly equivalent to the call |
124 | .PP | |
125 | .RS | |
126 | setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); | |
127 | .RE | |
128 | .PP | |
129 | The | |
e511ffb6 | 130 | .BR setbuffer () |
fea681da MK |
131 | function is the same, except that the size of the buffer is up to the |
132 | caller, rather than being determined by the default | |
133 | .BR BUFSIZ . | |
134 | The | |
e511ffb6 | 135 | .BR setlinebuf () |
fea681da MK |
136 | function is exactly equivalent to the call: |
137 | .PP | |
138 | .RS | |
0c535394 | 139 | setvbuf(stream, (char *) NULL, _IOLBF, 0); |
fea681da MK |
140 | .RE |
141 | .SH "RETURN VALUE" | |
142 | The function | |
e511ffb6 | 143 | .BR setvbuf () |
fea681da | 144 | returns 0 on success. |
f59a3f19 | 145 | It can return any value on failure, but returns non-zero when |
fea681da | 146 | .I mode |
d9bfdb9c | 147 | is invalid or the request cannot be honored. |
c13182ef | 148 | It may set |
fea681da MK |
149 | .I errno |
150 | on failure. | |
151 | The other functions are void. | |
152 | .SH "CONFORMING TO" | |
153 | The | |
e511ffb6 | 154 | .BR setbuf () |
fea681da | 155 | and |
e511ffb6 | 156 | .BR setvbuf () |
68e1685c | 157 | functions conform to C89 and C99. |
fea681da MK |
158 | .SH BUGS |
159 | The | |
e511ffb6 | 160 | .BR setbuffer () |
fea681da | 161 | and |
e511ffb6 | 162 | .BR setlinebuf () |
fea681da | 163 | functions are not portable to versions of BSD before 4.2BSD, and |
c13182ef MK |
164 | are available under Linux since libc 4.5.21. |
165 | On 4.2BSD and 4.3BSD systems, | |
e511ffb6 | 166 | .BR setbuf () |
fea681da MK |
167 | always uses a suboptimal buffer size and should be avoided. |
168 | .P | |
169 | You must make sure that both | |
170 | .I buf | |
c13182ef | 171 | and the space it points to still exist by the time |
fea681da MK |
172 | .I stream |
173 | is closed, which also happens at program termination. | |
174 | .P | |
175 | For example, the following is illegal: | |
176 | .nf | |
177 | .sp | |
178 | #include <stdio.h> | |
cf0a9ace | 179 | |
c13182ef | 180 | int |
cf0a9ace | 181 | main(void) |
fea681da MK |
182 | { |
183 | char buf[BUFSIZ]; | |
184 | setbuf(stdin, buf); | |
185 | printf("Hello, world!\\n"); | |
186 | return 0; | |
187 | } | |
188 | .fi | |
fea681da MK |
189 | .SH "SEE ALSO" |
190 | .BR fclose (3), | |
191 | .BR fflush (3), | |
192 | .BR fopen (3), | |
193 | .BR fread (3), | |
194 | .BR malloc (3), | |
195 | .BR printf (3), | |
196 | .BR puts (3) |