]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 | .\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu | |
35 | .\" Modified, 2001-12-26, aeb | |
36 | .\" | |
37 | .TH STDIO 3 2001-12-26 "" "Linux Programmer's Manual" | |
38 | .SH NAME | |
39 | stdio \- standard input/output library functions | |
40 | .SH SYNOPSIS | |
41 | .B #include <stdio.h> | |
42 | .sp | |
c8ce4bc6 | 43 | .BI "FILE *" stdin ; |
fea681da | 44 | .br |
d9cf37f4 | 45 | .BI "FILE *" stdout ; |
fea681da | 46 | .br |
d9cf37f4 | 47 | .BI "FILE *" stderr ; |
fea681da MK |
48 | .SH DESCRIPTION |
49 | The standard I/O library provides a simple and efficient buffered stream | |
c13182ef MK |
50 | I/O interface. |
51 | Input and output is mapped into logical data streams and the | |
52 | physical I/O characteristics are concealed. | |
53 | The functions and macros are | |
fea681da MK |
54 | listed below; more information is available from the individual man pages. |
55 | .PP | |
56 | A stream is associated with an external file (which may be a physical | |
57 | device) by | |
58 | .I opening | |
c13182ef MK |
59 | a file, which may involve creating a new file. |
60 | Creating an existing file | |
61 | causes its former contents to be discarded. | |
62 | If a file can support positioning requests (such as a disk file, | |
63 | as opposed to a terminal) then a | |
fea681da MK |
64 | .I file position indicator |
65 | associated with the stream is positioned at the start of the file (byte | |
c13182ef MK |
66 | zero), unless the file is opened with append mode. |
67 | If append mode is used, | |
fea681da | 68 | it is unspecified whether the position indicator will be placed at the |
c13182ef MK |
69 | start or the end of the file. |
70 | The position indicator is maintained by | |
71 | subsequent reads, writes and positioning requests. | |
72 | All input occurs as if the characters were read by successive calls to the | |
fea681da MK |
73 | .BR fgetc (3) |
74 | function; all output takes place as if all characters were written by | |
75 | successive calls to the | |
76 | .BR fputc (3) | |
77 | function. | |
78 | .PP | |
79 | A file is disassociated from a stream by | |
80 | .I closing | |
c13182ef MK |
81 | the file. |
82 | Output streams are flushed (any unwritten buffer contents are | |
fea681da | 83 | transferred to the host environment) before the stream is disassociated from |
c13182ef MK |
84 | the file. |
85 | The value of a pointer to a | |
097585ed | 86 | .I FILE |
fea681da MK |
87 | object is indeterminate after a file is closed (garbage). |
88 | .PP | |
89 | A file may be subsequently reopened, by the same or another program | |
90 | execution, and its contents reclaimed or modified (if it can be | |
c13182ef MK |
91 | repositioned at the start). |
92 | If the main function returns to its original | |
fea681da MK |
93 | caller, or the |
94 | .BR exit (3) | |
95 | function is called, all open files are closed (hence all output streams are | |
c13182ef MK |
96 | flushed) before program termination. |
97 | Other methods of program termination, | |
fea681da MK |
98 | such as |
99 | .BR abort (3) | |
100 | do not bother about closing files properly. | |
101 | .PP | |
102 | At program startup, three text streams are predefined and need not be | |
a43aff68 | 103 | opened explicitly: |
c13182ef | 104 | .I standard input |
a43aff68 | 105 | (for reading conventional input), |
c13182ef | 106 | .I standard output |
fea681da MK |
107 | (for writing conventional input), and |
108 | .I standard error | |
c13182ef MK |
109 | (for writing diagnostic output). |
110 | These streams are abbreviated | |
fea681da MK |
111 | .IR stdin , stdout |
112 | and | |
113 | .IR stderr . | |
114 | When opened, the standard error stream is not fully buffered; the standard | |
115 | input and output streams are fully buffered if and only if the streams do | |
29abb77b | 116 | not refer to an interactive device. |
fea681da MK |
117 | .PP |
118 | Output streams that refer to terminal devices are always line buffered by | |
119 | default; pending output to such streams is written automatically whenever | |
c13182ef MK |
120 | an input stream that refers to a terminal device is read. |
121 | In cases where a | |
fea681da MK |
122 | large amount of computation is done after printing part of a line on an |
123 | output terminal, it is necessary to | |
124 | .BR fflush (3) | |
125 | the standard output before going off and computing so that the output will | |
126 | appear. | |
127 | .PP | |
128 | The | |
f19a0f03 | 129 | .I stdio |
fea681da MK |
130 | library is a part of the library |
131 | .B libc | |
132 | and routines are automatically loaded as needed by the compilers | |
133 | .BR cc (1) | |
134 | and | |
135 | .BR pc (1). | |
136 | The | |
3d341b33 | 137 | SYNOPSIS |
fea681da MK |
138 | sections of the following manual pages indicate which include files are to |
139 | be used, what the compiler declaration for the function looks like and | |
140 | which external variables are of interest. | |
141 | .PP | |
3b777aff | 142 | The following are defined as macros; these names may not be reused without |
fea681da MK |
143 | first removing their current definitions with |
144 | .BR #undef : | |
145 | .BR BUFSIZ , | |
146 | .BR EOF , | |
147 | .BR FILENAME_MAX , | |
148 | .BR FOPEN_MAX , | |
149 | .BR L_cuserid , | |
150 | .BR L_ctermid , | |
a5e0a0e4 | 151 | .BR L_tmpnam , |
fea681da MK |
152 | .BR NULL , |
153 | .BR SEEK_END , | |
154 | .BR SEEK_SET , | |
24a7082a | 155 | .BR SEEK_CUR , |
fea681da MK |
156 | .BR TMP_MAX , |
157 | .BR clearerr , | |
158 | .BR feof , | |
159 | .BR ferror , | |
160 | .BR fileno , | |
834fec09 MK |
161 | .\" Not on Linux: .BR fropen , |
162 | .\" Not on Linux: .BR fwopen , | |
fea681da MK |
163 | .BR getc , |
164 | .BR getchar , | |
165 | .BR putc , | |
166 | .BR putchar , | |
167 | .BR stderr , | |
168 | .BR stdin , | |
169 | .BR stdout . | |
170 | Function versions of the macro functions | |
171 | .BR feof , | |
172 | .BR ferror , | |
173 | .BR clearerr , | |
174 | .BR fileno , | |
175 | .BR getc , | |
176 | .BR getchar , | |
177 | .BR putc , | |
178 | and | |
179 | .B putchar | |
180 | exist and will be used if the macros definitions are explicitly removed. | |
c634028a | 181 | .SS "List of functions" |
9771e6de MK |
182 | .TS |
183 | ; | |
184 | lb lb | |
185 | lb l. | |
186 | Function Description | |
187 | _ | |
188 | clearerr check and reset stream status | |
189 | fclose close a stream | |
190 | fdopen stream open functions | |
191 | feof check and reset stream status | |
192 | ferror check and reset stream status | |
193 | fflush flush a stream | |
194 | fgetc get next character or word from input stream | |
195 | fgetpos reposition a stream | |
196 | fgets get a line from a stream | |
197 | fileno return the integer descriptor of the argument stream | |
198 | fopen stream open functions | |
199 | fprintf formatted output conversion | |
200 | fpurge flush a stream | |
201 | fputc output a character or word to a stream | |
202 | fputs output a line to a stream | |
203 | fread binary stream input/output | |
204 | freopen stream open functions | |
205 | fscanf input format conversion | |
206 | fseek reposition a stream | |
207 | fsetpos reposition a stream | |
208 | ftell reposition a stream | |
209 | fwrite binary stream input/output | |
210 | getc get next character or word from input stream | |
211 | getchar get next character or word from input stream | |
212 | gets get a line from a stream | |
213 | getw get next character or word from input stream | |
214 | mktemp make temporary filename (unique) | |
215 | perror system error messages | |
216 | printf formatted output conversion | |
217 | putc output a character or word to a stream | |
218 | putchar output a character or word to a stream | |
219 | puts output a line to a stream | |
220 | putw output a character or word to a stream | |
221 | remove remove directory entry | |
222 | rewind reposition a stream | |
223 | scanf input format conversion | |
224 | setbuf stream buffering operations | |
225 | setbuffer stream buffering operations | |
226 | setlinebuf stream buffering operations | |
227 | setvbuf stream buffering operations | |
228 | sprintf formatted output conversion | |
229 | sscanf input format conversion | |
230 | strerror system error messages | |
231 | sys_errlist system error messages | |
232 | sys_nerr system error messages | |
233 | tempnam temporary file routines | |
234 | tmpfile temporary file routines | |
235 | tmpnam temporary file routines | |
236 | ungetc un-get character from input stream | |
237 | vfprintf formatted output conversion | |
238 | vfscanf input format conversion | |
239 | vprintf formatted output conversion | |
240 | vscanf input format conversion | |
241 | vsprintf formatted output conversion | |
242 | vsscanf input format conversion | |
243 | .TE | |
47297adb | 244 | .SH CONFORMING TO |
fea681da | 245 | The |
f19a0f03 | 246 | .I stdio |
68e1685c | 247 | library conforms to C89. |
47297adb | 248 | .SH SEE ALSO |
fea681da MK |
249 | .BR close (2), |
250 | .BR open (2), | |
251 | .BR read (2), | |
252 | .BR write (2), | |
a2337ea3 MK |
253 | .BR stdout (3), |
254 | .BR unlocked_stdio (3) |