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