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