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