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.
  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 \(em
 104 .I standard input
 105 (for reading conventional input), \(em
 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 to 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 .B 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 .B 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 re-used 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 SEE_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 .TP 10n
 183 .B Function
 184 .B Description
 185 .TP
 186 .B clearerr
 187 check and reset stream status
 188 .TP
 189 .B fclose
 190 close a stream
 191 .TP
 192 .B fdopen
 193 stream open functions
 194 .TP
 195 .B feof
 196 check and reset stream status
 197 .TP
 198 .B ferror
 199 check and reset stream status
 200 .TP
 201 .B fflush
 202 flush a stream
 203 .TP
 204 .B fgetc
 205 get next character or word from input stream
 206 .\" .TP
 207 .\" .B fgetline
 208 .\" get a line from a stream (BSD only; renamed to fgetln())
 209 .TP
 210 .B fgetpos
 211 reposition a stream
 212 .TP
 213 .B fgets
 214 get a line from a stream
 215 .TP
 216 .B fileno
 217 return the integer descriptor of the argument stream
 218 .TP
 219 .B fopen
 220 stream open functions
 221 .TP
 222 .B fprintf
 223 formatted output conversion
 224 .TP
 225 .B fpurge
 226 flush a stream
 227 .TP
 228 .B fputc
 229 output a character or word to a stream
 230 .TP
 231 .B fputs
 232 output a line to a stream
 233 .TP
 234 .B fread
 235 binary stream input/output
 236 .TP
 237 .B freopen
 238 stream open functions
 239 .\" Not on Linux:
 240 .\" .TP
 241 .\" .B fropen
 242 .\" open a stream
 243 .TP
 244 .B fscanf
 245 input format conversion
 246 .TP
 247 .B fseek
 248 reposition a stream
 249 .TP
 250 .B fsetpos
 251 reposition a stream
 252 .TP
 253 .B ftell
 254 reposition a stream
 255 .TP
 256 .B fwrite
 257 binary stream input/output
 258 .TP
 259 .B getc
 260 get next character or word from input stream
 261 .TP
 262 .B getchar
 263 get next character or word from input stream
 264 .TP
 265 .B gets
 266 get a line from a stream
 267 .TP
 268 .B getw
 269 get next character or word from input stream
 270 .TP
 271 .B mktemp
 272 make temporary filename (unique)
 273 .TP
 274 .B perror
 275 system error messages
 276 .TP
 277 .B printf
 278 formatted output conversion
 279 .TP
 280 .B putc
 281 output a character or word to a stream
 282 .TP
 283 .B putchar
 284 output a character or word to a stream
 285 .TP
 286 .B puts
 287 output a line to a stream
 288 .TP
 289 .B putw
 290 output a character or word to a stream
 291 .TP
 292 .B remove
 293 remove directory entry
 294 .TP
 295 .B rewind
 296 reposition a stream
 297 .TP
 298 .B scanf
 299 input format conversion
 300 .TP
 301 .B setbuf
 302 stream buffering operations
 303 .TP
 304 .B setbuffer
 305 stream buffering operations
 306 .TP
 307 .B setlinebuf
 308 stream buffering operations
 309 .TP
 310 .B setvbuf
 311 stream buffering operations
 312 .TP
 313 .B sprintf
 314 formatted output conversion
 315 .TP
 316 .B sscanf
 317 input format conversion
 318 .TP
 319 .B strerror
 320 system error messages
 321 .TP
 322 .B sys_errlist
 323 system error messages
 324 .TP
 325 .B sys_nerr
 326 system error messages
 327 .TP
 328 .B tempnam
 329 temporary file routines
 330 .TP
 331 .B tmpfile
 332 temporary file routines
 333 .TP
 334 .B tmpnam
 335 temporary file routines
 336 .TP
 337 .B ungetc
 338 un-get character from input stream
 339 .TP
 340 .B vfprintf
 341 formatted output conversion
 342 .TP
 343 .B vfscanf
 344 input format conversion
 345 .TP
 346 .B vprintf
 347 formatted output conversion
 348 .TP
 349 .B vscanf
 350 input format conversion
 351 .TP
 352 .B vsprintf
 353 formatted output conversion
 354 .TP
 355 .B vsscanf
 356 input format conversion
 357 .SH "CONFORMING TO"
 358 The
 359 .B stdio
 360 library conforms to C89.
 361 .SH "SEE ALSO"
 362 .BR close (2),
 363 .BR open (2),
 364 .BR read (2),
 365 .BR write (2),
 366 .BR stdout (3),
 367 .BR unlocked_stdio (3)