Debian Codegraph @

upstream/debian-unstable/man3/stdio.3

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