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