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