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