Debian Codegraph @

upstream/debian-trixie/man3/stdin.3

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