version 1, including all changes.
.
Rev |
Author |
# |
Line |
1 |
perry |
1 |
SETBUF |
|
|
2 |
!!!SETBUF |
|
|
3 |
NAME |
|
|
4 |
SYNOPSIS |
|
|
5 |
DESCRIPTION |
|
|
6 |
RETURN VALUE |
|
|
7 |
CONFORMING TO |
|
|
8 |
BUGS |
|
|
9 |
SEE ALSO |
|
|
10 |
---- |
|
|
11 |
!!NAME |
|
|
12 |
|
|
|
13 |
|
|
|
14 |
setbuf, setbuffer, setlinebuf, setvbuf - stream buffering operations |
|
|
15 |
!!SYNOPSIS |
|
|
16 |
|
|
|
17 |
|
|
|
18 |
__#include __ |
|
|
19 |
|
|
|
20 |
|
|
|
21 |
__void setbuf(FILE *__''stream''__, char |
|
|
22 |
*__''buf''__); |
|
|
23 |
void setbuffer(FILE *__''stream''__, char |
|
|
24 |
*__''buf''__, size_t__''size''__); |
|
|
25 |
void setlinebuf(FILE *__''stream''__); |
|
|
26 |
int setvbuf(FILE *__''stream''__, char |
|
|
27 |
*__''buf''__, int__ ''mode'' __, size_t__ |
|
|
28 |
''size''__);__ |
|
|
29 |
!!DESCRIPTION |
|
|
30 |
|
|
|
31 |
|
|
|
32 |
The three types of buffering available are unbuffered, block |
|
|
33 |
buffered, and line buffered. When an output stream is |
|
|
34 |
unbuffered, information appears on the destination file or |
|
|
35 |
terminal as soon as written; when it is block buffered many |
|
|
36 |
characters are saved up and written as a block; when it is |
|
|
37 |
line buffered characters are saved up until a newline is |
|
|
38 |
output or input is read from any stream attached to a |
|
|
39 |
terminal device (typically stdin). The function |
|
|
40 |
fflush(3) may be used to force the block out early. |
|
|
41 |
(See fclose(3).) Normally all files are block |
|
|
42 |
buffered. When the first I/O operation occurs on a file, |
|
|
43 |
malloc(3) is called, and a buffer is obtained. If a |
|
|
44 |
stream refers to a terminal (as ''stdout'' normally does) |
|
|
45 |
it is line buffered. The standard error stream ''stderr'' |
|
|
46 |
is always unbuffered by default. |
|
|
47 |
|
|
|
48 |
|
|
|
49 |
The __setvbuf__ function may be used on any open stream |
|
|
50 |
to change its buffer. The ''mode'' parameter must be one |
|
|
51 |
of the following three macros: |
|
|
52 |
|
|
|
53 |
|
|
|
54 |
___IONBF__ |
|
|
55 |
|
|
|
56 |
|
|
|
57 |
unbuffered |
|
|
58 |
|
|
|
59 |
|
|
|
60 |
___IOLBF__ |
|
|
61 |
|
|
|
62 |
|
|
|
63 |
line buffered |
|
|
64 |
|
|
|
65 |
|
|
|
66 |
___IOFBF__ |
|
|
67 |
|
|
|
68 |
|
|
|
69 |
fully buffered |
|
|
70 |
|
|
|
71 |
|
|
|
72 |
Except for unbuffered files, the ''buf'' argument should |
|
|
73 |
point to a buffer at least ''size'' bytes long; this |
|
|
74 |
buffer will be used instead of the current buffer. If the |
|
|
75 |
argument ''buf'' is __NULL__, only the mode is |
|
|
76 |
affected; a new buffer will be allocated on the next read or |
|
|
77 |
write operation. The ''setvbuf'' function may only be |
|
|
78 |
used after opening a stream and before any other operations |
|
|
79 |
have been performed on it. |
|
|
80 |
|
|
|
81 |
|
|
|
82 |
The other three calls are, in effect, simply aliases for |
|
|
83 |
calls to __setvbuf__. The __setbuf__ function is |
|
|
84 |
exactly equivalent to the call |
|
|
85 |
|
|
|
86 |
|
|
|
87 |
setvbuf(stream, buf, buf ? _IOFBF : _IONBF, |
|
|
88 |
BUFSIZ); |
|
|
89 |
|
|
|
90 |
|
|
|
91 |
The __setbuffer__ function is the same, except that the |
|
|
92 |
size of the buffer is up to the caller, rather than being |
|
|
93 |
determined by the default __BUFSIZ__. The |
|
|
94 |
__setlinebuf__ function is exactly equivalent to the |
|
|
95 |
call: |
|
|
96 |
|
|
|
97 |
|
|
|
98 |
setvbuf(stream, (char *)NULL, _IOLBF, 0); |
|
|
99 |
!!RETURN VALUE |
|
|
100 |
|
|
|
101 |
|
|
|
102 |
The function __setvbuf__ returns 0 on success. It can |
|
|
103 |
return any value on failure, but returns nonzero when |
|
|
104 |
''mode'' is invalid or the request cannot be honoured. It |
|
|
105 |
may set ''errno'' on failure. The other functions are |
|
|
106 |
void. |
|
|
107 |
!!CONFORMING TO |
|
|
108 |
|
|
|
109 |
|
|
|
110 |
The __setbuf__ and __setvbuf__ functions conform to |
|
|
111 |
ANSI X3.159-1989 (``ANSI C''). |
|
|
112 |
!!BUGS |
|
|
113 |
|
|
|
114 |
|
|
|
115 |
The __setbuffer__ and __setlinebuf__ functions are not |
|
|
116 |
portable to versions of BSD before 4.2BSD, and are available |
|
|
117 |
under Linux since libc 4.5.21. On 4.2BSD and 4.3BSD systems, |
|
|
118 |
__setbuf__ always uses a suboptimal buffer size and |
|
|
119 |
should be avoided. |
|
|
120 |
|
|
|
121 |
|
|
|
122 |
You must make sure that both ''buf'' and the space it |
|
|
123 |
points to still exist by the time ''stream'' is closed, |
|
|
124 |
which also happens at program termination. |
|
|
125 |
|
|
|
126 |
|
|
|
127 |
For example, the following is illegal: |
|
|
128 |
|
|
|
129 |
|
|
|
130 |
#include |
|
|
131 |
!!SEE ALSO |
|
|
132 |
|
|
|
133 |
|
|
|
134 |
fclose(3), fflush(3), fopen(3), |
|
|
135 |
fread(3), malloc(3), printf(3), |
|
|
136 |
puts(3) |
|
|
137 |
---- |