original/man3/stdin.3

   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 2008-07-14 "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
  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
  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)
 160 .SH COLOPHON
 161 This page is part of release 3.67 of the Linux
 162 .I man-pages
 163 project.
 164 A description of the project,
 165 information about reporting bugs,
 166 and the latest version of this page,
 167 can be found at
 168 \%http://www.kernel.org/doc/man\-pages/.