1.\" Copyright (c) 1990, 1991 Regents of the University of California. 2.\" 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.\" from: @(#)stdio.3 6.5 (Berkeley) 5/6/91 33.\" $Id: stdio.3,v 1.3 1994/01/11 00:07:00 jtc Exp $ 34.\" 35.Dd May 6, 1991 36.Dt STDIO 3 37.Os BSD 4 38.Sh NAME 39.Nm stdio 40.Nd standard input/output library functions 41.Sh SYNOPSIS 42.Fd #include <stdio.h> 43.Fd FILE *stdin; 44.Fd FILE *stdout; 45.Fd FILE *stderr; 46.Sh DESCRIPTION 47The standard 48.Tn I/O 49library provides a simple and efficient buffered stream 50.Tn I/O 51interface. 52Input and output is mapped into logical data streams 53and the physical 54.Tn I/O 55characteristics are concealed. The functions and macros are listed 56below; more information is available from the individual man pages. 57.Pp 58A stream is associated with an external file (which may be a physical 59device) by 60.Em opening 61a file, which may involve creating a new file. Creating an 62existing file causes its former contents to be discarded. 63If a file can support positioning requests (such as a disk file, as opposed 64to a terminal) then a 65.Em file position indicator 66associated with the stream is positioned at the start of the file (byte 67zero), unless the file is opened with append mode. If append mode 68is used, the position indicator will be placed the end-of-file. 69The position indicator is maintained by subsequent reads, writes 70and positioning requests. All input occurs as if the characters 71were read by successive calls to the 72.Xr fgetc 3 73function; all output takes place as if all characters were 74read by successive calls to the 75.Xr fputc 3 76function. 77.Pp 78A file is disassociated from a stream by 79.Em closing 80the file. 81Output streams are flushed (any unwritten buffer contents are transferred 82to the host environment) before the stream is disassociated from the file. 83The value of a pointer to a 84.Dv FILE 85object is indeterminate after a file is closed (garbage). 86.Pp 87A file may be subsequently reopened, by the same or another program 88execution, and its contents reclaimed or modified (if it can be repositioned 89at the start). If the main function returns to its original caller, or 90the 91.Xr exit 3 92function is called, all open files are closed (hence all output 93streams are flushed) before program termination. Other methods 94of program termination, such as 95.Xr abort 3 96do not bother about closing files properly. 97.Pp 98At program startup, three text streams are predefined and need not be 99opened explicitly 100\(em 101.Em standard input 102(for reading conventional input), 103\(em 104.Em standard output 105(for writing conventional input), 106and 107.Em standard error 108(for writing diagnostic output). 109These streams are abbreviated 110.Em stdin , stdout 111and 112.Em stderr . 113When opened, the standard error stream 114is not fully buffered; the standard input and output streams are 115fully buffered if and only if the streams do not to refer to 116an interactive device. 117.Pp 118Output streams that refer to terminal devices 119are always line buffered by default; 120pending output to such streams is written automatically 121whenever an input stream that refers to a terminal device is read. 122In cases where a large amount of computation is done after printing 123part of a line on an output terminal, it is necessary to 124.Xr fflush 3 125the standard output before going off and computing so that the output 126will appear. 127.Pp 128The 129.Nm stdio 130library is a part of the library 131.Xr libc 132and routines are automatically loaded as needed by the compilers 133.Xr cc 1 134and 135.Xr pc 1 . 136The 137.Tn SYNOPSIS 138sections of the following manual pages indicate which include files 139are to be used, what the compiler declaration for the function 140looks like and which external variables are of interest. 141.Pp 142The following are defined as macros; 143these names may not be re-used 144without first removing their current definitions with 145.Dv #undef : 146.Dv BUFSIZ , 147.Dv EOF , 148.Dv FILENAME_MAX , 149.DV FOPEN_MAX , 150.Dv L_cuserid , 151.Dv L_ctermid , 152.Dv L_tmpnam, 153.Dv NULL , 154.Dv SEEK_END , 155.Dv SEEK_SET , 156.Dv SEE_CUR , 157.Dv TMP_MAX , 158.Dv clearerr , 159.Dv feof , 160.Dv ferror , 161.Dv fileno , 162.Dv fropen , 163.Dv fwopen , 164.Dv getc , 165.Dv getchar , 166.Dv putc , 167.Dv putchar , 168.Dv stderr , 169.Dv stdin , 170.Dv stdout . 171Function versions of the macro functions 172.Xr feof , 173.Xr ferror , 174.Xr clearerr , 175.Xr fileno , 176.Xr getc , 177.Xr getchar , 178.Xr putc , 179and 180.Xr putchar 181exist and will be used if the macros 182definitions are explicitly removed. 183.Sh SEE ALSO 184.Xr open 2 , 185.Xr close 2 , 186.Xr read 2 , 187.Xr write 2 188.Sh BUGS 189The standard buffered functions do not interact well with certain other 190library and system functions, especially 191.Xr vfork 192and 193.Xr abort . 194.Sh STANDARDS 195The 196.Nm stdio 197library conforms to 198.St -ansiC . 199.Sh LIST OF FUNCTIONS 200.Bl -column "Description" 201.Sy Function Description 202clearerr check and reset stream status 203fclose close a stream 204fdopen stream open functions 205feof check and reset stream status 206ferror check and reset stream status 207fflush flush a stream 208fgetc get next character or word from input stream 209fgetln get a line from a stream 210fgetpos reposition a stream 211fgets get a line from a stream 212fileno check and reset stream status 213fopen stream open functions 214fprintf formatted output conversion 215fpurge flush a stream 216fputc output a character or word to a stream 217fputs output a line to a stream 218fread binary stream input/output 219freopen stream open functions 220fropen open a stream 221fscanf input format conversion 222fseek reposition a stream 223fsetpos reposition a stream 224ftell reposition a stream 225funopen open a stream 226fwopen open a stream 227fwrite binary stream input/output 228getc get next character or word from input stream 229getchar get next character or word from input stream 230gets get a line from a stream 231getw get next character or word from input stream 232mktemp make temporary file name (unique) 233perror system error messages 234printf formatted output conversion 235putc output a character or word to a stream 236putchar output a character or word to a stream 237puts output a line to a stream 238putw output a character or word to a stream 239remove remove directory entry 240rewind reposition a stream 241scanf input format conversion 242setbuf stream buffering operations 243setbuffer stream buffering operations 244setlinebuf stream buffering operations 245setvbuf stream buffering operations 246snprintf formatted output conversion 247sprintf formatted output conversion 248sscanf input format conversion 249strerror system error messages 250sys_errlist system error messages 251sys_nerr system error messages 252tempnam temporary file routines 253tmpfile temporary file routines 254tmpnam temporary file routines 255ungetc un-get character from input stream 256vfprintf formatted output conversion 257vfscanf input format conversion 258vprintf formatted output conversion 259vscanf input format conversion 260vsnprintf formatted output conversion 261vsprintf formatted output conversion 262vsscanf input format conversion 263.El 264