stdio/FreeBSD/stdio.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)stdio.3     8.7 (Berkeley) 4/19/94
  29 .\" $FreeBSD: src/lib/libc/stdio/stdio.3,v 1.30 2009/03/04 03:38:51 das Exp $
  30 .\"
  31 .Dd March 3, 2009
  32 .Dt STDIO 3
  33 .Os
  34 .Sh NAME
  35 .Nm stdio
  36 .Nd standard input/output library functions
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdio.h
  41 .Vt FILE *stdin ;
  42 .Vt FILE *stdout ;
  43 .Vt FILE *stderr ;
  44 .Pp
  45 Note:
  46 The current implementation does not allow these variables
  47 to be evaluated at C compile/link time.
  48 That is, a runtime calculation must be performed, such as:
  49 .Bd -literal -offset indent
  50 #include <stdio.h>
  51
  52 static FILE *var;
  53
  54 int main() {
  55     var = stdout;
  56 }
  57 .Ed
  58 .Sh DESCRIPTION
  59 The standard
  60 .Tn I/O
  61 library provides a simple and efficient buffered stream
  62 .Tn I/O
  63 interface.
  64 Input and output is mapped into logical data streams
  65 and the physical
  66 .Tn I/O
  67 characteristics are concealed.
  68 The functions and macros are listed
  69 below; more information is available from the individual man pages.
  70 .Pp
  71 A stream is associated with an external file (which may be a physical
  72 device) by
  73 .Em opening
  74 a file, which may involve creating a new file.
  75 Creating an
  76 existing file causes its former contents to be discarded.
  77 If a file can support positioning requests (such as a disk file, as opposed
  78 to a terminal) then a
  79 .Em file position indicator
  80 associated with the stream is positioned at the start of the file (byte
  81 zero), unless the file is opened with append mode.
  82 If append mode
  83 is used, the position indicator will be placed at the end-of-file.
  84 The position indicator is maintained by subsequent reads, writes
  85 and positioning requests.
  86 All input occurs as if the characters
  87 were read by successive calls to the
  88 .Xr fgetc 3
  89 function; all output takes place as if all characters were
  90 written by successive calls to the
  91 .Xr fputc 3
  92 function.
  93 .Pp
  94 A file is disassociated from a stream by
  95 .Em closing
  96 the file.
  97 Output streams are flushed (any unwritten buffer contents are transferred
  98 to the host environment) before the stream is disassociated from the file.
  99 The value of a pointer to a
 100 .Dv FILE
 101 object is indeterminate (garbage) after a file is closed.
 102 .Pp
 103 A file may be subsequently reopened, by the same or another program
 104 execution, and its contents reclaimed or modified (if it can be repositioned
 105 at the start).
 106 If the main function returns to its original caller, or
 107 the
 108 .Xr exit 3
 109 function is called, all open files are closed (hence all output
 110 streams are flushed) before program termination.
 111 Other methods
 112 of program termination may not close files properly and hence
 113 buffered output may be lost.
 114 In particular,
 115 .Xr _exit 2
 116 does not flush stdio files.
 117 Neither does an exit due to a signal.
 118 Buffers are flushed by
 119 .Xr abort 3
 120 as required by POSIX, although previous implementations did not.
 121 .Pp
 122 This implementation makes no distinction between
 123 .Dq text
 124 and
 125 .Dq binary
 126 streams.
 127 In effect, all streams are binary.
 128 No translation is performed and no extra padding appears on any stream.
 129 .Pp
 130 At program startup, three streams are predefined and need not be
 131 opened explicitly:
 132 .Bl -bullet -compact -offset indent
 133 .It
 134 .Em standard input
 135 (for reading conventional input),
 136 .It
 137 .Em standard output
 138 (for writing conventional output), and
 139 .It
 140 .Em standard error
 141 (for writing diagnostic output).
 142 .El
 143 These streams are abbreviated
 144 .Dv stdin , stdout
 145 and
 146 .Dv stderr .
 147 Initially, the standard error stream
 148 is unbuffered; the standard input and output streams are
 149 fully buffered if and only if the streams do not refer to
 150 an interactive or
 151 .Dq terminal
 152 device, as determined by the
 153 .Xr isatty 3
 154 function.
 155 In fact,
 156 .Em all
 157 freshly-opened streams that refer to terminal devices
 158 default to line buffering, and
 159 pending output to such streams is written automatically
 160 whenever such an input stream is read.
 161 Note that this applies only to
 162 .Dq "true reads" ;
 163 if the read request can be satisfied by existing buffered data,
 164 no automatic flush will occur.
 165 In these cases,
 166 or when a large amount of computation is done after printing
 167 part of a line on an output terminal, it is necessary to
 168 .Xr fflush 3
 169 the standard output before going off and computing so that the output
 170 will appear.
 171 Alternatively, these defaults may be modified via the
 172 .Xr setvbuf 3
 173 function.
 174 .Pp
 175 The
 176 .Nm
 177 library is a part of the library
 178 .Nm libc
 179 and routines are automatically loaded as needed by the C compiler.
 180 The
 181 .Tn SYNOPSIS
 182 sections of the following manual pages indicate which include files
 183 are to be used, what the compiler declaration for the function
 184 looks like and which external variables are of interest.
 185 .Pp
 186 The following are defined as macros;
 187 these names may not be re-used
 188 without first removing their current definitions with
 189 .Ic #undef :
 190 .Dv BUFSIZ ,
 191 .Dv EOF ,
 192 .Dv FILENAME_MAX ,
 193 .Dv FOPEN_MAX ,
 194 .Dv L_ctermid ,
 195 .Dv L_cuserid ,
 196 .Dv L_tmpnam ,
 197 .Dv NULL ,
 198 .Dv P_tmpdir ,
 199 .Dv SEEK_CUR ,
 200 .Dv SEEK_END ,
 201 .Dv SEEK_SET ,
 202 .Dv TMP_MAX ,
 203 .Dv clearerr ,
 204 .Dv clearerr_unlocked ,
 205 .Dv feof ,
 206 .Dv feof_unlocked ,
 207 .Dv ferror ,
 208 .Dv ferror_unlocked ,
 209 .Dv fileno ,
 210 .Dv fileno_unlocked ,
 211 .Dv fropen ,
 212 .Dv fwopen ,
 213 .Dv getc ,
 214 .Dv getc_unlocked ,
 215 .Dv getchar ,
 216 .Dv getchar_unlocked ,
 217 .Dv putc ,
 218 .Dv putc_unlocked ,
 219 .Dv putchar ,
 220 .Dv putchar_unlocked ,
 221 .Dv stderr ,
 222 .Dv stdin
 223 and
 224 .Dv stdout .
 225 Function versions of the macro functions
 226 .Dv clearerr ,
 227 .Dv clearerr_unlocked ,
 228 .Dv feof ,
 229 .Dv feof_unlocked ,
 230 .Dv ferror ,
 231 .Dv ferror_unlocked ,
 232 .Dv fileno ,
 233 .Dv fileno_unlocked ,
 234 .Dv getc ,
 235 .Dv getc_unlocked ,
 236 .Dv getchar ,
 237 .Dv getchar_unlocked ,
 238 .Dv putc ,
 239 .Dv putc_unlocked ,
 240 .Dv putchar ,
 241 and
 242 .Dv putchar_unlocked
 243 exist and will be used if the macro
 244 definitions are explicitly removed.
 245 .Sh LEGACY SYNOPSIS
 246 The -D_NONSTD_SOURCE flag can be used
 247 to allow stdin, stdout, and/or stderr
 248 to be evaluated at compile/link time, as:
 249 .Bd -literal -offset indent
 250 #include <stdio.h>
 251
 252 static FILE *var = stdout;
 253 .Ed
 254 .Sh SEE ALSO
 255 .Xr close 2 ,
 256 .Xr open 2 ,
 257 .Xr read 2 ,
 258 .Xr write 2 ,
 259 .Xr compat 5
 260 .Sh STANDARDS
 261 The
 262 .Nm
 263 library conforms to
 264 .St -isoC-99 .
 265 .Sh LIST OF FUNCTIONS
 266 .Bl -column "Description"
 267 .It Sy "Function        Description"
 268 .It "asprintf   formatted output conversion"
 269 .It ""
 270 .It "clearerr   check and reset stream status"
 271 .It ""
 272 .It "fclose     close a stream"
 273 .It "fdopen     stream open functions"
 274 .It "feof       check and reset stream status"
 275 .It "ferror     check and reset stream status"
 276 .It "fflush     flush a stream"
 277 .It "fgetc      get next character or word from input stream"
 278 .It "fgetln     get a line from a stream"
 279 .It "fgetpos    reposition a stream"
 280 .It "fgets      get a line from a stream"
 281 .It "fgetwc     get next wide character from input stream"
 282 .It "fgetws     get a line of wide characters from a stream"
 283 .It "fileno     check and reset stream status"
 284 .It "fopen      stream open functions"
 285 .It "fprintf    formatted output conversion"
 286 .It "fpurge     flush a stream"
 287 .It "fputc      output a character or word to a stream"
 288 .It "fputs      output a line to a stream"
 289 .It "fputwc     output a wide character to a stream"
 290 .It "fputws     output a line of wide characters to a stream"
 291 .It "fread      binary stream input/output"
 292 .It "freopen    stream open functions"
 293 .It "fropen     open a stream"
 294 .It "fscanf     input format conversion"
 295 .It "fseek      reposition a stream"
 296 .It "fsetpos    reposition a stream"
 297 .It "ftell      reposition a stream"
 298 .It "funopen    open a stream"
 299 .It "fwide      set/get orientation of stream"
 300 .It "fwopen     open a stream"
 301 .It "fwprintf   formatted wide character output conversion"
 302 .It "fwrite     binary stream input/output"
 303 .It ""
 304 .It "getc       get next character or word from input stream"
 305 .It "getchar    get next character or word from input stream"
 306 .It "getdelim   get a line from a stream"
 307 .It "getline    get a line from a stream"
 308 .It "gets       get a line from a stream"
 309 .It "getw       get next character or word from input stream"
 310 .It "getwc      get next wide character from input stream"
 311 .It "getwchar   get next wide character from input stream"
 312 .It ""
 313 .It "mkdtemp    create unique temporary directory"
 314 .It "mkstemp    create unique temporary file"
 315 .It "mktemp     create unique temporary file"
 316 .It ""
 317 .It "perror     system error messages"
 318 .It "printf     formatted output conversion"
 319 .It "putc       output a character or word to a stream"
 320 .It "putchar    output a character or word to a stream"
 321 .It "puts       output a line to a stream"
 322 .It "putw       output a character or word to a stream"
 323 .It "putwc      output a wide character to a stream"
 324 .It "putwchar   output a wide character to a stream"
 325 .It ""
 326 .It "remove     remove directory entry"
 327 .It "rewind     reposition a stream"
 328 .It ""
 329 .It "scanf      input format conversion"
 330 .It "setbuf     stream buffering operations"
 331 .It "setbuffer  stream buffering operations"
 332 .It "setlinebuf stream buffering operations"
 333 .It "setvbuf    stream buffering operations"
 334 .It "snprintf   formatted output conversion"
 335 .It "sprintf    formatted output conversion"
 336 .It "sscanf     input format conversion"
 337 .It "strerror   system error messages"
 338 .It "swprintf   formatted wide character output conversion"
 339 .It "sys_errlist        system error messages"
 340 .It "sys_nerr   system error messages"
 341 .It ""
 342 .It "tempnam    temporary file routines"
 343 .It "tmpfile    temporary file routines"
 344 .It "tmpnam     temporary file routines"
 345 .It ""
 346 .It "ungetc     un-get character from input stream"
 347 .It "ungetwc    un-get wide character from input stream"
 348 .It ""
 349 .It "vasprintf  formatted output conversion"
 350 .It "vfprintf   formatted output conversion"
 351 .It "vfscanf    input format conversion"
 352 .It "vfwprintf  formatted wide character output conversion"
 353 .It "vprintf    formatted output conversion"
 354 .It "vscanf     input format conversion"
 355 .It "vsnprintf  formatted output conversion"
 356 .It "vsprintf   formatted output conversion"
 357 .It "vsscanf    input format conversion"
 358 .It "vswprintf  formatted wide character output conversion"
 359 .It "vwprintf   formatted wide character output conversion"
 360 .It ""
 361 .It "wprintf    formatted wide character output conversion"
 362 .El
 363 .Sh BUGS
 364 The standard buffered functions do not interact well with certain other
 365 library and system functions, especially
 366 .Xr vfork 2 .