man3/stdio.3

   1 .\" Copyright (c) 1990, 1991 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)stdio.3     6.5 (Berkeley) 5/6/91
  33 .\"
  34 .\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu
  35 .\" Modified, 2001-12-26, aeb
  36 .\"
  37 .TH STDIO 3  2001-12-26 "" "Linux Programmer's Manual"
  38 .SH NAME
  39 stdio \- standard input/output library functions
  40 .SH SYNOPSIS
  41 .B #include <stdio.h>
  42 .sp
  43 .BI "FILE *" stdin ;
  44 .br
  45 .BI "FILE *" stdout ;
  46 .br
  47 .BI "FILE *" stderr ;
  48 .SH DESCRIPTION
  49 The standard I/O library provides a simple and efficient buffered stream
  50 I/O interface.
  51 Input and output is mapped into logical data streams and the
  52 physical I/O characteristics are concealed.
  53 The functions and macros are
  54 listed below; more information is available from the individual man pages.
  55 .PP
  56 A stream is associated with an external file (which may be a physical
  57 device) by
  58 .I opening
  59 a file, which may involve creating a new file.
  60 Creating an existing file
  61 causes its former contents to be discarded.
  62 If a file can support positioning requests (such as a disk file,
  63 as opposed to a terminal) then a
  64 .I file position indicator
  65 associated with the stream is positioned at the start of the file (byte
  66 zero), unless the file is opened with append mode.
  67 If append mode is used,
  68 it is unspecified whether the position indicator will be placed at the
  69 start or the end of the file.
  70 The position indicator is maintained by
  71 subsequent reads, writes and positioning requests.
  72 All input occurs as if the characters were read by successive calls to the
  73 .BR fgetc (3)
  74 function; all output takes place as if all characters were written by
  75 successive calls to the
  76 .BR fputc (3)
  77 function.
  78 .PP
  79 A file is disassociated from a stream by
  80 .I closing
  81 the file.
  82 Output streams are flushed (any unwritten buffer contents are
  83 transferred to the host environment) before the stream is disassociated from
  84 the file.
  85 The value of a pointer to a
  86 .I FILE
  87 object is indeterminate after a file is closed (garbage).
  88 .PP
  89 A file may be subsequently reopened, by the same or another program
  90 execution, and its contents reclaimed or modified (if it can be
  91 repositioned at the start).
  92 If the main function returns to its original
  93 caller, or the
  94 .BR exit (3)
  95 function is called, all open files are closed (hence all output streams are
  96 flushed) before program termination.
  97 Other methods of program termination,
  98 such as
  99 .BR abort (3)
 100 do not bother about closing files properly.
 101 .PP
 102 At program startup, three text streams are predefined and need not be
 103 opened explicitly:
 104 .I standard input
 105 (for reading conventional input),
 106 .I standard output
 107 (for writing conventional input), and
 108 .I standard error
 109 (for writing diagnostic output).
 110 These streams are abbreviated
 111 .IR stdin , stdout
 112 and
 113 .IR stderr .
 114 When opened, the standard error stream is not fully buffered; the standard
 115 input and output streams are fully buffered if and only if the streams do
 116 not refer to an interactive device.
 117 .PP
 118 Output streams that refer to terminal devices are always line buffered by
 119 default; pending output to such streams is written automatically whenever
 120 an input stream that refers to a terminal device is read.
 121 In cases where a
 122 large amount of computation is done after printing part of a line on an
 123 output terminal, it is necessary to
 124 .BR fflush (3)
 125 the standard output before going off and computing so that the output will
 126 appear.
 127 .PP
 128 The
 129 .I stdio
 130 library is a part of the library
 131 .B libc
 132 and routines are automatically loaded as needed by the compilers
 133 .BR cc (1)
 134 and
 135 .BR pc (1).
 136 The
 137 SYNOPSIS
 138 sections of the following manual pages indicate which include files are to
 139 be used, what the compiler declaration for the function looks like and
 140 which external variables are of interest.
 141 .PP
 142 The following are defined as macros; these names may not be reused without
 143 first removing their current definitions with
 144 .BR #undef :
 145 .BR BUFSIZ ,
 146 .BR EOF ,
 147 .BR FILENAME_MAX ,
 148 .BR FOPEN_MAX ,
 149 .BR L_cuserid ,
 150 .BR L_ctermid ,
 151 .BR L_tmpnam ,
 152 .BR NULL ,
 153 .BR SEEK_END ,
 154 .BR SEEK_SET ,
 155 .BR SEEK_CUR ,
 156 .BR TMP_MAX ,
 157 .BR clearerr ,
 158 .BR feof ,
 159 .BR ferror ,
 160 .BR fileno ,
 161 .\" Not on Linux: .BR fropen ,
 162 .\" Not on Linux: .BR fwopen ,
 163 .BR getc ,
 164 .BR getchar ,
 165 .BR putc ,
 166 .BR putchar ,
 167 .BR stderr ,
 168 .BR stdin ,
 169 .BR stdout .
 170 Function versions of the macro functions
 171 .BR feof ,
 172 .BR ferror ,
 173 .BR clearerr ,
 174 .BR fileno ,
 175 .BR getc ,
 176 .BR getchar ,
 177 .BR putc ,
 178 and
 179 .B putchar
 180 exist and will be used if the macros definitions are explicitly removed.
 181 .SS "List of functions"
 182 .TS
 183 ;
 184 lb lb
 185 lb l.
 186 Function        Description
 187 _
 188 clearerr        check and reset stream status
 189 fclose  close a stream
 190 fdopen  stream open functions
 191 feof    check and reset stream status
 192 ferror  check and reset stream status
 193 fflush  flush a stream
 194 fgetc   get next character or word from input stream
 195 fgetpos reposition a stream
 196 fgets   get a line from a stream
 197 fileno  return the integer descriptor of the argument stream
 198 fopen   stream open functions
 199 fprintf formatted output conversion
 200 fpurge  flush a stream
 201 fputc   output a character or word to a stream
 202 fputs   output a line to a stream
 203 fread   binary stream input/output
 204 freopen stream open functions
 205 fscanf  input format conversion
 206 fseek   reposition a stream
 207 fsetpos reposition a stream
 208 ftell   reposition a stream
 209 fwrite  binary stream input/output
 210 getc    get next character or word from input stream
 211 getchar get next character or word from input stream
 212 gets    get a line from a stream
 213 getw    get next character or word from input stream
 214 mktemp  make temporary filename (unique)
 215 perror  system error messages
 216 printf  formatted output conversion
 217 putc    output a character or word to a stream
 218 putchar output a character or word to a stream
 219 puts    output a line to a stream
 220 putw    output a character or word to a stream
 221 remove  remove directory entry
 222 rewind  reposition a stream
 223 scanf   input format conversion
 224 setbuf  stream buffering operations
 225 setbuffer       stream buffering operations
 226 setlinebuf      stream buffering operations
 227 setvbuf stream buffering operations
 228 sprintf formatted output conversion
 229 sscanf  input format conversion
 230 strerror        system error messages
 231 sys_errlist     system error messages
 232 sys_nerr        system error messages
 233 tempnam temporary file routines
 234 tmpfile temporary file routines
 235 tmpnam  temporary file routines
 236 ungetc  un-get character from input stream
 237 vfprintf        formatted output conversion
 238 vfscanf input format conversion
 239 vprintf formatted output conversion
 240 vscanf  input format conversion
 241 vsprintf        formatted output conversion
 242 vsscanf input format conversion
 243 .TE
 244 .SH CONFORMING TO
 245 The
 246 .I stdio
 247 library conforms to C89.
 248 .SH SEE ALSO
 249 .BR close (2),
 250 .BR open (2),
 251 .BR read (2),
 252 .BR write (2),
 253 .BR stdout (3),
 254 .BR unlocked_stdio (3)