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