]>
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 | 6 | .\" |
352bedee | 7 | .\" 2007-12-08, mtk, Converted from mdoc to man macros |
3233d665 | 8 | .\" |
5ec60461 | 9 | .TH STDIN 3 2007-12-28 "Linux" "Linux Programmer's Manual" |
3233d665 MK |
10 | .SH NAME |
11 | stdin, stdout, stderr \- standard I/O streams | |
12 | .SH SYNOPSIS | |
13 | .nf | |
14 | .B #include <stdio.h> | |
15 | ||
62218dc0 MK |
16 | .BI "extern FILE *" stdin ; |
17 | .BI "extern FILE *" stdout ; | |
18 | .BI "extern FILE *" stderr ; | |
3233d665 MK |
19 | .fi |
20 | .SH DESCRIPTION | |
fea681da MK |
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 | 25 | the user's terminal (see |
3233d665 | 26 | .BR tty (4) |
fea681da | 27 | but might instead refer to files or other devices, depending on what |
6387216b MK |
28 | the parent process chose to set up. |
29 | (See also the "Redirection" section of | |
3233d665 | 30 | .BR sh (1).) |
5ec60461 | 31 | .PP |
3233d665 MK |
32 | The input stream is referred to as "standard input"; the output stream is |
33 | referred to as "standard output"; and the error stream is referred to | |
34 | as "standard error". | |
c13182ef | 35 | These terms are abbreviated to form the symbols |
fea681da | 36 | used to refer to these files, namely |
3233d665 MK |
37 | .IR stdin , |
38 | .IR stdout , | |
fea681da | 39 | and |
3233d665 MK |
40 | .IR stderr . |
41 | ||
fea681da | 42 | Each of these symbols is a |
3233d665 | 43 | .BR stdio (3) |
ec5a588f MK |
44 | macro of type pointer to |
45 | .IR FILE , | |
46 | and can be used with functions like | |
3233d665 | 47 | .BR fprintf (3) |
fea681da | 48 | or |
3233d665 | 49 | .BR fread (3). |
5ec60461 | 50 | .PP |
ec5a588f MK |
51 | Since |
52 | .IR FILE s | |
53 | are a buffering wrapper around Unix file descriptors, the | |
fea681da MK |
54 | same underlying files may also be accessed using the raw Unix file |
55 | interface, that is, the functions like | |
3233d665 | 56 | .BR read (2) |
fea681da | 57 | and |
3233d665 | 58 | .BR lseek (2). |
5ec60461 | 59 | .PP |
6a4c2e36 MK |
60 | On program startup, the integer file descriptors |
61 | associated with the streams | |
25c626cf | 62 | .IR stdin , |
3233d665 | 63 | .IR stdout , |
fea681da | 64 | and |
3233d665 | 65 | .I stderr |
6a4c2e36 | 66 | are 0, 1, and 2, respectively. |
3233d665 MK |
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 | |
c84371c6 | 73 | \fI<unistd.h>\fP. |
6a4c2e36 | 74 | (Applying |
3233d665 | 75 | .BR freopen (3) |
6a4c2e36 MK |
76 | to one of these streams can change the file descriptor number |
77 | associated with the stream.) | |
5ec60461 | 78 | .PP |
ec5a588f MK |
79 | Note that mixing use of |
80 | .IR FILE s | |
81 | and raw file descriptors can produce | |
fea681da MK |
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, | |
c13182ef MK |
86 | while stdio is just a library. |
87 | This means for example, that after an | |
3233d665 | 88 | .BR exec (3), |
1e321034 | 89 | the child inherits all open file descriptors, but all old streams |
c13182ef | 90 | have become inaccessible. |
5ec60461 | 91 | .PP |
fea681da | 92 | Since the symbols |
25c626cf | 93 | .IR stdin , |
3233d665 | 94 | .IR stdout , |
fea681da | 95 | and |
3233d665 | 96 | .I stderr |
fea681da MK |
97 | are specified to be macros, assigning to them is non-portable. |
98 | The standard streams can be made to refer to different files | |
99 | with help of the library function | |
3233d665 | 100 | .BR freopen (3), |
fea681da | 101 | specially introduced to make it possible to reassign |
3233d665 MK |
102 | .IR stdin , |
103 | .IR stdout , | |
fea681da | 104 | and |
3233d665 | 105 | .IR stderr . |
fea681da | 106 | The standard streams are closed by a call to |
3233d665 | 107 | .BR exit (3) |
fea681da | 108 | and by normal program termination. |
3233d665 | 109 | .SH CONSIDERATIONS |
fea681da | 110 | The stream |
3233d665 | 111 | stderr is unbuffered. |
c13182ef | 112 | The stream |
3233d665 | 113 | stdout is line-buffered when it points to a terminal. |
c13182ef | 114 | Partial lines will not |
fea681da | 115 | appear until |
3233d665 | 116 | .BR fflush (3) |
fea681da | 117 | or |
3233d665 | 118 | .BR exit (3) |
c13182ef MK |
119 | is called, or a newline is printed. |
120 | This can produce unexpected | |
fea681da MK |
121 | results, especially with debugging output. |
122 | The buffering mode of the standard streams (or any other stream) | |
123 | can be changed using the | |
3233d665 | 124 | .BR setbuf (3) |
fea681da | 125 | or |
3233d665 | 126 | .BR setvbuf (3) |
fea681da MK |
127 | call. |
128 | Note that in case | |
3233d665 | 129 | stdin is associated with a terminal, there may also be input buffering |
fea681da MK |
130 | in the terminal driver, entirely unrelated to stdio buffering. |
131 | (Indeed, normally terminal input is line buffered in the kernel.) | |
132 | This kernel input handling can be modified using calls like | |
3233d665 | 133 | .BR tcsetattr (3); |
fea681da | 134 | see also |
3233d665 | 135 | .BR stty (1), |
fea681da | 136 | and |
3233d665 MK |
137 | .BR termios (3). |
138 | .SH "CONFORMING TO" | |
fea681da | 139 | The |
3233d665 MK |
140 | .IR stdin , |
141 | .IR stdout , | |
fea681da | 142 | and |
3233d665 MK |
143 | .I stderr |
144 | macros conform to C89 | |
fea681da MK |
145 | and this standard also stipulates that these three |
146 | streams shall be open at program startup. | |
3233d665 MK |
147 | .SH SEE ALSO |
148 | .BR sh (1), | |
149 | .BR csh (1), | |
150 | .BR open (2), | |
151 | .BR fopen (3), | |
152 | .BR stdio (3) |