Debian Codegraph @

upstream/fedora-44/man3/stdio.3

raw
1 '\" t
2 .\" Copyright (c) 1990, 1991 Regents of the University of California.
3 .\" All rights reserved.
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .\" @(#)stdio.3 6.5 (Berkeley) 5/6/91
8 .\"
9 .\" Converted for Linux, Mon Nov 29 16:07:22 1993, [email protected]
10 .\" Modified, 2001-12-26, aeb
11 .\"
12 .TH stdio 3 2024-12-24 "Linux man-pages 6.13"
13 .SH NAME
14 stdio \- standard input/output library functions
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ,\~ \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <stdio.h>
21 .P
22 .BI extern\~FILE\~\~* stdin ;
23 .BI extern\~FILE\~\~* stdout ;
24 .BI extern\~FILE\~\~* stderr ;
25 .fi
26 .SH DESCRIPTION
27 The standard I/O library provides a simple and efficient buffered stream
28 I/O interface.
29 Input and output is mapped into logical data streams and the
30 physical I/O characteristics are concealed.
31 The functions and macros are
32 listed below; more information is available from the individual man pages.
33 .P
34 A stream is associated with an external file (which may be a physical
35 device) by
36 .I opening
37 a file, which may involve creating a new file.
38 Creating an existing file
39 causes its former contents to be discarded.
40 If a file can support positioning requests (such as a disk file,
41 as opposed to a terminal), then a
42 .I file position indicator
43 associated with the stream is positioned at the start of the file (byte
44 zero), unless the file is opened with append mode.
45 If append mode is used,
46 it is unspecified whether the position indicator will be placed at the
47 start or the end of the file.
48 The position indicator is maintained by
49 subsequent reads, writes, and positioning requests.
50 All input occurs as if the characters were read by successive calls to the
51 .BR fgetc (3)
52 function; all output takes place as if all characters were written by
53 successive calls to the
54 .BR fputc (3)
55 function.
56 .P
57 A file is disassociated from a stream by
58 .I closing
59 the file.
60 Output streams are flushed (any unwritten buffer contents are
61 transferred to the host environment) before the stream is disassociated from
62 the file.
63 The value of a pointer to a
64 .I FILE
65 object is indeterminate after a file is closed (garbage).
66 .P
67 A file may be subsequently reopened, by the same or another program
68 execution, and its contents reclaimed or modified (if it can be
69 repositioned at the start).
70 If the main function returns to its original
71 caller, or the
72 .BR exit (3)
73 function is called, all open files are closed (hence all output streams are
74 flushed) before program termination.
75 Other methods of program termination,
76 such as
77 .BR abort (3)
78 do not bother about closing files properly.
79 .P
80 At program startup, three text streams are predefined and need not be
81 opened explicitly:
82 .I standard input
83 (for reading conventional input),
84 .I standard output
85 (for writing conventional output), and
86 .I standard error
87 (for writing diagnostic output).
88 These streams are abbreviated
89 .IR stdin ,
90 .IR stdout ,
91 and
92 .IR stderr .
93 When opened, the standard error stream is not fully buffered; the standard
94 input and output streams are fully buffered if and only if the streams do
95 not refer to an interactive device.
96 .P
97 Output streams that refer to terminal devices are always line buffered by
98 default; pending output to such streams is written automatically whenever
99 an input stream that refers to a terminal device is read.
100 In cases where a
101 large amount of computation is done after printing part of a line on an
102 output terminal, it is necessary to
103 .BR fflush (3)
104 the standard output before going off and computing so that the output will
105 appear.
106 .P
107 The
108 .I stdio
109 library is a part of the library
110 .B libc
111 and routines are automatically loaded as needed by
112 .BR cc (1).
113 The
114 SYNOPSIS
115 sections of the following manual pages indicate which include files are to
116 be used, what the compiler declaration for the function looks like and
117 which external variables are of interest.
118 .P
119 The following are defined as macros; these names may not be reused without
120 first removing their current definitions with
121 .BR #undef :
122 .BR BUFSIZ ,
123 .BR EOF ,
124 .BR FILENAME_MAX ,
125 .BR FOPEN_MAX ,
126 .BR L_cuserid ,
127 .BR L_ctermid ,
128 .BR L_tmpnam ,
129 .BR NULL ,
130 .BR SEEK_END ,
131 .BR SEEK_SET ,
132 .BR SEEK_CUR ,
133 .BR TMP_MAX ,
134 .BR clearerr ,
135 .BR feof ,
136 .BR ferror ,
137 .BR fileno ,
138 .\" Not on Linux: .BR fropen ,
139 .\" Not on Linux: .BR fwopen ,
140 .BR getc ,
141 .BR getchar ,
142 .BR putc ,
143 .BR putchar ,
144 .BR stderr ,
145 .BR stdin ,
146 .BR stdout .
147 Function versions of the macro functions
148 .BR feof ,
149 .BR ferror ,
150 .BR clearerr ,
151 .BR fileno ,
152 .BR getc ,
153 .BR getchar ,
154 .BR putc ,
155 and
156 .B putchar
157 exist and will be used if the macros definitions are explicitly removed.
158 .SS List of functions
159 .TS
160 ;
161 lb lbx
162 l l.
163 Function Description
164 _
165 T{
166 .BR clearerr (3)
167 T} T{
168 check and reset stream status
169 T}
170 T{
171 .BR fclose (3)
172 T} T{
173 close a stream
174 T}
175 T{
176 .BR fdopen (3)
177 T} T{
178 stream open functions
179 T}
180 T{
181 .BR feof (3)
182 T} T{
183 check and reset stream status
184 T}
185 T{
186 .BR ferror (3)
187 T} T{
188 check and reset stream status
189 T}
190 T{
191 .BR fflush (3)
192 T} T{
193 flush a stream
194 T}
195 T{
196 .BR fgetc (3)
197 T} T{
198 get next character or word from input stream
199 T}
200 T{
201 .BR fgetpos (3)
202 T} T{
203 reposition a stream
204 T}
205 T{
206 .BR fgets (3)
207 T} T{
208 get a line from a stream
209 T}
210 T{
211 .BR fileno (3)
212 T} T{
213 return the integer descriptor of the argument stream
214 T}
215 T{
216 .BR fmemopen (3)
217 T} T{
218 open memory as stream
219 T}
220 T{
221 .BR fopen (3)
222 T} T{
223 stream open functions
224 T}
225 T{
226 .BR fopencookie (3)
227 T} T{
228 open a custom stream
229 T}
230 T{
231 .BR fprintf (3)
232 T} T{
233 formatted output conversion
234 T}
235 T{
236 .BR fpurge (3)
237 T} T{
238 flush a stream
239 T}
240 T{
241 .BR fputc (3)
242 T} T{
243 output a character or word to a stream
244 T}
245 T{
246 .BR fputs (3)
247 T} T{
248 output a line to a stream
249 T}
250 T{
251 .BR fread (3)
252 T} T{
253 binary stream input/output
254 T}
255 T{
256 .BR freopen (3)
257 T} T{
258 stream open functions
259 T}
260 T{
261 .BR fscanf (3)
262 T} T{
263 input format conversion
264 T}
265 T{
266 .BR fseek (3)
267 T} T{
268 reposition a stream
269 T}
270 T{
271 .BR fsetpos (3)
272 T} T{
273 reposition a stream
274 T}
275 T{
276 .BR ftell (3)
277 T} T{
278 reposition a stream
279 T}
280 T{
281 .BR fwrite (3)
282 T} T{
283 binary stream input/output
284 T}
285 T{
286 .BR getc (3)
287 T} T{
288 get next character or word from input stream
289 T}
290 T{
291 .BR getchar (3)
292 T} T{
293 get next character or word from input stream
294 T}
295 T{
296 .BR gets (3)
297 T} T{
298 get a line from a stream
299 T}
300 T{
301 .BR getw (3)
302 T} T{
303 get next character or word from input stream
304 T}
305 T{
306 .BR mktemp (3)
307 T} T{
308 make temporary filename (unique)
309 T}
310 T{
311 .BR open_memstream (3)
312 T} T{
313 open a dynamic memory buffer stream
314 T}
315 T{
316 .BR open_wmemstream (3)
317 T} T{
318 open a dynamic memory buffer stream
319 T}
320 T{
321 .BR perror (3)
322 T} T{
323 system error messages
324 T}
325 T{
326 .BR printf (3)
327 T} T{
328 formatted output conversion
329 T}
330 T{
331 .BR putc (3)
332 T} T{
333 output a character or word to a stream
334 T}
335 T{
336 .BR putchar (3)
337 T} T{
338 output a character or word to a stream
339 T}
340 T{
341 .BR puts (3)
342 T} T{
343 output a line to a stream
344 T}
345 T{
346 .BR putw (3)
347 T} T{
348 output a character or word to a stream
349 T}
350 T{
351 .BR remove (3)
352 T} T{
353 remove directory entry
354 T}
355 T{
356 .BR rewind (3)
357 T} T{
358 reposition a stream
359 T}
360 T{
361 .BR scanf (3)
362 T} T{
363 input format conversion
364 T}
365 T{
366 .BR setbuf (3)
367 T} T{
368 stream buffering operations
369 T}
370 T{
371 .BR setbuffer (3)
372 T} T{
373 stream buffering operations
374 T}
375 T{
376 .BR setlinebuf (3)
377 T} T{
378 stream buffering operations
379 T}
380 T{
381 .BR setvbuf (3)
382 T} T{
383 stream buffering operations
384 T}
385 T{
386 .BR sprintf (3)
387 T} T{
388 formatted output conversion
389 T}
390 T{
391 .BR sscanf (3)
392 T} T{
393 input format conversion
394 T}
395 T{
396 .BR strerror (3)
397 T} T{
398 system error messages
399 T}
400 T{
401 .BR sys_errlist (3)
402 T} T{
403 system error messages
404 T}
405 T{
406 .BR sys_nerr (3)
407 T} T{
408 system error messages
409 T}
410 T{
411 .BR tempnam (3)
412 T} T{
413 temporary file routines
414 T}
415 T{
416 .BR tmpfile (3)
417 T} T{
418 temporary file routines
419 T}
420 T{
421 .BR tmpnam (3)
422 T} T{
423 temporary file routines
424 T}
425 T{
426 .BR ungetc (3)
427 T} T{
428 un-get character from input stream
429 T}
430 T{
431 .BR vfprintf (3)
432 T} T{
433 formatted output conversion
434 T}
435 T{
436 .BR vfscanf (3)
437 T} T{
438 input format conversion
439 T}
440 T{
441 .BR vprintf (3)
442 T} T{
443 formatted output conversion
444 T}
445 T{
446 .BR vscanf (3)
447 T} T{
448 input format conversion
449 T}
450 T{
451 .BR vsprintf (3)
452 T} T{
453 formatted output conversion
454 T}
455 T{
456 .BR vsscanf (3)
457 T} T{
458 input format conversion
459 T}
460 .TE
461 .SH STANDARDS
462 C11, POSIX.1-2008.
463 .SH HISTORY
464 C89, POSIX.1-2001.
465 .SH SEE ALSO
466 .BR close (2),
467 .BR open (2),
468 .BR read (2),
469 .BR write (2),
470 .BR stdout (3),
471 .BR unlocked_stdio (3)