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