man3/stdio.3

   1 .\" Copyright (c) 1990, 1991 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     @(#)stdio.3     6.5 (Berkeley) 5/6/91
   7 .\"
   8 .\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu
   9 .\" Modified, 2001-12-26, aeb
  10 .\"
  11 .TH stdio 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 stdio \- standard input/output library functions
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <stdio.h>
  20 .PP
  21 .BI "FILE *" stdin ;
  22 .BI "FILE *" stdout ;
  23 .BI "FILE *" stderr ;
  24 .fi
  25 .SH DESCRIPTION
  26 The standard I/O library provides a simple and efficient buffered stream
  27 I/O interface.
  28 Input and output is mapped into logical data streams and the
  29 physical I/O characteristics are concealed.
  30 The functions and macros are
  31 listed below; more information is available from the individual man pages.
  32 .PP
  33 A stream is associated with an external file (which may be a physical
  34 device) by
  35 .I opening
  36 a file, which may involve creating a new file.
  37 Creating an existing file
  38 causes its former contents to be discarded.
  39 If a file can support positioning requests (such as a disk file,
  40 as opposed to a terminal), then a
  41 .I file position indicator
  42 associated with the stream is positioned at the start of the file (byte
  43 zero), unless the file is opened with append mode.
  44 If append mode is used,
  45 it is unspecified whether the position indicator will be placed at the
  46 start or the end of the file.
  47 The position indicator is maintained by
  48 subsequent reads, writes, and positioning requests.
  49 All input occurs as if the characters were read by successive calls to the
  50 .BR fgetc (3)
  51 function; all output takes place as if all characters were written by
  52 successive calls to the
  53 .BR fputc (3)
  54 function.
  55 .PP
  56 A file is disassociated from a stream by
  57 .I closing
  58 the file.
  59 Output streams are flushed (any unwritten buffer contents are
  60 transferred to the host environment) before the stream is disassociated from
  61 the file.
  62 The value of a pointer to a
  63 .I FILE
  64 object is indeterminate after a file is closed (garbage).
  65 .PP
  66 A file may be subsequently reopened, by the same or another program
  67 execution, and its contents reclaimed or modified (if it can be
  68 repositioned at the start).
  69 If the main function returns to its original
  70 caller, or the
  71 .BR exit (3)
  72 function is called, all open files are closed (hence all output streams are
  73 flushed) before program termination.
  74 Other methods of program termination,
  75 such as
  76 .BR abort (3)
  77 do not bother about closing files properly.
  78 .PP
  79 At program startup, three text streams are predefined and need not be
  80 opened explicitly:
  81 .I standard input
  82 (for reading conventional input),
  83 .I standard output
  84 (for writing conventional output), and
  85 .I standard error
  86 (for writing diagnostic output).
  87 These streams are abbreviated
  88 .IR stdin ,
  89 .IR stdout ,
  90 and
  91 .IR stderr .
  92 When opened, the standard error stream is not fully buffered; the standard
  93 input and output streams are fully buffered if and only if the streams do
  94 not refer to an interactive device.
  95 .PP
  96 Output streams that refer to terminal devices are always line buffered by
  97 default; pending output to such streams is written automatically whenever
  98 an input stream that refers to a terminal device is read.
  99 In cases where a
 100 large amount of computation is done after printing part of a line on an
 101 output terminal, it is necessary to
 102 .BR fflush (3)
 103 the standard output before going off and computing so that the output will
 104 appear.
 105 .PP
 106 The
 107 .I stdio
 108 library is a part of the library
 109 .B libc
 110 and routines are automatically loaded as needed by
 111 .BR cc (1).
 112 The
 113 SYNOPSIS
 114 sections of the following manual pages indicate which include files are to
 115 be used, what the compiler declaration for the function looks like and
 116 which external variables are of interest.
 117 .PP
 118 The following are defined as macros; these names may not be reused without
 119 first removing their current definitions with
 120 .BR #undef :
 121 .BR BUFSIZ ,
 122 .BR EOF ,
 123 .BR FILENAME_MAX ,
 124 .BR FOPEN_MAX ,
 125 .BR L_cuserid ,
 126 .BR L_ctermid ,
 127 .BR L_tmpnam ,
 128 .BR NULL ,
 129 .BR SEEK_END ,
 130 .BR SEEK_SET ,
 131 .BR SEEK_CUR ,
 132 .BR TMP_MAX ,
 133 .BR clearerr ,
 134 .BR feof ,
 135 .BR ferror ,
 136 .BR fileno ,
 137 .\" Not on Linux: .BR fropen ,
 138 .\" Not on Linux: .BR fwopen ,
 139 .BR getc ,
 140 .BR getchar ,
 141 .BR putc ,
 142 .BR putchar ,
 143 .BR stderr ,
 144 .BR stdin ,
 145 .BR stdout .
 146 Function versions of the macro functions
 147 .BR feof ,
 148 .BR ferror ,
 149 .BR clearerr ,
 150 .BR fileno ,
 151 .BR getc ,
 152 .BR getchar ,
 153 .BR putc ,
 154 and
 155 .B putchar
 156 exist and will be used if the macros definitions are explicitly removed.
 157 .SS List of functions
 158 .nh
 159 .ad l
 160 .TS
 161 ;
 162 lb lbx
 163 l l.
 164 Function        Description
 165 _
 166 \fBclearerr\fP(3)       T{
 167 check and reset stream status
 168 T}
 169 \fBfclose\fP(3) T{
 170 close a stream
 171 T}
 172 \fBfdopen\fP(3) T{
 173 stream open functions
 174 T}
 175 \fBfeof\fP(3)   T{
 176 check and reset stream status
 177 T}
 178 \fBferror\fP(3) T{
 179 check and reset stream status
 180 T}
 181 \fBfflush\fP(3) T{
 182 flush a stream
 183 T}
 184 \fBfgetc\fP(3)  T{
 185 get next character or word from input stream
 186 T}
 187 \fBfgetpos\fP(3)        T{
 188 reposition a stream
 189 T}
 190 \fBfgets\fP(3)  T{
 191 get a line from a stream
 192 T}
 193 \fBfileno\fP(3) T{
 194 return the integer descriptor of the argument stream
 195 T}
 196 \fBfopen\fP(3)  T{
 197 stream open functions
 198 T}
 199 \fBfprintf\fP(3)        T{
 200 formatted output conversion
 201 T}
 202 \fBfpurge\fP(3) T{
 203 flush a stream
 204 T}
 205 \fBfputc\fP(3)  T{
 206 output a character or word to a stream
 207 T}
 208 \fBfputs\fP(3)  T{
 209 output a line to a stream
 210 T}
 211 \fBfread\fP(3)  T{
 212 binary stream input/output
 213 T}
 214 \fBfreopen\fP(3)        T{
 215 stream open functions
 216 T}
 217 \fBfscanf\fP(3) T{
 218 input format conversion
 219 T}
 220 \fBfseek\fP(3)  T{
 221 reposition a stream
 222 T}
 223 \fBfsetpos\fP(3)        T{
 224 reposition a stream
 225 T}
 226 \fBftell\fP(3)  T{
 227 reposition a stream
 228 T}
 229 \fBfwrite\fP(3) T{
 230 binary stream input/output
 231 T}
 232 \fBgetc\fP(3)   T{
 233 get next character or word from input stream
 234 T}
 235 \fBgetchar\fP(3)        T{
 236 get next character or word from input stream
 237 T}
 238 \fBgets\fP(3)   T{
 239 get a line from a stream
 240 T}
 241 \fBgetw\fP(3)   T{
 242 get next character or word from input stream
 243 T}
 244 \fBmktemp\fP(3) T{
 245 make temporary filename (unique)
 246 T}
 247 \fBperror\fP(3) T{
 248 system error messages
 249 T}
 250 \fBprintf\fP(3) T{
 251 formatted output conversion
 252 T}
 253 \fBputc\fP(3)   T{
 254 output a character or word to a stream
 255 T}
 256 \fBputchar\fP(3)        T{
 257 output a character or word to a stream
 258 T}
 259 \fBputs\fP(3)   T{
 260 output a line to a stream
 261 T}
 262 \fBputw\fP(3)   T{
 263 output a character or word to a stream
 264 T}
 265 \fBremove\fP(3) T{
 266 remove directory entry
 267 T}
 268 \fBrewind\fP(3) T{
 269 reposition a stream
 270 T}
 271 \fBscanf\fP(3)  T{
 272 input format conversion
 273 T}
 274 \fBsetbuf\fP(3) T{
 275 stream buffering operations
 276 T}
 277 \fBsetbuffer\fP(3)      T{
 278 stream buffering operations
 279 T}
 280 \fBsetlinebuf\fP(3)     T{
 281 stream buffering operations
 282 T}
 283 \fBsetvbuf\fP(3)        T{
 284 stream buffering operations
 285 T}
 286 \fBsprintf\fP(3)        T{
 287 formatted output conversion
 288 T}
 289 \fBsscanf\fP(3) T{
 290 input format conversion
 291 T}
 292 \fBstrerror\fP(3)       T{
 293 system error messages
 294 T}
 295 \fBsys_errlist\fP(3)    T{
 296 system error messages
 297 T}
 298 \fBsys_nerr\fP(3)       T{
 299 system error messages
 300 T}
 301 \fBtempnam\fP(3)        T{
 302 temporary file routines
 303 T}
 304 \fBtmpfile\fP(3)        T{
 305 temporary file routines
 306 T}
 307 \fBtmpnam\fP(3) T{
 308 temporary file routines
 309 T}
 310 \fBungetc\fP(3) T{
 311 un-get character from input stream
 312 T}
 313 \fBvfprintf\fP(3)       T{
 314 formatted output conversion
 315 T}
 316 \fBvfscanf\fP(3)        T{
 317 input format conversion
 318 T}
 319 \fBvprintf\fP(3)        T{
 320 formatted output conversion
 321 T}
 322 \fBvscanf\fP(3) T{
 323 input format conversion
 324 T}
 325 \fBvsprintf\fP(3)       T{
 326 formatted output conversion
 327 T}
 328 \fBvsscanf\fP(3)        T{
 329 input format conversion
 330 T}
 331 .TE
 332 .ad
 333 .hy
 334 .SH STANDARDS
 335 The
 336 .I stdio
 337 library conforms to C89.
 338 .SH SEE ALSO
 339 .BR close (2),
 340 .BR open (2),
 341 .BR read (2),
 342 .BR write (2),
 343 .BR stdout (3),
 344 .BR unlocked_stdio (3)