Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1990, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 | |
33 | .\" | |
34 | .Dd May 6, 1991 | |
35 | .Dt STDIO 3 | |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm stdio | |
39 | .Nd standard input/output library functions | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <stdio.h> | |
42 | .Fd FILE *stdin; | |
43 | .Fd FILE *stdout; | |
44 | .Fd FILE *stderr; | |
45 | .Sh DESCRIPTION | |
46 | The standard | |
47 | .Tn I/O | |
48 | library provides a simple and efficient buffered stream | |
49 | .Tn I/O | |
50 | interface. | |
51 | Input and ouput is mapped into logical data streams | |
52 | and the physical | |
53 | .Tn I/O | |
54 | characteristics are concealed. The functions and macros are listed | |
55 | below; more information is available from the individual man pages. | |
56 | .Pp | |
57 | A stream is associated with an external file (which may be a physical | |
58 | device) by | |
59 | .Em opening | |
60 | a file, which may involve creating a new file. Creating an | |
61 | existing file causes its former contents to be discarded. | |
62 | If a file can support positioning requests (such as a disk file, as opposed | |
63 | to a terminal) then a | |
64 | .Em file position indicator | |
65 | associated with the stream is positioned at the start of the file (byte | |
66 | zero), unless the file is opened with appened mode. If append mode | |
67 | is used, the position indicator will be placed the end-of-file. | |
68 | The position indicator is maintained by subsequent reads, writes | |
69 | and positioning requests. All input occurs as if the characters | |
70 | were read by successive calls to the | |
71 | .Xr fgetc 3 | |
72 | function; all ouput takes place as if all characters were | |
73 | read by successive calls to the | |
74 | .Xr fputc 3 | |
75 | function. | |
76 | .Pp | |
77 | A file is disassociated from a stream by | |
78 | .Em closing | |
79 | the file. | |
c2714ef5 | 80 | Ouput streams are flushed (any unwritten buffer contents are transferred |
15637ed4 RG |
81 | to the host environment) before the stream is disassociated from the file. |
82 | The value of a pointer to a | |
83 | .Dv FILE | |
84 | object is indeterminate after a file is closed (garbage). | |
85 | .Pp | |
86 | A file may be subsequently reopened, by the same or another program | |
87 | execution, and its contents reclaimed or modified (if it can be repositioned | |
88 | at the start). If the main function returns to its original caller, or | |
89 | the | |
90 | .Xr exit 3 | |
91 | function is called, all open files are closed (hence all output | |
92 | streams are flushed) before program termination. Other methods | |
93 | of program termination, such as | |
94 | .Xr abort 3 | |
95 | do not bother about closing files properly. | |
96 | .Pp | |
97 | At program startup, three text streams are predefined and need not be | |
98 | opened explicitly | |
99 | \(em | |
100 | .Em standard input | |
101 | (for reading converntional input), | |
102 | \(em | |
103 | .Em standard output | |
104 | (for writing converntional input), | |
105 | and | |
106 | .Em standard error | |
107 | (for writing diagnostic output). | |
108 | These streams are abbreviated | |
109 | .Em stdin , stdout | |
110 | and | |
111 | .Em stderr . | |
112 | When opened, the standard error stream | |
113 | is not fully buffered; the standard input and output streams are | |
114 | fully buffered if and only if the streams do not to refer to | |
115 | an interactive device. | |
116 | .Pp | |
117 | Output streams that refer to terminal devices | |
118 | are always line buffered by default; | |
119 | pending output to such streams is written automatically | |
120 | whenever an input stream that refers to a terminal device is read. | |
121 | In cases where a large amount of computation is done after printing | |
122 | part of a line on an output terminal, it is necessary to | |
123 | .Xr fflush 3 | |
124 | the standard output before going off and computing so that the output | |
125 | will appear. | |
126 | .Pp | |
127 | The | |
128 | .Nm stdio | |
129 | library is a part of the library | |
130 | .Xr libc | |
131 | and routines are automatically loaded as needed by the compilers | |
132 | .Xr cc 1 | |
133 | and | |
134 | .Xr pc 1 . | |
135 | The | |
136 | .Tn SYNOPSIS | |
137 | sections of the following manual pages indicate which include files | |
138 | are to be used, what the compiler declaration for the function | |
139 | looks like and which external variables are of interest. | |
140 | .Pp | |
141 | The following are defined as macros; | |
142 | these names may not be re-used | |
143 | without first removing their current definitions with | |
144 | .Dv #undef : | |
145 | .Dv BUFSIZ , | |
146 | .Dv EOF , | |
147 | .Dv FILENAME_MAX , | |
148 | .DV FOPEN_MAX , | |
149 | .Dv L_cuserid , | |
150 | .Dv L_ctermid , | |
151 | .Dv L_tmpnam, | |
152 | .Dv NULL , | |
153 | .Dv SEEK_END , | |
154 | .Dv SEEK_SET , | |
155 | .Dv SEE_CUR , | |
156 | .Dv TMP_MAX , | |
157 | .Dv clearerr , | |
158 | .Dv feof , | |
159 | .Dv ferror , | |
160 | .Dv fileno , | |
161 | .Dv fropen , | |
162 | .Dv fwopen , | |
163 | .Dv getc , | |
164 | .Dv getchar , | |
165 | .Dv putc , | |
166 | .Dv putchar , | |
167 | .Dv stderr , | |
168 | .Dv stdin , | |
169 | .Dv stdout . | |
170 | Function versions of the macro functions | |
171 | .Xr feof , | |
172 | .Xr ferror , | |
173 | .Xr clearerr , | |
174 | .Xr fileno , | |
175 | .Xr getc , | |
176 | .Xr getchar , | |
177 | .Xr putc , | |
178 | and | |
179 | .Xr putchar | |
180 | exist and will be used if the macros | |
181 | definitions are explicitly removed. | |
182 | .Sh SEE ALSO | |
183 | .Xr open 2 , | |
184 | .Xr close 2 , | |
185 | .Xr read 2 , | |
186 | .Xr write 2 | |
187 | .Sh BUGS | |
188 | The standard buffered functions do not interact well with certain other | |
189 | library and system functions, especially | |
190 | .Xr vfork | |
191 | and | |
192 | .Xr abort . | |
193 | .Sh STANDARDS | |
194 | The | |
195 | .Nm stdio | |
196 | library conforms to | |
197 | .St -ansiC . | |
198 | .Sh LIST OF FUNCTIONS | |
199 | .Bl -column "Description" | |
200 | .Sy Function Description | |
201 | clearerr check and reset stream status | |
202 | fclose close a stream | |
203 | fdopen stream open functions | |
204 | feof check and reset stream status | |
205 | ferror check and reset stream status | |
206 | fflush flush a stream | |
207 | fgetc get next character or word from input stream | |
208 | fgetline get a line from a stream | |
209 | fgetpos reposition a stream | |
210 | fgets get a line from a stream | |
211 | fileno check and reset stream status | |
212 | fopen stream open functions | |
213 | fprintf formatted output conversion | |
214 | fpurge flush a stream | |
215 | fputc output a character or word to a stream | |
216 | fputs output a line to a stream | |
217 | fread binary stream input/output | |
218 | freopen stream open functions | |
219 | fropen open a stream | |
220 | fscanf input format conversion | |
221 | fseek reposition a stream | |
222 | fsetpos reposition a stream | |
223 | ftell reposition a stream | |
224 | funopen open a stream | |
225 | fwopen open a stream | |
226 | fwrite binary stream input/output | |
227 | getc get next character or word from input stream | |
228 | getchar get next character or word from input stream | |
229 | gets get a line from a stream | |
230 | getw get next character or word from input stream | |
231 | mktemp make temporary file name (unique) | |
232 | perror system error messages | |
233 | printf formatted output conversion | |
234 | putc output a character or word to a stream | |
235 | putchar output a character or word to a stream | |
236 | puts output a line to a stream | |
237 | putw output a character or word to a stream | |
238 | remove remove directory entry | |
239 | rewind reposition a stream | |
240 | scanf input format conversion | |
241 | setbuf stream buffering operations | |
242 | setbuffer stream buffering operations | |
243 | setlinebuf stream buffering operations | |
244 | setvbuf stream buffering operations | |
245 | snprintf formatted output conversion | |
246 | sprintf formatted output conversion | |
247 | sscanf input format conversion | |
248 | strerror system error messages | |
249 | sys_errlist system error messages | |
250 | sys_nerr system error messages | |
251 | tempnam temporary file routines | |
252 | tmpfile temporary file routines | |
253 | tmpnam temporary file routines | |
254 | ungetc un-get character from input stream | |
255 | vfprintf formatted output conversion | |
256 | vfscanf input format conversion | |
257 | vprintf formatted output conversion | |
258 | vscanf input format conversion | |
259 | vsnprintf formatted output conversion | |
260 | vsprintf formatted output conversion | |
261 | vsscanf input format conversion | |
262 | .El |