1.\" $OpenBSD: stdio.3,v 1.14 2002/07/24 22:59:03 deraadt 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 218asprintf formatted output conversion with allocation 219clearerr check and reset stream status 220fclose close a stream 221fdopen stream open functions 222feof check and reset stream status 223ferror check and reset stream status 224fflush flush a stream 225fgetc get next character or word from input stream 226fgetln get a line from a stream 227fgetpos reposition a stream 228fgets get a line from a stream 229fileno check and reset stream status 230fopen stream open functions 231fprintf formatted output conversion 232fpurge flush a stream 233fputc output a character or word to a stream 234fputs output a line to a stream 235fread binary stream input/output 236freopen stream open functions 237fropen open a stream 238fscanf input format conversion 239fseek reposition a stream 240fsetpos reposition a stream 241ftell reposition a stream 242funopen open a stream 243fwopen open a stream 244fwrite binary stream input/output 245getc get next character or word from input stream 246getchar get next character or word from input stream 247gets get a line from a stream 248getw get next character or word from input stream 249mkstemp create unique temporary file 250mktemp create unique temporary file 251perror system error messages 252printf formatted output conversion 253putc output a character or word to a stream 254putchar output a character or word to a stream 255puts output a line to a stream 256putw output a character or word to a stream 257remove remove directory entry 258rewind reposition a stream 259scanf input format conversion 260setbuf stream buffering operations 261setbuffer stream buffering operations 262setlinebuf stream buffering operations 263setvbuf stream buffering operations 264snprintf formatted output conversion 265sprintf formatted output conversion 266sscanf input format conversion 267strerror system error messages 268sys_errlist system error messages 269sys_nerr system error messages 270tempnam temporary file routines 271tmpfile temporary file routines 272tmpnam temporary file routines 273ungetc un-get character from input stream 274vasprintf formatted output conversion with allocation 275vfprintf formatted output conversion 276vfscanf input format conversion 277vprintf formatted output conversion 278vscanf input format conversion 279vsnprintf formatted output conversion 280vsprintf formatted output conversion 281vsscanf input format conversion 282.El 283.Sh SEE ALSO 284.Xr close 2 , 285.Xr open 2 , 286.Xr read 2 , 287.Xr write 2 288.Sh BUGS 289The standard buffered functions do not interact well with certain other 290library and system functions, especially 291.Xr vfork 292and 293.Xr abort . 294.Sh STANDARDS 295The 296.Nm stdio 297library conforms to 298.St -ansiC . 299