Commit | Line | Data |
---|---|---|
475a9472 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
1382c0b2 | 5 | .\" @(#)setbuf.3 6.7 (Berkeley) %G% |
475a9472 | 6 | .\" |
858d320c | 7 | .TH SETBUF 3 |
475a9472 KM |
8 | .UC 4 |
9 | .SH NAME | |
858d320c | 10 | setbuf, setbuffer, setlinebuf, setvbuf \- assign buffering to a stream |
475a9472 | 11 | .SH SYNOPSIS |
858d320c KB |
12 | .nf |
13 | .ft B | |
14 | #include <stdio.h> | |
15 | ||
16 | int | |
17 | setbuf(FILE *stream, char *buf); | |
18 | ||
19 | int | |
20 | setbuffer(FILE *stream, char *buf, size_t size); | |
21 | ||
22 | int | |
23 | setlinebuf(FILE *stream); | |
24 | ||
25 | int | |
26 | setvbuf(FILE *stream, char *buf, int mode, size_t size); | |
27 | .ft R | |
28 | .fi | |
475a9472 | 29 | .SH DESCRIPTION |
2bec55ba KM |
30 | The three types of buffering available are unbuffered, block buffered, |
31 | and line buffered. | |
32 | When an output stream is unbuffered, information appears on the | |
33 | destination file or terminal as soon as written; | |
34 | when it is block buffered many characters are saved up and written as a block; | |
35 | when it is line buffered characters are saved up until a newline is | |
858d320c KB |
36 | output or input is read from any stream attached to a terminal device |
37 | (typically stdin). | |
2bec55ba KM |
38 | .I Fflush |
39 | (see | |
86198885 | 40 | .IR fclose (3)) |
2bec55ba KM |
41 | may be used to force the block out early. |
42 | Normally all files are block buffered. | |
43 | A buffer is obtained from | |
858d320c KB |
44 | .IR malloc (3) |
45 | upon the first read or write operation on the file. | |
46 | If a stream refers to a terminal | |
47 | (as | |
2bec55ba | 48 | .B stdout |
858d320c | 49 | normally does) it is line buffered. |
2bec55ba KM |
50 | The standard stream |
51 | .B stderr | |
52 | is always unbuffered. | |
53 | .PP | |
858d320c KB |
54 | .I Setvbuf |
55 | may be used at any time on any open stream | |
56 | to change its buffer. | |
57 | The | |
58 | .I mode | |
59 | parameter must be one of the following three macros: | |
60 | .RS | |
61 | .TP 8 | |
62 | .B _IONBF | |
63 | unbuffered | |
64 | .br | |
65 | .ns | |
66 | .TP 8 | |
67 | .B _IOLBF | |
68 | line buffered | |
69 | .br | |
70 | .ns | |
71 | .TP 8 | |
72 | .B _IOFBF | |
73 | fully buffered | |
74 | .RE | |
75 | .LP | |
76 | Except for unbuffered files, the | |
2bec55ba | 77 | .I buf |
858d320c | 78 | argument should point to a buffer at least |
2bec55ba | 79 | .I size |
858d320c KB |
80 | bytes long; |
81 | this buffer will be used instead of the current buffer. | |
82 | If | |
2bec55ba | 83 | .I buf |
858d320c KB |
84 | is NULL, |
85 | only the mode is affected; | |
86 | a new buffer will be allocated on the next read or write operation. | |
87 | .I Setvbuf | |
88 | may be used at any time, | |
89 | but can only change the mode of a stream | |
90 | when it is not ``active'': | |
91 | that is, before any I/O, | |
92 | or immediately after a call to | |
93 | .IR fflush . | |
2bec55ba | 94 | .PP |
858d320c KB |
95 | The other three calls are, in effect, simply aliases |
96 | for calls to | |
97 | .IR setvbuf . | |
98 | .I Setbuf | |
99 | is exactly equivalent to the call | |
100 | .sp | |
101 | .ti +0.5i | |
102 | setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); | |
103 | .sp | |
104 | .I Setbuffer | |
105 | is the same, except that the size of the buffer is up to the caller, | |
106 | rather than being determined by the manifest constant | |
2bec55ba | 107 | .SM |
858d320c KB |
108 | .BR BUFSIZ . |
109 | .I Setlinebuf | |
110 | is exactly equivalent to the call | |
111 | .sp | |
112 | .ti +0.5i | |
113 | setvbuf(stream, (char *)NULL, _IOLBF, 0); | |
475a9472 | 114 | .SH "SEE ALSO" |
858d320c KB |
115 | fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3) |
116 | .SH STANDARDS | |
117 | .I Setbuf | |
118 | and | |
119 | .I setvbuf | |
1382c0b2 | 120 | conform to ANSI X3.159-1989 (``ANSI C''). |
475a9472 | 121 | .SH BUGS |
2bec55ba KM |
122 | The |
123 | .I setbuffer | |
124 | and | |
125 | .I setlinebuf | |
1382c0b2 | 126 | functions are not portable to versions of BSD UNIX before 4.2BSD. |
3db3fcbb MK |
127 | On 4.2BSD and 4.3BSD systems, |
128 | .I setbuf | |
129 | always uses a suboptimal buffer size and should be avoided. |