Commit | Line | Data |
---|---|---|
7860c229 KB |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
475a9472 | 3 | .\" |
043368e6 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
ae59e04c | 8 | .\" %sccs.include.redist.man% |
475a9472 | 9 | .\" |
7860c229 | 10 | .\" @(#)setbuf.3 8.1 (Berkeley) %G% |
ae59e04c CL |
11 | .\" |
12 | .Dd | |
13 | .Dt SETBUF 3 | |
14 | .Os BSD 4 | |
15 | .Sh NAME | |
16 | .Nm setbuf , | |
17 | .Nm setbuffer , | |
18 | .Nm setlinebuf , | |
19 | .Nm setvbuf | |
20 | .Nd stream buffering operations | |
21 | .Sh SYNOPSIS | |
22 | .Fd #include <stdio.h> | |
ce84a9a3 | 23 | .Ft void |
ae59e04c | 24 | .Fn setbuf "FILE *stream" "char *buf" |
ce84a9a3 | 25 | .Ft void |
ae59e04c CL |
26 | .Fn setbuffer "FILE *stream" "char *buf" "size_t size" |
27 | .Ft int | |
28 | .Fn setlinebuf "FILE *stream" | |
29 | .Ft int | |
30 | .Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" | |
31 | .Sh DESCRIPTION | |
2bec55ba KM |
32 | The three types of buffering available are unbuffered, block buffered, |
33 | and line buffered. | |
34 | When an output stream is unbuffered, information appears on the | |
35 | destination file or terminal as soon as written; | |
36 | when it is block buffered many characters are saved up and written as a block; | |
37 | when it is line buffered characters are saved up until a newline is | |
858d320c KB |
38 | output or input is read from any stream attached to a terminal device |
39 | (typically stdin). | |
ae59e04c CL |
40 | The function |
41 | .Xr fflush 3 | |
2bec55ba | 42 | may be used to force the block out early. |
ae59e04c CL |
43 | (See |
44 | .Xr fclose 3 . ) | |
ce84a9a3 | 45 | .Pp |
2bec55ba | 46 | Normally all files are block buffered. |
ae59e04c CL |
47 | When the first |
48 | .Tn I/O | |
49 | operation occurs on a file, | |
50 | .Xr malloc 3 | |
51 | is called, | |
ce84a9a3 | 52 | and an optimally-sized buffer is obtained. |
858d320c KB |
53 | If a stream refers to a terminal |
54 | (as | |
ae59e04c | 55 | .Em stdout |
858d320c | 56 | normally does) it is line buffered. |
ae59e04c CL |
57 | The standard error stream |
58 | .Em stderr | |
2bec55ba | 59 | is always unbuffered. |
ae59e04c CL |
60 | .Pp |
61 | The | |
62 | .Fn setvbuf | |
63 | function | |
ce84a9a3 | 64 | may be used to alter the buffering behavior of a stream. |
858d320c | 65 | The |
ae59e04c | 66 | .Fa mode |
858d320c | 67 | parameter must be one of the following three macros: |
ae59e04c CL |
68 | .Bl -tag -width _IOFBF -offset indent |
69 | .It Dv _IONBF | |
858d320c | 70 | unbuffered |
ae59e04c | 71 | .It Dv _IOLBF |
858d320c | 72 | line buffered |
ae59e04c | 73 | .It Dv _IOFBF |
858d320c | 74 | fully buffered |
ae59e04c CL |
75 | .El |
76 | .Pp | |
ce84a9a3 CT |
77 | The |
78 | .Fa size | |
79 | parameter may be given as zero | |
80 | to obtain deferred optimal-size buffer allocation as usual. | |
81 | If it is not zero, | |
82 | then except for unbuffered files, the | |
ae59e04c | 83 | .Fa buf |
858d320c | 84 | argument should point to a buffer at least |
ae59e04c | 85 | .Fa size |
858d320c KB |
86 | bytes long; |
87 | this buffer will be used instead of the current buffer. | |
ce84a9a3 CT |
88 | (If the |
89 | .Fa size | |
90 | argument | |
91 | is not zero but | |
ae59e04c | 92 | .Fa buf |
ce84a9a3 CT |
93 | is |
94 | .Dv NULL , | |
95 | a buffer of the given size will be allocated immediately, | |
96 | and released on close. | |
97 | This is an extension to ANSI C; | |
98 | portable code should use a size of 0 with any | |
99 | .Dv NULL | |
100 | buffer.) | |
101 | .Pp | |
ae59e04c CL |
102 | The |
103 | .Fn setvbuf | |
ce84a9a3 CT |
104 | function may be used at any time, |
105 | but may have peculiar side effects | |
106 | (such as discarding input or flushing output) | |
107 | if the stream is ``active''. | |
108 | Portable applications should call it only once on any given stream, | |
109 | and before any | |
110 | .Tn I/O | |
111 | is performed. | |
ae59e04c | 112 | .Pp |
ce84a9a3 | 113 | The other three calls are, in effect, simply aliases for calls to |
ae59e04c | 114 | .Fn setvbuf . |
ce84a9a3 | 115 | Except for the lack of a return value, the |
ae59e04c | 116 | .Fn setbuf |
ce84a9a3 | 117 | function is exactly equivalent to the call |
ae59e04c | 118 | .Pp |
ce84a9a3 | 119 | .Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);" |
ae59e04c CL |
120 | .Pp |
121 | The | |
122 | .Fn setbuffer | |
123 | function | |
858d320c | 124 | is the same, except that the size of the buffer is up to the caller, |
ae59e04c CL |
125 | rather than being determined by the default |
126 | .Dv BUFSIZ . | |
127 | The | |
128 | .Fn setlinebuf | |
129 | function | |
130 | is exactly equivalent to the call: | |
131 | .Pp | |
ce84a9a3 CT |
132 | .Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);" |
133 | .Sh RETURN VALUES | |
134 | The | |
135 | .Fn setvbuf | |
136 | function returns 0 on success, or | |
137 | .Dv EOF | |
138 | if the request cannot be honored | |
139 | (note that the stream is still functional in this case). | |
140 | .Pp | |
141 | The | |
142 | .Fn setlinebuf | |
143 | function returns what the equivalent | |
144 | .Fn setvbuf | |
145 | would have returned. | |
ae59e04c CL |
146 | .Sh SEE ALSO |
147 | .Xr fopen 3 , | |
148 | .Xr fclose 3 , | |
149 | .Xr fread 3 , | |
150 | .Xr malloc 3 , | |
151 | .Xr puts 3 , | |
152 | .Xr printf 3 | |
153 | .Sh STANDARDS | |
154 | The | |
155 | .Fn setbuf | |
858d320c | 156 | and |
ae59e04c CL |
157 | .Fn setvbuf |
158 | functions | |
159 | conform to | |
160 | .St -ansiC . | |
161 | .Sh BUGS | |
2bec55ba | 162 | The |
ae59e04c CL |
163 | .Fn setbuffer |
164 | and | |
165 | .Fn setlinebuf | |
166 | functions are not portable to versions of | |
167 | .Bx | |
168 | before | |
169 | .Bx 4.2 . | |
170 | On | |
171 | .Bx 4.2 | |
2bec55ba | 172 | and |
ae59e04c CL |
173 | .Bx 4.3 |
174 | systems, | |
175 | .Fn setbuf | |
3db3fcbb | 176 | always uses a suboptimal buffer size and should be avoided. |