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  2017-11-26 "" "Linux Programmer's Manual"
  40 .SH NAME
  41 stdio \- standard input/output library functions
  42 .SH SYNOPSIS
  43 .B #include <stdio.h>
  44 .PP
  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 ,
 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 .TS
 184 ;
 185 lb lb
 186 l l.
 187 Function        Description
 188 _
 189 \fBclearerr\fP(3)       check and reset stream status
 190 \fBfclose\fP(3) close a stream
 191 \fBfdopen\fP(3) stream open functions
 192 \fBfeof\fP(3)   check and reset stream status
 193 \fBferror\fP(3) check and reset stream status
 194 \fBfflush\fP(3) flush a stream
 195 \fBfgetc\fP(3)  get next character or word from input stream
 196 \fBfgetpos\fP(3)        reposition a stream
 197 \fBfgets\fP(3)  get a line from a stream
 198 \fBfileno\fP(3) return the integer descriptor of the argument stream
 199 \fBfopen\fP(3)  stream open functions
 200 \fBfprintf\fP(3)        formatted output conversion
 201 \fBfpurge\fP(3) flush a stream
 202 \fBfputc\fP(3)  output a character or word to a stream
 203 \fBfputs\fP(3)  output a line to a stream
 204 \fBfread\fP(3)  binary stream input/output
 205 \fBfreopen\fP(3)        stream open functions
 206 \fBfscanf\fP(3) input format conversion
 207 \fBfseek\fP(3)  reposition a stream
 208 \fBfsetpos\fP(3)        reposition a stream
 209 \fBftell\fP(3)  reposition a stream
 210 \fBfwrite\fP(3) binary stream input/output
 211 \fBgetc\fP(3)   get next character or word from input stream
 212 \fBgetchar\fP(3)        get next character or word from input stream
 213 \fBgets\fP(3)   get a line from a stream
 214 \fBgetw\fP(3)   get next character or word from input stream
 215 \fBmktemp\fP(3) make temporary filename (unique)
 216 \fBperror\fP(3) system error messages
 217 \fBprintf\fP(3) formatted output conversion
 218 \fBputc\fP(3)   output a character or word to a stream
 219 \fBputchar\fP(3)        output a character or word to a stream
 220 \fBputs\fP(3)   output a line to a stream
 221 \fBputw\fP(3)   output a character or word to a stream
 222 \fBremove\fP(3) remove directory entry
 223 \fBrewind\fP(3) reposition a stream
 224 \fBscanf\fP(3)  input format conversion
 225 \fBsetbuf\fP(3) stream buffering operations
 226 \fBsetbuffer\fP(3)      stream buffering operations
 227 \fBsetlinebuf\fP(3)     stream buffering operations
 228 \fBsetvbuf\fP(3)        stream buffering operations
 229 \fBsprintf\fP(3)        formatted output conversion
 230 \fBsscanf\fP(3) input format conversion
 231 \fBstrerror\fP(3)       system error messages
 232 \fBsys_errlist\fP(3)    system error messages
 233 \fBsys_nerr\fP(3)       system error messages
 234 \fBtempnam\fP(3)        temporary file routines
 235 \fBtmpfile\fP(3)        temporary file routines
 236 \fBtmpnam\fP(3) temporary file routines
 237 \fBungetc\fP(3) un-get character from input stream
 238 \fBvfprintf\fP(3)       formatted output conversion
 239 \fBvfscanf\fP(3)        input format conversion
 240 \fBvprintf\fP(3)        formatted output conversion
 241 \fBvscanf\fP(3) input format conversion
 242 \fBvsprintf\fP(3)       formatted output conversion
 243 \fBvsscanf\fP(3)        input format conversion
 244 .TE
 245 .SH CONFORMING TO
 246 The
 247 .I stdio
 248 library conforms to C89.
 249 .SH SEE ALSO
 250 .BR close (2),
 251 .BR open (2),
 252 .BR read (2),
 253 .BR write (2),
 254 .BR stdout (3),
 255 .BR unlocked_stdio (3)