Debian Codegraph @

upstream/debian-unstable/man3/stdin.3

raw
1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
2 .\" Placed in the Public Domain.
3 .\" %%%LICENSE_END
4 .\"
5 .TH stdin 3 2025-09-21 "Linux man-pages 6.18"
6 .SH NAME
7 stdin, stdout, stderr \- standard I/O streams
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .B #include <stdio.h>
14 .P
15 .BI extern\~FILE\~\~* stdin ;
16 .BI extern\~FILE\~\~* stdout ;
17 .BI extern\~FILE\~\~* stderr ;
18 .fi
19 .SH DESCRIPTION
20 Under normal circumstances every UNIX program has three streams opened
21 for it when it starts up, one for input, one for output, and one for
22 printing diagnostic or error messages.
23 These are typically attached to
24 the user's terminal (see
25 .BR tty (4))
26 but might instead refer to files or other devices, depending on what
27 the parent process chose to set up.
28 (See also the "Redirections" section of
29 .BR sh (1).)
30 .P
31 The input stream is referred to as "standard input";
32 the output stream is referred to as "standard output";
33 and the error stream is referred to as "standard error".
34 These terms are abbreviated to form the symbols
35 used to refer to these files,
36 namely
37 .IR stdin ,
38 .IR stdout ,
39 and
40 .IR stderr .
41 .P
42 Each of these symbols is a
43 .BR stdio (3)
44 macro of type pointer to
45 .IR FILE ,
46 and can be used with functions like
47 .BR fprintf (3)
48 or
49 .BR fread (3).
50 .P
51 Since
52 .IR FILE s
53 are a buffering wrapper around UNIX file descriptors, the
54 same underlying files may also be accessed using the raw UNIX file
55 interface, that is, the functions like
56 .BR read (2)
57 and
58 .BR lseek (2).
59 .P
60 On program startup, the integer file descriptors
61 associated with the streams
62 .IR stdin ,
63 .IR stdout ,
64 and
65 .I stderr
66 are 0, 1, and 2, respectively.
67 The preprocessor symbols
68 .BR STDIN_FILENO ,
69 .BR STDOUT_FILENO ,
70 and
71 .B STDERR_FILENO
72 are defined with these values in
73 .IR <unistd.h> .
74 (Applying
75 .BR freopen (3)
76 to one of these streams can change the file descriptor number
77 associated with the stream.)
78 .P
79 Note that mixing use of
80 .IR FILE s
81 and raw file descriptors can produce
82 unexpected results and should generally be avoided.
83 (For the masochistic among you: POSIX.1, section 8.2.3, describes
84 in detail how this interaction is supposed to work.)
85 A general rule is that file descriptors are handled in the kernel,
86 while stdio is just a library.
87 This means for example, that after an
88 .BR exec (3),
89 the child inherits all open file descriptors, but all old streams
90 have become inaccessible.
91 .P
92 Since the symbols
93 .IR stdin ,
94 .IR stdout ,
95 and
96 .I stderr
97 are specified to be macros, assigning to them is nonportable.
98 The standard streams can be made to refer to different files
99 with help of the library function
100 .BR freopen (3),
101 specially introduced to make it possible to reassign
102 .IR stdin ,
103 .IR stdout ,
104 and
105 .IR stderr .
106 The standard streams are closed by a call to
107 .BR exit (3)
108 and by normal program termination.
109 .SH STANDARDS
110 C11, POSIX.1-2008.
111 .P
112 The standards also stipulate that these three
113 streams shall be open at program startup.
114 .SH HISTORY
115 C89, POSIX.1-2001.
116 .SH NOTES
117 The stream
118 .I stderr
119 is unbuffered.
120 The stream
121 .I stdout
122 is line-buffered when it points to a terminal.
123 Partial lines will not
124 appear until
125 .BR fflush (3)
126 or
127 .BR exit (3)
128 is called, or a newline is printed.
129 This can produce unexpected
130 results, especially with debugging output.
131 The buffering mode of the standard streams (or any other stream)
132 can be changed using the
133 .BR setbuf (3)
134 or
135 .BR setvbuf (3)
136 call.
137 Note that in case
138 .I stdin
139 is associated with a terminal, there may also be input buffering
140 in the terminal driver, entirely unrelated to stdio buffering.
141 (Indeed, normally terminal input is line buffered in the kernel.)
142 This kernel input handling can be modified using calls like
143 .BR tcsetattr (3);
144 see also
145 .BR stty (1),
146 and
147 .BR termios (3).
148 .SH SEE ALSO
149 .BR csh (1),
150 .BR sh (1),
151 .BR open (2),
152 .BR fopen (3),
153 .BR stdio (3)