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  2021-03-22 "" "Linux Programmer's Manual"
  40 .SH NAME
  41 stdio \- standard input/output library functions
  42 .SH SYNOPSIS
  43 .nf
  44 .B #include <stdio.h>
  45 .PP
  46 .BI "FILE *" stdin ;
  47 .BI "FILE *" stdout ;
  48 .BI "FILE *" stderr ;
  49 .fi
  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 ,
 114 .IR stdout ,
 115 and
 116 .IR stderr .
 117 When opened, the standard error stream is not fully buffered; the standard
 118 input and output streams are fully buffered if and only if the streams do
 119 not refer to an interactive device.
 120 .PP
 121 Output streams that refer to terminal devices are always line buffered by
 122 default; pending output to such streams is written automatically whenever
 123 an input stream that refers to a terminal device is read.
 124 In cases where a
 125 large amount of computation is done after printing part of a line on an
 126 output terminal, it is necessary to
 127 .BR fflush (3)
 128 the standard output before going off and computing so that the output will
 129 appear.
 130 .PP
 131 The
 132 .I stdio
 133 library is a part of the library
 134 .B libc
 135 and routines are automatically loaded as needed by
 136 .BR cc (1).
 137 The
 138 SYNOPSIS
 139 sections of the following manual pages indicate which include files are to
 140 be used, what the compiler declaration for the function looks like and
 141 which external variables are of interest.
 142 .PP
 143 The following are defined as macros; these names may not be reused without
 144 first removing their current definitions with
 145 .BR #undef :
 146 .BR BUFSIZ ,
 147 .BR EOF ,
 148 .BR FILENAME_MAX ,
 149 .BR FOPEN_MAX ,
 150 .BR L_cuserid ,
 151 .BR L_ctermid ,
 152 .BR L_tmpnam ,
 153 .BR NULL ,
 154 .BR SEEK_END ,
 155 .BR SEEK_SET ,
 156 .BR SEEK_CUR ,
 157 .BR TMP_MAX ,
 158 .BR clearerr ,
 159 .BR feof ,
 160 .BR ferror ,
 161 .BR fileno ,
 162 .\" Not on Linux: .BR fropen ,
 163 .\" Not on Linux: .BR fwopen ,
 164 .BR getc ,
 165 .BR getchar ,
 166 .BR putc ,
 167 .BR putchar ,
 168 .BR stderr ,
 169 .BR stdin ,
 170 .BR stdout .
 171 Function versions of the macro functions
 172 .BR feof ,
 173 .BR ferror ,
 174 .BR clearerr ,
 175 .BR fileno ,
 176 .BR getc ,
 177 .BR getchar ,
 178 .BR putc ,
 179 and
 180 .B putchar
 181 exist and will be used if the macros definitions are explicitly removed.
 182 .SS List of functions
 183 .nh
 184 .ad l
 185 .TS
 186 ;
 187 lb lbx
 188 l l.
 189 Function        Description
 190 _
 191 \fBclearerr\fP(3)       T{
 192 check and reset stream status
 193 T}
 194 \fBfclose\fP(3) T{
 195 close a stream
 196 T}
 197 \fBfdopen\fP(3) T{
 198 stream open functions
 199 T}
 200 \fBfeof\fP(3)   T{
 201 check and reset stream status
 202 T}
 203 \fBferror\fP(3) T{
 204 check and reset stream status
 205 T}
 206 \fBfflush\fP(3) T{
 207 flush a stream
 208 T}
 209 \fBfgetc\fP(3)  T{
 210 get next character or word from input stream
 211 T}
 212 \fBfgetpos\fP(3)        T{
 213 reposition a stream
 214 T}
 215 \fBfgets\fP(3)  T{
 216 get a line from a stream
 217 T}
 218 \fBfileno\fP(3) T{
 219 return the integer descriptor of the argument stream
 220 T}
 221 \fBfopen\fP(3)  T{
 222 stream open functions
 223 T}
 224 \fBfprintf\fP(3)        T{
 225 formatted output conversion
 226 T}
 227 \fBfpurge\fP(3) T{
 228 flush a stream
 229 T}
 230 \fBfputc\fP(3)  T{
 231 output a character or word to a stream
 232 T}
 233 \fBfputs\fP(3)  T{
 234 output a line to a stream
 235 T}
 236 \fBfread\fP(3)  T{
 237 binary stream input/output
 238 T}
 239 \fBfreopen\fP(3)        T{
 240 stream open functions
 241 T}
 242 \fBfscanf\fP(3) T{
 243 input format conversion
 244 T}
 245 \fBfseek\fP(3)  T{
 246 reposition a stream
 247 T}
 248 \fBfsetpos\fP(3)        T{
 249 reposition a stream
 250 T}
 251 \fBftell\fP(3)  T{
 252 reposition a stream
 253 T}
 254 \fBfwrite\fP(3) T{
 255 binary stream input/output
 256 T}
 257 \fBgetc\fP(3)   T{
 258 get next character or word from input stream
 259 T}
 260 \fBgetchar\fP(3)        T{
 261 get next character or word from input stream
 262 T}
 263 \fBgets\fP(3)   T{
 264 get a line from a stream
 265 T}
 266 \fBgetw\fP(3)   T{
 267 get next character or word from input stream
 268 T}
 269 \fBmktemp\fP(3) T{
 270 make temporary filename (unique)
 271 T}
 272 \fBperror\fP(3) T{
 273 system error messages
 274 T}
 275 \fBprintf\fP(3) T{
 276 formatted output conversion
 277 T}
 278 \fBputc\fP(3)   T{
 279 output a character or word to a stream
 280 T}
 281 \fBputchar\fP(3)        T{
 282 output a character or word to a stream
 283 T}
 284 \fBputs\fP(3)   T{
 285 output a line to a stream
 286 T}
 287 \fBputw\fP(3)   T{
 288 output a character or word to a stream
 289 T}
 290 \fBremove\fP(3) T{
 291 remove directory entry
 292 T}
 293 \fBrewind\fP(3) T{
 294 reposition a stream
 295 T}
 296 \fBscanf\fP(3)  T{
 297 input format conversion
 298 T}
 299 \fBsetbuf\fP(3) T{
 300 stream buffering operations
 301 T}
 302 \fBsetbuffer\fP(3)      T{
 303 stream buffering operations
 304 T}
 305 \fBsetlinebuf\fP(3)     T{
 306 stream buffering operations
 307 T}
 308 \fBsetvbuf\fP(3)        T{
 309 stream buffering operations
 310 T}
 311 \fBsprintf\fP(3)        T{
 312 formatted output conversion
 313 T}
 314 \fBsscanf\fP(3) T{
 315 input format conversion
 316 T}
 317 \fBstrerror\fP(3)       T{
 318 system error messages
 319 T}
 320 \fBsys_errlist\fP(3)    T{
 321 system error messages
 322 T}
 323 \fBsys_nerr\fP(3)       T{
 324 system error messages
 325 T}
 326 \fBtempnam\fP(3)        T{
 327 temporary file routines
 328 T}
 329 \fBtmpfile\fP(3)        T{
 330 temporary file routines
 331 T}
 332 \fBtmpnam\fP(3) T{
 333 temporary file routines
 334 T}
 335 \fBungetc\fP(3) T{
 336 un-get character from input stream
 337 T}
 338 \fBvfprintf\fP(3)       T{
 339 formatted output conversion
 340 T}
 341 \fBvfscanf\fP(3)        T{
 342 input format conversion
 343 T}
 344 \fBvprintf\fP(3)        T{
 345 formatted output conversion
 346 T}
 347 \fBvscanf\fP(3) T{
 348 input format conversion
 349 T}
 350 \fBvsprintf\fP(3)       T{
 351 formatted output conversion
 352 T}
 353 \fBvsscanf\fP(3)        T{
 354 input format conversion
 355 T}
 356 .TE
 357 .ad
 358 .hy
 359 .SH CONFORMING TO
 360 The
 361 .I stdio
 362 library conforms to C89.
 363 .SH SEE ALSO
 364 .BR close (2),
 365 .BR open (2),
 366 .BR read (2),
 367 .BR write (2),
 368 .BR stdout (3),
 369 .BR unlocked_stdio (3)