]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 | |
8f0aff2a | 4 | .\" Polished a bit by aeb. |
2297bf0e | 5 | .\" |
a1ecf930 | 6 | .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
8f0aff2a | 7 | .\" Placed in the Public Domain. |
a1ecf930 | 8 | .\" %%%LICENSE_END |
fea681da | 9 | .\" |
e787eaba | 10 | .\" 2005-06-16 mtk, mentioned freopen() |
352bedee | 11 | .\" 2007-12-08, mtk, Converted from mdoc to man macros |
3233d665 | 12 | .\" |
4b8c67d9 | 13 | .TH STDIN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
3233d665 MK |
14 | .SH NAME |
15 | stdin, stdout, stderr \- standard I/O streams | |
16 | .SH SYNOPSIS | |
17 | .nf | |
18 | .B #include <stdio.h> | |
dbfe9c70 | 19 | .PP |
62218dc0 MK |
20 | .BI "extern FILE *" stdin ; |
21 | .BI "extern FILE *" stdout ; | |
22 | .BI "extern FILE *" stderr ; | |
3233d665 MK |
23 | .fi |
24 | .SH DESCRIPTION | |
008f1ecc | 25 | Under normal circumstances every UNIX program has three streams opened |
fea681da | 26 | for it when it starts up, one for input, one for output, and one for |
c13182ef MK |
27 | printing diagnostic or error messages. |
28 | These are typically attached to | |
fea681da | 29 | the user's terminal (see |
6968bea3 | 30 | .BR tty (4)) |
fea681da | 31 | but might instead refer to files or other devices, depending on what |
6387216b MK |
32 | the parent process chose to set up. |
33 | (See also the "Redirection" section of | |
3233d665 | 34 | .BR sh (1).) |
5ec60461 | 35 | .PP |
3233d665 MK |
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". | |
c13182ef | 39 | These terms are abbreviated to form the symbols |
fea681da | 40 | used to refer to these files, namely |
3233d665 MK |
41 | .IR stdin , |
42 | .IR stdout , | |
fea681da | 43 | and |
3233d665 | 44 | .IR stderr . |
847e0d88 | 45 | .PP |
fea681da | 46 | Each of these symbols is a |
3233d665 | 47 | .BR stdio (3) |
ec5a588f MK |
48 | macro of type pointer to |
49 | .IR FILE , | |
50 | and can be used with functions like | |
3233d665 | 51 | .BR fprintf (3) |
fea681da | 52 | or |
3233d665 | 53 | .BR fread (3). |
5ec60461 | 54 | .PP |
ec5a588f MK |
55 | Since |
56 | .IR FILE s | |
008f1ecc MK |
57 | are a buffering wrapper around UNIX file descriptors, the |
58 | same underlying files may also be accessed using the raw UNIX file | |
fea681da | 59 | interface, that is, the functions like |
3233d665 | 60 | .BR read (2) |
fea681da | 61 | and |
3233d665 | 62 | .BR lseek (2). |
5ec60461 | 63 | .PP |
6a4c2e36 MK |
64 | On program startup, the integer file descriptors |
65 | associated with the streams | |
25c626cf | 66 | .IR stdin , |
3233d665 | 67 | .IR stdout , |
fea681da | 68 | and |
3233d665 | 69 | .I stderr |
6a4c2e36 | 70 | are 0, 1, and 2, respectively. |
3233d665 MK |
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 | |
c9942389 | 77 | .IR <unistd.h> . |
6a4c2e36 | 78 | (Applying |
3233d665 | 79 | .BR freopen (3) |
6a4c2e36 MK |
80 | to one of these streams can change the file descriptor number |
81 | associated with the stream.) | |
5ec60461 | 82 | .PP |
ec5a588f MK |
83 | Note that mixing use of |
84 | .IR FILE s | |
85 | and raw file descriptors can produce | |
fea681da MK |
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, | |
c13182ef MK |
90 | while stdio is just a library. |
91 | This means for example, that after an | |
3233d665 | 92 | .BR exec (3), |
1e321034 | 93 | the child inherits all open file descriptors, but all old streams |
c13182ef | 94 | have become inaccessible. |
5ec60461 | 95 | .PP |
fea681da | 96 | Since the symbols |
25c626cf | 97 | .IR stdin , |
3233d665 | 98 | .IR stdout , |
fea681da | 99 | and |
3233d665 | 100 | .I stderr |
d603cc27 | 101 | are specified to be macros, assigning to them is nonportable. |
fea681da MK |
102 | The standard streams can be made to refer to different files |
103 | with help of the library function | |
3233d665 | 104 | .BR freopen (3), |
fea681da | 105 | specially introduced to make it possible to reassign |
3233d665 MK |
106 | .IR stdin , |
107 | .IR stdout , | |
fea681da | 108 | and |
3233d665 | 109 | .IR stderr . |
fea681da | 110 | The standard streams are closed by a call to |
3233d665 | 111 | .BR exit (3) |
fea681da | 112 | and by normal program termination. |
47297adb | 113 | .SH CONFORMING TO |
3ba63d8e MK |
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 | |
fea681da | 123 | The stream |
3ba63d8e MK |
124 | .I stderr |
125 | is unbuffered. | |
c13182ef | 126 | The stream |
3ba63d8e MK |
127 | .I stdout |
128 | is line-buffered when it points to a terminal. | |
c13182ef | 129 | Partial lines will not |
fea681da | 130 | appear until |
3233d665 | 131 | .BR fflush (3) |
fea681da | 132 | or |
3233d665 | 133 | .BR exit (3) |
c13182ef MK |
134 | is called, or a newline is printed. |
135 | This can produce unexpected | |
fea681da MK |
136 | results, especially with debugging output. |
137 | The buffering mode of the standard streams (or any other stream) | |
138 | can be changed using the | |
3233d665 | 139 | .BR setbuf (3) |
fea681da | 140 | or |
3233d665 | 141 | .BR setvbuf (3) |
fea681da MK |
142 | call. |
143 | Note that in case | |
3ba63d8e MK |
144 | .I stdin |
145 | is associated with a terminal, there may also be input buffering | |
fea681da MK |
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 | |
3233d665 | 149 | .BR tcsetattr (3); |
fea681da | 150 | see also |
3233d665 | 151 | .BR stty (1), |
fea681da | 152 | and |
3233d665 | 153 | .BR termios (3). |
3233d665 | 154 | .SH SEE ALSO |
3233d665 | 155 | .BR csh (1), |
f0c34053 | 156 | .BR sh (1), |
3233d665 MK |
157 | .BR open (2), |
158 | .BR fopen (3), | |
159 | .BR stdio (3) |