| .\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998 |
| .\" |
| .\" This man page was written in 1998 by David A. Holland |
| .\" Polished a bit by aeb. |
| .\" |
| .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
| .\" Placed in the Public Domain. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2005-06-16 mtk, mentioned freopen() |
| .\" 2007-12-08, mtk, Converted from mdoc to man macros |
| .\" |
| .TH STDIN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| stdin, stdout, stderr \- standard I/O streams |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "extern FILE *" stdin ; |
| .BI "extern FILE *" stdout ; |
| .BI "extern FILE *" stderr ; |
| .fi |
| .SH DESCRIPTION |
| Under normal circumstances every UNIX program has three streams opened |
| for it when it starts up, one for input, one for output, and one for |
| printing diagnostic or error messages. |
| These are typically attached to |
| the user's terminal (see |
| .BR tty (4)) |
| but might instead refer to files or other devices, depending on what |
| the parent process chose to set up. |
| (See also the "Redirection" section of |
| .BR sh (1).) |
| .PP |
| The input stream is referred to as "standard input"; the output stream is |
| referred to as "standard output"; and the error stream is referred to |
| as "standard error". |
| These terms are abbreviated to form the symbols |
| used to refer to these files, namely |
| .IR stdin , |
| .IR stdout , |
| and |
| .IR stderr . |
| .PP |
| Each of these symbols is a |
| .BR stdio (3) |
| macro of type pointer to |
| .IR FILE , |
| and can be used with functions like |
| .BR fprintf (3) |
| or |
| .BR fread (3). |
| .PP |
| Since |
| .IR FILE s |
| are a buffering wrapper around UNIX file descriptors, the |
| same underlying files may also be accessed using the raw UNIX file |
| interface, that is, the functions like |
| .BR read (2) |
| and |
| .BR lseek (2). |
| .PP |
| On program startup, the integer file descriptors |
| associated with the streams |
| .IR stdin , |
| .IR stdout , |
| and |
| .I stderr |
| are 0, 1, and 2, respectively. |
| The preprocessor symbols |
| .BR STDIN_FILENO , |
| .BR STDOUT_FILENO , |
| and |
| .B STDERR_FILENO |
| are defined with these values in |
| .IR <unistd.h> . |
| (Applying |
| .BR freopen (3) |
| to one of these streams can change the file descriptor number |
| associated with the stream.) |
| .PP |
| Note that mixing use of |
| .IR FILE s |
| and raw file descriptors can produce |
| unexpected results and should generally be avoided. |
| (For the masochistic among you: POSIX.1, section 8.2.3, describes |
| in detail how this interaction is supposed to work.) |
| A general rule is that file descriptors are handled in the kernel, |
| while stdio is just a library. |
| This means for example, that after an |
| .BR exec (3), |
| the child inherits all open file descriptors, but all old streams |
| have become inaccessible. |
| .PP |
| Since the symbols |
| .IR stdin , |
| .IR stdout , |
| and |
| .I stderr |
| are specified to be macros, assigning to them is nonportable. |
| The standard streams can be made to refer to different files |
| with help of the library function |
| .BR freopen (3), |
| specially introduced to make it possible to reassign |
| .IR stdin , |
| .IR stdout , |
| and |
| .IR stderr . |
| The standard streams are closed by a call to |
| .BR exit (3) |
| and by normal program termination. |
| .SH CONFORMING TO |
| The |
| .IR stdin , |
| .IR stdout , |
| and |
| .I stderr |
| macros conform to C89 |
| and this standard also stipulates that these three |
| streams shall be open at program startup. |
| .SH NOTES |
| The stream |
| .I stderr |
| is unbuffered. |
| The stream |
| .I stdout |
| is line-buffered when it points to a terminal. |
| Partial lines will not |
| appear until |
| .BR fflush (3) |
| or |
| .BR exit (3) |
| is called, or a newline is printed. |
| This can produce unexpected |
| results, especially with debugging output. |
| The buffering mode of the standard streams (or any other stream) |
| can be changed using the |
| .BR setbuf (3) |
| or |
| .BR setvbuf (3) |
| call. |
| Note that in case |
| .I stdin |
| is associated with a terminal, there may also be input buffering |
| in the terminal driver, entirely unrelated to stdio buffering. |
| (Indeed, normally terminal input is line buffered in the kernel.) |
| This kernel input handling can be modified using calls like |
| .BR tcsetattr (3); |
| see also |
| .BR stty (1), |
| and |
| .BR termios (3). |
| .SH SEE ALSO |
| .BR csh (1), |
| .BR sh (1), |
| .BR open (2), |
| .BR fopen (3), |
| .BR stdio (3) |