1.\" Copyright (c) 1990, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)stdio.3 8.7 (Berkeley) 04/19/94 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 appended 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 transferred 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 71This implementation needs and makes 72no distinction between 73.Dq text 74and 75.Dq binary 76streams. 77In effect, all streams are binary. 78No translation is performed and no extra padding appears on any stream. 79.Pp 80At program startup, three streams are predefined and need not be 81opened explicitly: 82.Bl -bullet -compact -offset indent 83.It 84.Em standard input 85(for reading conventional input), 86.It 87.Em standard output 88(for writing conventional input), and 89.It 90.Em standard error 91(for writing diagnostic output). 92.El 93These streams are abbreviated 94.Em stdin , stdout 95and 96.Em stderr . 97Initially, the standard error stream 98is unbuffered; the standard input and output streams are 99fully buffered if and only if the streams do not refer to 100an interactive or 101.Dq terminal 102device, as determined by the 103.Xr isatty 3 104function. 105In fact, 106.Em all 107freshly-opened streams that refer to terminal devices 108default to line buffering, and 109pending output to such streams is written automatically 110whenever an such an input stream is read. 111Note that this applies only to 112.Dq "true reads" ; 113if the read request can be satisfied by existing buffered data, 114no automatic flush will occur. 115In these cases, 116or when a large amount of computation is done after printing 117part of a line on an output terminal, it is necessary to 118.Xr fflush 3 119the standard output before going off and computing so that the output 120will appear. 121Alternatively, these defaults may be modified via the 122.Xr setvbuf 3 123function. 124.Pp 125The 126.Nm stdio 127library is a part of the library 128.Xr libc 129and routines are automatically loaded as needed by the compilers 130.Xr cc 1 131and 132.Xr pc 1 . 133The 134.Tn SYNOPSIS 135sections of the following manual pages indicate which include files 136are to be used, what the compiler declaration for the function 137looks like and which external variables are of interest. 138.Pp 139The following are defined as macros; 140these names may not be re-used 141without first removing their current definitions with 142.Dv #undef : 143.Dv BUFSIZ , 144.Dv EOF , 145.Dv FILENAME_MAX , 146.DV FOPEN_MAX , 147.Dv L_cuserid , 148.Dv L_ctermid , 149.Dv L_tmpnam, 150.Dv NULL , 151.Dv SEEK_END , 152.Dv SEEK_SET , 153.Dv SEE_CUR , 154.Dv TMP_MAX , 155.Dv clearerr , 156.Dv feof , 157.Dv ferror , 158.Dv fileno , 159.Dv freopen , 160.Dv fwopen , 161.Dv getc , 162.Dv getchar , 163.Dv putc , 164.Dv putchar , 165.Dv stderr , 166.Dv stdin , 167.Dv stdout . 168Function versions of the macro functions 169.Xr feof , 170.Xr ferror , 171.Xr clearerr , 172.Xr fileno , 173.Xr getc , 174.Xr getchar , 175.Xr putc , 176and 177.Xr putchar 178exist and will be used if the macros 179definitions are explicitly removed. 180.Sh SEE ALSO 181.Xr open 2 , 182.Xr close 2 , 183.Xr read 2 , 184.Xr write 2 185.Sh BUGS 186The standard buffered functions do not interact well with certain other 187library and system functions, especially 188.Xr vfork 189and 190.Xr abort . 191.Sh STANDARDS 192The 193.Nm stdio 194library conforms to 195.St -ansiC . 196.Sh LIST OF FUNCTIONS 197.Bl -column "Description" 198.Sy Function Description 199clearerr check and reset stream status 200fclose close a stream 201fdopen stream open functions 202feof check and reset stream status 203ferror check and reset stream status 204fflush flush a stream 205fgetc get next character or word from input stream 206fgetline get a line from a stream 207fgetpos reposition a stream 208fgets get a line from a stream 209fileno check and reset stream status 210fopen stream open functions 211fprintf formatted output conversion 212fpurge flush a stream 213fputc output a character or word to a stream 214fputs output a line to a stream 215fread binary stream input/output 216freopen stream open functions 217fropen open a stream 218fscanf input format conversion 219fseek reposition a stream 220fsetpos reposition a stream 221ftell reposition a stream 222funopen open a stream 223fwopen open a stream 224fwrite binary stream input/output 225getc get next character or word from input stream 226getchar get next character or word from input stream 227gets get a line from a stream 228getw get next character or word from input stream 229mkstemp create unique temporary file 230mktemp create unique temporary file 231perror system error messages 232printf formatted output conversion 233putc output a character or word to a stream 234putchar output a character or word to a stream 235puts output a line to a stream 236putw output a character or word to a stream 237remove remove directory entry 238rewind reposition a stream 239scanf input format conversion 240setbuf stream buffering operations 241setbuffer stream buffering operations 242setlinebuf stream buffering operations 243setvbuf stream buffering operations 244snprintf formatted output conversion 245sprintf formatted output conversion 246sscanf input format conversion 247strerror system error messages 248sys_errlist system error messages 249sys_nerr system error messages 250tempnam temporary file routines 251tmpfile temporary file routines 252tmpnam temporary file routines 253ungetc un-get character from input stream 254vfprintf formatted output conversion 255vfscanf input format conversion 256vprintf formatted output conversion 257vscanf input format conversion 258vsnprintf formatted output conversion 259vsprintf formatted output conversion 260vsscanf input format conversion 261.El 262