lib/libc/stdio/stdio.3

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