]>
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 | .\" | |
1c6f59c2 | 39 | .TH STDIO 3 2017-11-26 "" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | stdio \- standard input/output library functions | |
42 | .SH SYNOPSIS | |
43 | .B #include <stdio.h> | |
68e4db0a | 44 | .PP |
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 | |
6da3279c SL |
113 | .IR stdin , |
114 | .IR stdout , | |
fea681da MK |
115 | and |
116 | .IR stderr . | |
117 | When opened, the standard error stream is not fully buffered; the standard | |
118 | input and output streams are fully buffered if and only if the streams do | |
29abb77b | 119 | not refer to an interactive device. |
fea681da MK |
120 | .PP |
121 | Output streams that refer to terminal devices are always line buffered by | |
122 | default; pending output to such streams is written automatically whenever | |
c13182ef MK |
123 | an input stream that refers to a terminal device is read. |
124 | In cases where a | |
fea681da MK |
125 | large amount of computation is done after printing part of a line on an |
126 | output terminal, it is necessary to | |
127 | .BR fflush (3) | |
128 | the standard output before going off and computing so that the output will | |
129 | appear. | |
130 | .PP | |
131 | The | |
f19a0f03 | 132 | .I stdio |
fea681da MK |
133 | library is a part of the library |
134 | .B libc | |
5f70d096 MK |
135 | and routines are automatically loaded as needed by |
136 | .BR cc (1). | |
fea681da | 137 | The |
3d341b33 | 138 | SYNOPSIS |
fea681da MK |
139 | sections of the following manual pages indicate which include files are to |
140 | be used, what the compiler declaration for the function looks like and | |
141 | which external variables are of interest. | |
142 | .PP | |
3b777aff | 143 | The following are defined as macros; these names may not be reused without |
fea681da MK |
144 | first removing their current definitions with |
145 | .BR #undef : | |
146 | .BR BUFSIZ , | |
147 | .BR EOF , | |
148 | .BR FILENAME_MAX , | |
149 | .BR FOPEN_MAX , | |
150 | .BR L_cuserid , | |
151 | .BR L_ctermid , | |
a5e0a0e4 | 152 | .BR L_tmpnam , |
fea681da MK |
153 | .BR NULL , |
154 | .BR SEEK_END , | |
155 | .BR SEEK_SET , | |
24a7082a | 156 | .BR SEEK_CUR , |
fea681da MK |
157 | .BR TMP_MAX , |
158 | .BR clearerr , | |
159 | .BR feof , | |
160 | .BR ferror , | |
161 | .BR fileno , | |
834fec09 MK |
162 | .\" Not on Linux: .BR fropen , |
163 | .\" Not on Linux: .BR fwopen , | |
fea681da MK |
164 | .BR getc , |
165 | .BR getchar , | |
166 | .BR putc , | |
167 | .BR putchar , | |
168 | .BR stderr , | |
169 | .BR stdin , | |
170 | .BR stdout . | |
171 | Function versions of the macro functions | |
172 | .BR feof , | |
173 | .BR ferror , | |
174 | .BR clearerr , | |
175 | .BR fileno , | |
176 | .BR getc , | |
177 | .BR getchar , | |
178 | .BR putc , | |
179 | and | |
180 | .B putchar | |
181 | exist and will be used if the macros definitions are explicitly removed. | |
73d8cece | 182 | .SS List of functions |
9771e6de MK |
183 | .TS |
184 | ; | |
185 | lb lb | |
3242546c | 186 | l l. |
9771e6de MK |
187 | Function Description |
188 | _ | |
3242546c MK |
189 | \fBclearerr\fP(3) check and reset stream status |
190 | \fBfclose\fP(3) close a stream | |
191 | \fBfdopen\fP(3) stream open functions | |
192 | \fBfeof\fP(3) check and reset stream status | |
193 | \fBferror\fP(3) check and reset stream status | |
194 | \fBfflush\fP(3) flush a stream | |
195 | \fBfgetc\fP(3) get next character or word from input stream | |
196 | \fBfgetpos\fP(3) reposition a stream | |
197 | \fBfgets\fP(3) get a line from a stream | |
198 | \fBfileno\fP(3) return the integer descriptor of the argument stream | |
199 | \fBfopen\fP(3) stream open functions | |
200 | \fBfprintf\fP(3) formatted output conversion | |
201 | \fBfpurge\fP(3) flush a stream | |
202 | \fBfputc\fP(3) output a character or word to a stream | |
203 | \fBfputs\fP(3) output a line to a stream | |
204 | \fBfread\fP(3) binary stream input/output | |
205 | \fBfreopen\fP(3) stream open functions | |
206 | \fBfscanf\fP(3) input format conversion | |
207 | \fBfseek\fP(3) reposition a stream | |
208 | \fBfsetpos\fP(3) reposition a stream | |
209 | \fBftell\fP(3) reposition a stream | |
210 | \fBfwrite\fP(3) binary stream input/output | |
211 | \fBgetc\fP(3) get next character or word from input stream | |
212 | \fBgetchar\fP(3) get next character or word from input stream | |
213 | \fBgets\fP(3) get a line from a stream | |
214 | \fBgetw\fP(3) get next character or word from input stream | |
215 | \fBmktemp\fP(3) make temporary filename (unique) | |
216 | \fBperror\fP(3) system error messages | |
217 | \fBprintf\fP(3) formatted output conversion | |
218 | \fBputc\fP(3) output a character or word to a stream | |
219 | \fBputchar\fP(3) output a character or word to a stream | |
220 | \fBputs\fP(3) output a line to a stream | |
221 | \fBputw\fP(3) output a character or word to a stream | |
222 | \fBremove\fP(3) remove directory entry | |
223 | \fBrewind\fP(3) reposition a stream | |
224 | \fBscanf\fP(3) input format conversion | |
225 | \fBsetbuf\fP(3) stream buffering operations | |
226 | \fBsetbuffer\fP(3) stream buffering operations | |
227 | \fBsetlinebuf\fP(3) stream buffering operations | |
228 | \fBsetvbuf\fP(3) stream buffering operations | |
229 | \fBsprintf\fP(3) formatted output conversion | |
230 | \fBsscanf\fP(3) input format conversion | |
231 | \fBstrerror\fP(3) system error messages | |
232 | \fBsys_errlist\fP(3) system error messages | |
233 | \fBsys_nerr\fP(3) system error messages | |
234 | \fBtempnam\fP(3) temporary file routines | |
235 | \fBtmpfile\fP(3) temporary file routines | |
236 | \fBtmpnam\fP(3) temporary file routines | |
237 | \fBungetc\fP(3) un-get character from input stream | |
238 | \fBvfprintf\fP(3) formatted output conversion | |
239 | \fBvfscanf\fP(3) input format conversion | |
240 | \fBvprintf\fP(3) formatted output conversion | |
241 | \fBvscanf\fP(3) input format conversion | |
242 | \fBvsprintf\fP(3) formatted output conversion | |
243 | \fBvsscanf\fP(3) input format conversion | |
9771e6de | 244 | .TE |
47297adb | 245 | .SH CONFORMING TO |
fea681da | 246 | The |
f19a0f03 | 247 | .I stdio |
68e1685c | 248 | library conforms to C89. |
47297adb | 249 | .SH SEE ALSO |
fea681da MK |
250 | .BR close (2), |
251 | .BR open (2), | |
252 | .BR read (2), | |
253 | .BR write (2), | |
a2337ea3 MK |
254 | .BR stdout (3), |
255 | .BR unlocked_stdio (3) |