| blob | 78f66e7fa3edf54d9e3f679d5054837eac86e283 |
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 .\"
5 .\" @(#)stdio.3s 6.2 (Berkeley) 5/13/86
6 .\"
7 .TH STDIO 3 "May 13, 1986"
8 .UC 4
9 .SH NAME
10 stdio \- standard buffered input/output package
11 .SH SYNOPSIS
12 .nf
13 .ft B
14 #include <stdio.h>
16 FILE *stdin;
17 FILE *stdout;
18 FILE *stderr;
19 .ft R
20 .fi
21 .SH DESCRIPTION
22 The functions in the standard I/O library constitute a user-level buffering
23 scheme. The in-line macros
24 .B getc
25 and
26 .BR putc (3)
27 handle characters quickly. The higher level routines
28 .BR gets ,
29 .BR fgets ,
30 .BR scanf ,
31 .BR fscanf ,
32 .BR fread ,
33 .BR puts ,
34 .BR fputs ,
35 .BR printf ,
36 .BR fprintf ,
37 .BR fwrite
38 all use
39 .B getc
40 and
41 .BR putc ;
42 they can be freely intermixed.
43 .PP
44 A file with associated buffering is called a
45 .IR stream ,
46 and is declared to be a pointer to a defined type
47 .SM
48 .BR FILE .
49 .BR Fopen (3)
50 creates certain descriptive data for a stream
51 and returns a pointer to designate the stream in all further transactions.
52 There are three normally open streams with constant pointers declared in
53 the include file and associated with the standard open files:
54 .TP 10n
55 .B stdin
56 standard input file
57 .br
58 .ns
59 .TP
60 .B stdout
61 standard output file
62 .br
63 .ns
64 .TP
65 .B stderr
66 standard error file
67 .PP
68 A constant `pointer'
69 .SM
70 .B NULL
71 (0)
72 designates no stream at all.
73 .PP
74 An integer constant
75 .SM
76 .B EOF
77 (\-1) is returned upon end of file or error by integer functions that
78 deal with streams.
79 .PP
80 Any routine that uses the standard input/output package
81 must include the header file
82 .RI < stdio.h >
83 of pertinent macro definitions.
84 The functions and constants mentioned in the standard I/O manual pages
85 are declared in the include file and need no further declaration.
86 The constants, and the following `functions' are
87 implemented as macros; redeclaration of these names is perilous:
88 .BR clearerr ,
89 .BR getc ,
90 .BR getchar ,
91 .BR putc ,
92 .BR putchar ,
93 .BR feof ,
94 .BR ferror ,
95 .BR fileno .
96 .SH "SEE ALSO"
97 .BR open (2),
98 .BR close (2),
99 .BR read (2),
100 .BR write (2),
101 .BR fclose (3),
102 .BR ferror (3),
103 .BR fopen (3),
104 .BR fread (3),
105 .BR fseek (3),
106 .BR getc (3),
107 .BR gets (3),
108 .BR printf (3),
109 .BR putc (3),
110 .BR puts (3),
111 .BR scanf (3),
112 .BR setbuf (3),
113 .BR ungetc (3).
114 .SH DIAGNOSTICS
115 The value
116 .SM
117 .B EOF
118 is returned uniformly to indicate that a
119 .SM
120 .B FILE
121 pointer has not been initialized with
122 .BR fopen ,
123 input (output) has been attempted on an output (input) stream, or a
124 .SM
125 .B FILE
126 pointer designates corrupt or otherwise unintelligible
127 .SM
128 .B FILE
129 data.
130 .PP
131 For purposes of efficiency, this implementation of the standard library
132 has been changed to line buffer output to a terminal by default and attempts
133 to do this transparently by flushing the output whenever a
134 .BR read (2)
135 from the standard input is necessary. This is almost always transparent,
136 but may cause confusion or malfunctioning of programs which use
137 standard i/o routines but use
138 .BR read (2)
139 themselves to read from the standard input.
140 .PP
141 In cases where a large amount of computation is done after printing
142 part of a line on an output terminal, it is necessary to
143 .BR fflush (3)
144 the standard output before going off and computing so that the output
145 will appear.
146 .SH BUGS
147 The standard buffered functions do not interact well with certain other
148 library and system functions, especially \fBfork\fP and \fBabort\fP.
149 .SH "LIST OF FUNCTIONS"
150 .sp 2
151 .nf
152 .ta \w'setlinebuf'u+2n +\w'setbuf(3)'u+10n
153 \fBName\fP \fBAppears on Page\fP \fBDescription\fP
154 .ta \w'setlinebuf'u+4n +\w'setbuf(3)'u+4n
155 .sp 5p
156 clearerr ferror(3) stream status inquiries
157 fclose fclose(3) close or flush a stream
158 fdopen fopen(3) open a stream
159 feof ferror(3) stream status inquiries
160 ferror ferror(3) stream status inquiries
161 fflush fclose(3) close or flush a stream
162 fgetc getc(3) get character or word from stream
163 fgets gets(3) get a string from a stream
164 fileno ferror(3) stream status inquiries
165 fopen fopen(3) open a stream
166 fprintf printf(3) formatted output conversion
167 fputc putc(3) put character or word on a stream
168 fputs puts(3) put a string on a stream
169 fread fread(3) buffered binary input/output
170 freopen fopen(3) open a stream
171 fscanf scanf(3) formatted input conversion
172 fseek fseek(3) reposition a stream
173 ftell fseek(3) reposition a stream
174 fwrite fread(3) buffered binary input/output
175 getc getc(3) get character or word from stream
176 getchar getc(3) get character or word from stream
177 gets gets(3) get a string from a stream
178 getw getc(3) get character or word from stream
179 printf printf(3) formatted output conversion
180 putc putc(3) put character or word on a stream
181 putchar putc(3) put character or word on a stream
182 puts puts(3) put a string on a stream
183 putw putc(3) put character or word on a stream
184 rewind fseek(3) reposition a stream
185 scanf scanf(3) formatted input conversion
186 setbuf setbuf(3) assign buffering to a stream
187 setvbuf setbuf(3) assign buffering to a stream
188 snprintf printf(3) formatted output conversion
189 sprintf printf(3) formatted output conversion
190 sscanf scanf(3) formatted input conversion
191 ungetc ungetc(3) push character back into input stream
192 vfprintf printf(3) formatted output conversion
193 vfscanf scanf(3) formatted input conversion
194 vprintf printf(3) formatted output conversion
195 vscanf scanf(3) formatted input conversion
196 vsnprintf printf(3) formatted output conversion
197 vsprintf printf(3) formatted output conversion
198 vsscanf scanf(3) formatted input conversion
199 .fi