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