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