Debian Codegraph @

upstream/debian-trixie/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-05-02 "Linux man-pages 6.9.1"
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 "FILE *" stdin ;
23 .BI "FILE *" stdout ;
24 .BI "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 \fBclearerr\fP(3) T{
166 check and reset stream status
167 T}
168 \fBfclose\fP(3) T{
169 close a stream
170 T}
171 \fBfdopen\fP(3) T{
172 stream open functions
173 T}
174 \fBfeof\fP(3) T{
175 check and reset stream status
176 T}
177 \fBferror\fP(3) T{
178 check and reset stream status
179 T}
180 \fBfflush\fP(3) T{
181 flush a stream
182 T}
183 \fBfgetc\fP(3) T{
184 get next character or word from input stream
185 T}
186 \fBfgetpos\fP(3) T{
187 reposition a stream
188 T}
189 \fBfgets\fP(3) T{
190 get a line from a stream
191 T}
192 \fBfileno\fP(3) T{
193 return the integer descriptor of the argument stream
194 T}
195 \fBfmemopen\fP(3) T{
196 open memory as stream
197 T}
198 \fBfopen\fP(3) T{
199 stream open functions
200 T}
201 \fBfopencookie\fP(3) T{
202 open a custom stream
203 T}
204 \fBfprintf\fP(3) T{
205 formatted output conversion
206 T}
207 \fBfpurge\fP(3) T{
208 flush a stream
209 T}
210 \fBfputc\fP(3) T{
211 output a character or word to a stream
212 T}
213 \fBfputs\fP(3) T{
214 output a line to a stream
215 T}
216 \fBfread\fP(3) T{
217 binary stream input/output
218 T}
219 \fBfreopen\fP(3) T{
220 stream open functions
221 T}
222 \fBfscanf\fP(3) T{
223 input format conversion
224 T}
225 \fBfseek\fP(3) T{
226 reposition a stream
227 T}
228 \fBfsetpos\fP(3) T{
229 reposition a stream
230 T}
231 \fBftell\fP(3) T{
232 reposition a stream
233 T}
234 \fBfwrite\fP(3) T{
235 binary stream input/output
236 T}
237 \fBgetc\fP(3) T{
238 get next character or word from input stream
239 T}
240 \fBgetchar\fP(3) T{
241 get next character or word from input stream
242 T}
243 \fBgets\fP(3) T{
244 get a line from a stream
245 T}
246 \fBgetw\fP(3) T{
247 get next character or word from input stream
248 T}
249 \fBmktemp\fP(3) T{
250 make temporary filename (unique)
251 T}
252 \fBopen_memstream\fP(3) T{
253 open a dynamic memory buffer stream
254 T}
255 \fBopen_wmemstream\fP(3) T{
256 open a dynamic memory buffer stream
257 T}
258 \fBperror\fP(3) T{
259 system error messages
260 T}
261 \fBprintf\fP(3) T{
262 formatted output conversion
263 T}
264 \fBputc\fP(3) T{
265 output a character or word to a stream
266 T}
267 \fBputchar\fP(3) T{
268 output a character or word to a stream
269 T}
270 \fBputs\fP(3) T{
271 output a line to a stream
272 T}
273 \fBputw\fP(3) T{
274 output a character or word to a stream
275 T}
276 \fBremove\fP(3) T{
277 remove directory entry
278 T}
279 \fBrewind\fP(3) T{
280 reposition a stream
281 T}
282 \fBscanf\fP(3) T{
283 input format conversion
284 T}
285 \fBsetbuf\fP(3) T{
286 stream buffering operations
287 T}
288 \fBsetbuffer\fP(3) T{
289 stream buffering operations
290 T}
291 \fBsetlinebuf\fP(3) T{
292 stream buffering operations
293 T}
294 \fBsetvbuf\fP(3) T{
295 stream buffering operations
296 T}
297 \fBsprintf\fP(3) T{
298 formatted output conversion
299 T}
300 \fBsscanf\fP(3) T{
301 input format conversion
302 T}
303 \fBstrerror\fP(3) T{
304 system error messages
305 T}
306 \fBsys_errlist\fP(3) T{
307 system error messages
308 T}
309 \fBsys_nerr\fP(3) T{
310 system error messages
311 T}
312 \fBtempnam\fP(3) T{
313 temporary file routines
314 T}
315 \fBtmpfile\fP(3) T{
316 temporary file routines
317 T}
318 \fBtmpnam\fP(3) T{
319 temporary file routines
320 T}
321 \fBungetc\fP(3) T{
322 un-get character from input stream
323 T}
324 \fBvfprintf\fP(3) T{
325 formatted output conversion
326 T}
327 \fBvfscanf\fP(3) T{
328 input format conversion
329 T}
330 \fBvprintf\fP(3) T{
331 formatted output conversion
332 T}
333 \fBvscanf\fP(3) T{
334 input format conversion
335 T}
336 \fBvsprintf\fP(3) T{
337 formatted output conversion
338 T}
339 \fBvsscanf\fP(3) T{
340 input format conversion
341 T}
342 .TE
343 .SH STANDARDS
344 C11, POSIX.1-2008.
345 .SH HISTORY
346 C89, POSIX.1-2001.
347 .SH SEE ALSO
348 .BR close (2),
349 .BR open (2),
350 .BR read (2),
351 .BR write (2),
352 .BR stdout (3),
353 .BR unlocked_stdio (3)