1.\" $OpenBSD: stdio.3,v 1.13 2000/04/20 01:39:32 aaron 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.Dd April 19, 1994 35.Dt STDIO 3 36.Os 37.Sh NAME 38.Nm stdio 39.Nd standard input/output library functions 40.Sh SYNOPSIS 41.Fd #include <stdio.h> 42.Pp 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 and the physical 53.Tn I/O 54characteristics are concealed. 55The functions and macros are listed below; 56more 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.Dq opening 61a file, which may involve creating a new file. 62Creating an existing 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.Dq 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. 68If append mode 69is used, the position indicator will be placed at the end-of-file. 70The position indicator is maintained by subsequent reads, writes 71and positioning requests. 72All input occurs as if the characters 73were read by successive calls to the 74.Xr fgetc 3 75function; all output takes place as if all characters were 76written by successive calls to the 77.Xr fputc 3 78function. 79.Pp 80A file is disassociated from a stream by 81.Dq closing 82it. 83Output streams are flushed (any unwritten buffer contents are transferred 84to the host environment) before the stream is disassociated from the file. 85The value of a pointer to a 86.Dv FILE 87object is indeterminate (garbage) after a file is closed. 88.Pp 89A file may be subsequently reopened, by the same or another program 90execution, and its contents reclaimed or modified (if it can be repositioned 91at the start). 92If the main function returns to its original caller, or the 93.Xr exit 3 94function is called, all open files are closed (hence all output 95streams are flushed) before program termination. 96Other methods of program termination may not close files properly and hence 97buffered output may be lost. 98In particular, 99.Xr _exit 2 100does not flush stdio files. 101Neither does an exit due to a signal. 102Buffers are flushed by 103.Xr abort 3 104as required by POSIX, although previous implementations did not. 105.Pp 106This implementation needs and makes 107no distinction between 108.Dq text 109and 110.Dq binary 111streams. 112In effect, all streams are binary. 113No translation is performed and no extra padding appears on any stream. 114.Pp 115At program startup, three streams are predefined and need not be 116opened explicitly: 117.Pp 118.Bl -bullet -compact -offset indent 119.It 120.Em standard input 121(for reading conventional input), 122.It 123.Em standard output 124(for writing conventional output), and 125.It 126.Em standard error 127(for writing diagnostic output). 128.El 129.Pp 130These streams are abbreviated 131.Em stdin , 132.Em stdout , 133and 134.Em stderr . 135Initially, the standard error stream 136is unbuffered; the standard input and output streams are 137fully buffered if and only if the streams do not refer to 138an interactive or 139.Dq terminal 140device, as determined by the 141.Xr isatty 3 142function. 143In fact, 144.Em all 145freshly opened streams that refer to terminal devices 146default to line buffering, and 147pending output to such streams is written automatically 148whenever such an input stream is read. 149Note that this applies only to 150.Dq "true reads" ; 151if the read request can be satisfied by existing buffered data, 152no automatic flush will occur. 153In these cases, 154or when a large amount of computation is done after printing 155part of a line on an output terminal, it is necessary to 156.Xr fflush 3 157the standard output before going off and computing so that the output 158will appear. 159Alternatively, these defaults may be modified via the 160.Xr setvbuf 3 161function. 162.Pp 163The 164.Nm stdio 165library is a part of the library 166.Xr libc 167and routines are automatically loaded as needed by the compiler. 168The 169.Tn SYNOPSIS 170sections of the following manual pages indicate which include files 171are to be used, what the compiler declaration for the function 172looks like and which external variables are of interest. 173.Pp 174The following are defined as macros; 175these names may not be re-used 176without first removing their current definitions with 177.Dv #undef : 178.Dv BUFSIZ , 179.Dv EOF , 180.Dv FILENAME_MAX , 181.Dv FOPEN_MAX , 182.Dv L_cuserid , 183.Dv L_ctermid , 184.Dv L_tmpnam , 185.Dv NULL , 186.Dv SEEK_END , 187.Dv SEEK_SET , 188.Dv SEE_CUR , 189.Dv TMP_MAX , 190.Dv clearerr , 191.Dv feof , 192.Dv ferror , 193.Dv fileno , 194.Dv freopen , 195.Dv fwopen , 196.Dv getc , 197.Dv getchar , 198.Dv putc , 199.Dv putchar , 200.Dv stderr , 201.Dv stdin , 202.Dv stdout . 203Function versions of the macro functions 204.Xr feof , 205.Xr ferror , 206.Xr clearerr , 207.Xr fileno , 208.Xr getc , 209.Xr getchar , 210.Xr putc , 211and 212.Xr putchar 213exist and will be used if the macro 214definitions are explicitly removed. 215.Sh LIST OF FUNCTIONS 216.Bl -column "Description" 217.Sy Function Description 218clearerr check and reset stream status 219fclose close a stream 220fdopen stream open functions 221feof check and reset stream status 222ferror check and reset stream status 223fflush flush a stream 224fgetc get next character or word from input stream 225fgetln get a line from a stream 226fgetpos reposition a stream 227fgets get a line from a stream 228fileno check and reset stream status 229fopen stream open functions 230fprintf formatted output conversion 231fpurge flush a stream 232fputc output a character or word to a stream 233fputs output a line to a stream 234fread binary stream input/output 235freopen stream open functions 236fropen open a stream 237fscanf input format conversion 238fseek reposition a stream 239fsetpos reposition a stream 240ftell reposition a stream 241funopen open a stream 242fwopen open a stream 243fwrite binary stream input/output 244getc get next character or word from input stream 245getchar get next character or word from input stream 246gets get a line from a stream 247getw get next character or word from input stream 248mkstemp create unique temporary file 249mktemp create unique temporary file 250perror system error messages 251printf formatted output conversion 252putc output a character or word to a stream 253putchar output a character or word to a stream 254puts output a line to a stream 255putw output a character or word to a stream 256remove remove directory entry 257rewind reposition a stream 258scanf input format conversion 259setbuf stream buffering operations 260setbuffer stream buffering operations 261setlinebuf stream buffering operations 262setvbuf stream buffering operations 263snprintf formatted output conversion 264sprintf formatted output conversion 265sscanf input format conversion 266strerror system error messages 267sys_errlist system error messages 268sys_nerr system error messages 269tempnam temporary file routines 270tmpfile temporary file routines 271tmpnam temporary file routines 272ungetc un-get character from input stream 273vfprintf formatted output conversion 274vfscanf input format conversion 275vprintf formatted output conversion 276vscanf input format conversion 277vsnprintf formatted output conversion 278vsprintf formatted output conversion 279vsscanf input format conversion 280.El 281.Sh SEE ALSO 282.Xr close 2 , 283.Xr open 2 , 284.Xr read 2 , 285.Xr write 2 286.Sh BUGS 287The standard buffered functions do not interact well with certain other 288library and system functions, especially 289.Xr vfork 290and 291.Xr abort . 292.Sh STANDARDS 293The 294.Nm stdio 295library conforms to 296.St -ansiC . 297