1.\" $NetBSD: stdio.3,v 1.15 2002/10/01 17:24:08 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 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.Fd #include \*[Lt]stdio.h\*[Gt] 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 171The following are defined as macros; these names may not be re-used 172without first removing their current definitions with 173.Dv #undef : 174.Dv BUFSIZ , 175.Dv EOF , 176.Dv FILENAME_MAX , 177.Dv FOPEN_MAX , 178.Dv L_cuserid , 179.Dv L_ctermid , 180.Dv L_tmpnam , 181.Dv NULL , 182.Dv SEEK_END , 183.Dv SEEK_SET , 184.Dv SEE_CUR , 185.Dv TMP_MAX , 186.Fn clearerr , 187.Fn feof , 188.Fn ferror , 189.Fn fileno , 190.Fn freopen , 191.Fn fwopen , 192.Fn getc , 193.Fn getchar , 194.Fn putc , 195.Fn putchar , 196.Dv stderr , 197.Dv stdin , 198.Dv stdout . 199Function versions of the macro functions 200.Fn feof , 201.Fn ferror , 202.Fn clearerr , 203.Fn fileno , 204.Fn getc , 205.Fn getchar , 206.Fn putc , 207and 208.Fn putchar 209exist and will be used if the macros definitions are explicitly removed. 210.Sh SEE ALSO 211.Xr close 2 , 212.Xr open 2 , 213.Xr read 2 , 214.Xr write 2 215.Sh STANDARDS 216The 217.Nm 218library conforms to 219.St -ansiC . 220.Sh LIST OF FUNCTIONS 221.Bl -column "Description" 222.Sy Function Description 223clearerr check and reset stream status 224fclose close a stream 225fdopen stream open functions 226feof check and reset stream status 227ferror check and reset stream status 228fflush flush a stream 229fgetc get next character or word from input stream 230fgetln get a line from a stream 231fgetpos reposition a stream 232fgets get a line from a stream 233fgetwc get next wide character from input stream 234fileno check and reset stream status 235fopen stream open functions 236fprintf formatted output conversion 237fpurge flush a stream 238fputc output a character or word to a stream 239fputs output a line to a stream 240fputwc output a wide character to a stream 241fread binary stream input/output 242freopen stream open functions 243fropen open a stream 244fscanf input format conversion 245fseek reposition a stream 246fsetpos reposition a stream 247ftell reposition a stream 248funopen open a stream 249fwide set/get orientation of a stream 250fwopen open a stream 251fwrite binary stream input/output 252getc get next character or word from input stream 253getchar get next character or word from input stream 254gets get a line from a stream 255getw get next character or word from input stream 256getwc get next wide character from input stream 257getwchar get next wide character from input stream 258mkstemp create unique temporary file 259mktemp create unique temporary file 260perror system error messages 261printf formatted output conversion 262putc output a character or word to a stream 263putchar output a character or word to a stream 264puts output a line to a stream 265putw output a character or word to a stream 266putwc output a wide character to a stream 267putwchar output a wide character to a stream 268remove remove directory entry 269rewind reposition a stream 270scanf input format conversion 271setbuf stream buffering operations 272setbuffer stream buffering operations 273setlinebuf stream buffering operations 274setvbuf stream buffering operations 275snprintf formatted output conversion 276sprintf formatted output conversion 277sscanf input format conversion 278strerror system error messages 279sys_errlist system error messages 280sys_nerr system error messages 281tempnam temporary file routines 282tmpfile temporary file routines 283tmpnam temporary file routines 284ungetc un-get character from input stream 285ungetwc un-get wide character from input stream 286vfprintf formatted output conversion 287vfscanf input format conversion 288vprintf formatted output conversion 289vscanf input format conversion 290vsnprintf formatted output conversion 291vsprintf formatted output conversion 292vsscanf input format conversion 293.El 294.Sh BUGS 295The standard buffered functions do not interact well with certain other 296library and system functions, especially 297.Xr vfork 2 298and 299.Xr abort 3 . 300