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 | .\" | |
13595319 | 5 | .\" @(#)setbuf.3 6.3 (Berkeley) %G% |
475a9472 | 6 | .\" |
30d2d776 | 7 | .TH SETBUF 3S "" |
475a9472 KM |
8 | .UC 4 |
9 | .SH NAME | |
2bec55ba | 10 | setbuf, setbuffer, setlinebuf \- assign buffering to a stream |
475a9472 KM |
11 | .SH SYNOPSIS |
12 | .B #include <stdio.h> | |
13 | .PP | |
14 | .B setbuf(stream, buf) | |
15 | .br | |
16 | .SM | |
17 | .B FILE | |
18 | .B *stream; | |
19 | .br | |
20 | .B char *buf; | |
2bec55ba KM |
21 | .PP |
22 | .B setbuffer(stream, buf, size) | |
23 | .br | |
24 | .SM | |
25 | .B FILE | |
26 | .B *stream; | |
27 | .br | |
28 | .B char *buf; | |
29 | .br | |
30 | .B int size; | |
31 | .PP | |
32 | .B setlinebuf(stream) | |
33 | .br | |
34 | .SM | |
35 | .B FILE | |
36 | .B *stream; | |
475a9472 | 37 | .SH DESCRIPTION |
2bec55ba KM |
38 | The three types of buffering available are unbuffered, block buffered, |
39 | and line buffered. | |
40 | When an output stream is unbuffered, information appears on the | |
41 | destination file or terminal as soon as written; | |
42 | when it is block buffered many characters are saved up and written as a block; | |
43 | when it is line buffered characters are saved up until a newline is | |
44 | encountered or input is read from stdin. | |
45 | .I Fflush | |
46 | (see | |
47 | .IR fclose (3S)) | |
48 | may be used to force the block out early. | |
49 | Normally all files are block buffered. | |
50 | A buffer is obtained from | |
51 | .IR malloc (3) | |
52 | upon the first | |
53 | .I getc | |
54 | or | |
55 | .IR putc (3S) | |
56 | on the file. | |
57 | If the standard stream | |
58 | .B stdout | |
59 | refers to a terminal it is line buffered. | |
60 | The standard stream | |
61 | .B stderr | |
62 | is always unbuffered. | |
63 | .PP | |
475a9472 | 64 | .I Setbuf |
2bec55ba KM |
65 | is used after a stream has been opened but before it is read or written. |
66 | The character array | |
475a9472 | 67 | .I buf |
2bec55ba | 68 | is used instead of an automatically allocated buffer. If |
475a9472 KM |
69 | .I buf |
70 | is the constant pointer | |
71 | .SM | |
72 | .B NULL, | |
73 | input/output will be completely unbuffered. | |
475a9472 KM |
74 | A manifest constant |
75 | .SM | |
76 | .B BUFSIZ | |
77 | tells how big an array is needed: | |
78 | .IP | |
79 | .B char | |
80 | buf[BUFSIZ]; | |
81 | .PP | |
2bec55ba KM |
82 | .IR Setbuffer , |
83 | an alternate form of | |
84 | .IR setbuf , | |
85 | is used after a stream has been opened but before it is read or written. | |
86 | The character array | |
87 | .I buf | |
88 | whose size is determined by the | |
89 | .I size | |
90 | argument is used instead of an automatically allocated buffer. If | |
91 | .I buf | |
92 | is the constant pointer | |
93 | .SM | |
94 | .BR NULL , | |
95 | input/output will be completely unbuffered. | |
96 | .PP | |
97 | .I Setlinebuf | |
98 | is used to change | |
99 | .I stdout | |
475a9472 | 100 | or |
475a9472 | 101 | .I stderr |
2bec55ba KM |
102 | from block buffered or unbuffered to line buffered. |
103 | Unlike | |
104 | .I setbuf | |
105 | and | |
106 | .I setbuffer | |
107 | it can be used at any time that the file descriptor is active. | |
108 | .PP | |
109 | A file can be changed from unbuffered or line buffered to block buffered | |
110 | by using | |
111 | .I freopen | |
112 | (see | |
113 | .IR fopen (3S)). | |
114 | A file can be changed from block buffered or line buffered to unbuffered | |
115 | by using | |
116 | .I freopen | |
117 | followed by | |
118 | .I setbuf | |
119 | with a buffer argument of | |
120 | .SM | |
121 | .BR NULL . | |
475a9472 | 122 | .SH "SEE ALSO" |
2bec55ba KM |
123 | fopen(3S), |
124 | getc(3S), | |
125 | putc(3S), | |
126 | malloc(3), | |
127 | fclose(3S), | |
128 | puts(3S), | |
129 | printf(3S), | |
130 | fread(3S) | |
475a9472 | 131 | .SH BUGS |
2bec55ba KM |
132 | The |
133 | .I setbuffer | |
134 | and | |
135 | .I setlinebuf | |
3db3fcbb MK |
136 | functions are not portable to non-4.2BSD versions of UNIX. |
137 | On 4.2BSD and 4.3BSD systems, | |
138 | .I setbuf | |
139 | always uses a suboptimal buffer size and should be avoided. | |
140 | .I Setbuffer | |
141 | is not usually needed | |
142 | as the default file I/O buffer sizes are optimal. |