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 .B FILE *stdin;
  44 .br
  45 .B FILE *stdout;
  46 .br
  47 .B FILE *stderr;
  48 .SH DESCRIPTION
  49 The standard I/O library provides a simple and efficient buffered stream
  50 I/O interface.  Input and output is mapped into logical data streams and the
  51 physical I/O characteristics are concealed. The functions and macros are
  52 listed below; more information is available from the individual man pages.
  53 .PP
  54 A stream is associated with an external file (which may be a physical
  55 device) by
  56 .I opening
  57 a file, which may involve creating a new file. Creating an existing file
  58 causes its former contents to be discarded.  If a file can support
  59 positioning requests (such as a disk file, as opposed to a terminal) then a
  60 .I file position indicator
  61 associated with the stream is positioned at the start of the file (byte
  62 zero), unless the file is opened with append mode. If append mode is used,
  63 it is unspecified whether the position indicator will be placed at the
  64 start or the end of the file.  The position indicator is maintained by
  65 subsequent reads, writes and positioning requests. All input occurs
  66 as if the characters were read by successive calls to the
  67 .BR fgetc (3)
  68 function; all output takes place as if all characters were written by
  69 successive calls to the
  70 .BR fputc (3)
  71 function.
  72 .PP
  73 A file is disassociated from a stream by
  74 .I closing
  75 the file.  Output streams are flushed (any unwritten buffer contents are
  76 transferred to the host environment) before the stream is disassociated from
  77 the file.  The value of a pointer to a
  78 .B FILE
  79 object is indeterminate after a file is closed (garbage).
  80 .PP
  81 A file may be subsequently reopened, by the same or another program
  82 execution, and its contents reclaimed or modified (if it can be
  83 repositioned at the start).  If the main function returns to its original
  84 caller, or the
  85 .BR exit (3)
  86 function is called, all open files are closed (hence all output streams are
  87 flushed) before program termination.  Other methods of program termination,
  88 such as
  89 .BR abort (3)
  90 do not bother about closing files properly.
  91 .PP
  92 At program startup, three text streams are predefined and need not be
  93 opened explicitly \(em
  94 .I standard input
  95 (for reading conventional input), \(em
  96 .I standard output
  97 (for writing conventional input), and
  98 .I standard error
  99 (for writing diagnostic output).  These streams are abbreviated
 100 .IR stdin , stdout
 101 and
 102 .IR stderr .
 103 When opened, the standard error stream is not fully buffered; the standard
 104 input and output streams are fully buffered if and only if the streams do
 105 not to refer to an interactive device.
 106 .PP
 107 Output streams that refer to terminal devices are always line buffered by
 108 default; pending output to such streams is written automatically whenever
 109 an input stream that refers to a terminal device is read.  In cases where a
 110 large amount of computation is done after printing part of a line on an
 111 output terminal, it is necessary to
 112 .BR fflush (3)
 113 the standard output before going off and computing so that the output will
 114 appear.
 115 .PP
 116 The
 117 .B stdio
 118 library is a part of the library
 119 .B libc
 120 and routines are automatically loaded as needed by the compilers
 121 .BR cc (1)
 122 and
 123 .BR pc (1).
 124 The
 125 .B SYNOPSIS
 126 sections of the following manual pages indicate which include files are to
 127 be used, what the compiler declaration for the function looks like and
 128 which external variables are of interest.
 129 .PP
 130 The following are defined as macros; these names may not be re-used without
 131 first removing their current definitions with
 132 .BR #undef :
 133 .BR BUFSIZ ,
 134 .BR EOF ,
 135 .BR FILENAME_MAX ,
 136 .BR FOPEN_MAX ,
 137 .BR L_cuserid ,
 138 .BR L_ctermid ,
 139 .BR L_tmpnam ,
 140 .BR NULL ,
 141 .BR SEEK_END ,
 142 .BR SEEK_SET ,
 143 .BR SEE_CUR ,
 144 .BR TMP_MAX ,
 145 .BR clearerr ,
 146 .BR feof ,
 147 .BR ferror ,
 148 .BR fileno ,
 149 .\" Not on Linux: .BR fropen ,
 150 .\" Not on Linux: .BR fwopen ,
 151 .BR getc ,
 152 .BR getchar ,
 153 .BR putc ,
 154 .BR putchar ,
 155 .BR stderr ,
 156 .BR stdin ,
 157 .BR stdout .
 158 Function versions of the macro functions
 159 .BR feof ,
 160 .BR ferror ,
 161 .BR clearerr ,
 162 .BR fileno ,
 163 .BR getc ,
 164 .BR getchar ,
 165 .BR putc ,
 166 and
 167 .B putchar
 168 exist and will be used if the macros definitions are explicitly removed.
 169 .SH "LIST OF FUNCTIONS"
 170 .TP 10n
 171 .B Function
 172 .B Description
 173 .TP
 174 .B clearerr
 175 check and reset stream status
 176 .TP
 177 .B fclose
 178 close a stream
 179 .TP
 180 .B fdopen
 181 stream open functions
 182 .TP
 183 .B feof
 184 check and reset stream status
 185 .TP
 186 .B ferror
 187 check and reset stream status
 188 .TP
 189 .B fflush
 190 flush a stream
 191 .TP
 192 .B fgetc
 193 get next character or word from input stream
 194 .\" .TP
 195 .\" .B fgetline
 196 .\" get a line from a stream (BSD only; renamed to fgetln())
 197 .TP
 198 .B fgetpos
 199 reposition a stream
 200 .TP
 201 .B fgets
 202 get a line from a stream
 203 .TP
 204 .B fileno
 205 return the integer descriptor of the argument stream
 206 .TP
 207 .B fopen
 208 stream open functions
 209 .TP
 210 .B fprintf
 211 formatted output conversion
 212 .TP
 213 .B fpurge
 214 flush a stream
 215 .TP
 216 .B fputc
 217 output a character or word to a stream
 218 .TP
 219 .B fputs
 220 output a line to a stream
 221 .TP
 222 .B fread
 223 binary stream input/output
 224 .TP
 225 .B freopen
 226 stream open functions
 227 .\" Not on Linux:
 228 .\" .TP
 229 .\" .B fropen
 230 .\" open a stream
 231 .TP
 232 .B fscanf
 233 input format conversion
 234 .TP
 235 .B fseek
 236 reposition a stream
 237 .TP
 238 .B fsetpos
 239 reposition a stream
 240 .TP
 241 .B ftell
 242 reposition a stream
 243 .TP
 244 .B fwrite
 245 binary stream input/output
 246 .TP
 247 .B getc
 248 get next character or word from input stream
 249 .TP
 250 .B getchar
 251 get next character or word from input stream
 252 .TP
 253 .B gets
 254 get a line from a stream
 255 .TP
 256 .B getw
 257 get next character or word from input stream
 258 .TP
 259 .B mktemp
 260 make temporary file name (unique)
 261 .TP
 262 .B perror
 263 system error messages
 264 .TP
 265 .B printf
 266 formatted output conversion
 267 .TP
 268 .B putc
 269 output a character or word to a stream
 270 .TP
 271 .B putchar
 272 output a character or word to a stream
 273 .TP
 274 .B puts
 275 output a line to a stream
 276 .TP
 277 .B putw
 278 output a character or word to a stream
 279 .TP
 280 .B remove
 281 remove directory entry
 282 .TP
 283 .B rewind
 284 reposition a stream
 285 .TP
 286 .B scanf
 287 input format conversion
 288 .TP
 289 .B setbuf
 290 stream buffering operations
 291 .TP
 292 .B setbuffer
 293 stream buffering operations
 294 .TP
 295 .B setlinebuf
 296 stream buffering operations
 297 .TP
 298 .B setvbuf
 299 stream buffering operations
 300 .TP
 301 .B sprintf
 302 formatted output conversion
 303 .TP
 304 .B sscanf
 305 input format conversion
 306 .TP
 307 .B strerror
 308 system error messages
 309 .TP
 310 .B sys_errlist
 311 system error messages
 312 .TP
 313 .B sys_nerr
 314 system error messages
 315 .TP
 316 .B tempnam
 317 temporary file routines
 318 .TP
 319 .B tmpfile
 320 temporary file routines
 321 .TP
 322 .B tmpnam
 323 temporary file routines
 324 .TP
 325 .B ungetc
 326 un-get character from input stream
 327 .TP
 328 .B vfprintf
 329 formatted output conversion
 330 .TP
 331 .B vfscanf
 332 input format conversion
 333 .TP
 334 .B vprintf
 335 formatted output conversion
 336 .TP
 337 .B vscanf
 338 input format conversion
 339 .TP
 340 .B vsprintf
 341 formatted output conversion
 342 .TP
 343 .B vsscanf
 344 input format conversion
 345 .SH "CONFORMING TO"
 346 The
 347 .B stdio
 348 library conforms to ANSI X3.159-1989 (``ANSI C'').
 349 .SH "SEE ALSO"
 350 .BR close (2),
 351 .BR open (2),
 352 .BR read (2),
 353 .BR write (2),
 354 .BR stdout (3)