original/man3/stdio.3

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