1.\" $OpenBSD: stdio.3,v 1.19 2007/05/31 19:19:31 jmc 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: May 31 2007 $ 31.Dt STDIO 3 32.Os 33.Sh NAME 34.Nm stdio 35.Nd standard input/output library functions 36.Sh SYNOPSIS 37.Fd #include <stdio.h> 38.Pp 39.Fd FILE *stdin; 40.Fd FILE *stdout; 41.Fd FILE *stderr; 42.Sh DESCRIPTION 43The standard 44.Tn I/O 45library provides a simple and efficient buffered stream 46.Tn I/O 47interface. 48Input and output is mapped into logical data streams and the physical 49.Tn I/O 50characteristics are concealed. 51The functions and macros are listed below; 52more information is available from the individual man pages. 53.Pp 54A stream is associated with an external file (which may be a physical 55device) by 56.Dq opening 57a file, which may involve creating a new file. 58Creating an existing file causes its former contents to be discarded. 59If a file can support positioning requests (such as a disk file, as opposed 60to a terminal) then a 61.Dq file position indicator 62associated with the stream is positioned at the start of the file (byte 63zero), unless the file is opened with append mode. 64If append mode 65is used, the position indicator will be placed at the end-of-file. 66The position indicator is maintained by subsequent reads, writes, 67and positioning requests. 68All input occurs as if the characters 69were read by successive calls to the 70.Xr fgetc 3 71function; all output takes place as if all characters were 72written by successive calls to the 73.Xr fputc 3 74function. 75.Pp 76A file is disassociated from a stream by 77.Dq closing 78it. 79Output streams are flushed (any unwritten buffer contents are transferred 80to the host environment) before the stream is disassociated from the file. 81The value of a pointer to a 82.Dv FILE 83object is indeterminate (garbage) after a file is closed. 84.Pp 85A file may be subsequently reopened, by the same or another program 86execution, and its contents reclaimed or modified (if it can be repositioned 87at the start). 88If the main function returns to its original caller, or the 89.Xr exit 3 90function is called, all open files are closed (hence all output 91streams are flushed) before program termination. 92Other methods of program termination may not close files properly and hence 93buffered output may be lost. 94In particular, 95.Xr _exit 2 96does not flush 97.Nm 98files. 99Neither does an exit due to a signal. 100Buffers are flushed by 101.Xr abort 3 102as required by POSIX, although previous implementations did not. 103.Pp 104This implementation needs and makes 105no distinction between 106.Dq text 107and 108.Dq binary 109streams. 110In effect, all streams are binary. 111No translation is performed and no extra padding appears on any stream. 112.Pp 113At program startup, three streams are predefined and need not be 114opened explicitly: 115.Pp 116.Bl -bullet -compact -offset indent 117.It 118.Em standard input 119(for reading conventional input), 120.It 121.Em standard output 122(for writing conventional output), and 123.It 124.Em standard error 125(for writing diagnostic output). 126.El 127.Pp 128These streams are abbreviated 129.Em stdin , 130.Em stdout , 131and 132.Em stderr . 133Initially, the standard error stream 134is unbuffered; the standard input and output streams are 135fully buffered if and only if the streams do not refer to 136an interactive or 137.Dq terminal 138device, as determined by the 139.Xr isatty 3 140function. 141In fact, 142.Em all 143freshly opened streams that refer to terminal devices 144default to line buffering, and 145pending output to such streams is written automatically 146whenever such an input stream is read. 147Note that this applies only to 148.Dq "true reads" ; 149if the read request can be satisfied by existing buffered data, 150no automatic flush will occur. 151In these cases, 152or when a large amount of computation is done after printing 153part of a line on an output terminal, it is necessary to 154.Xr fflush 3 155the standard output before going off and computing so that the output 156will appear. 157Alternatively, these defaults may be modified via the 158.Xr setvbuf 3 159function. 160.Pp 161The 162.Nm stdio 163library is a part of the library 164.Xr libc 165and routines are automatically loaded as needed by the compiler. 166The 167.Tn SYNOPSIS 168sections of the following manual pages indicate which include files 169are to be used, what the compiler declaration for the function 170looks like, and which external variables are of interest. 171.Pp 172The following are defined as macros; 173these names may not be re-used 174without first removing their current definitions with 175.Dv #undef : 176.Dv BUFSIZ , 177.Dv EOF , 178.Dv FILENAME_MAX , 179.Dv FOPEN_MAX , 180.Dv L_cuserid , 181.Dv L_ctermid , 182.Dv L_tmpnam , 183.Dv NULL , 184.Dv SEEK_END , 185.Dv SEEK_SET , 186.Dv SEEK_CUR , 187.Dv TMP_MAX , 188.Dv clearerr , 189.Dv feof , 190.Dv ferror , 191.Dv fileno , 192.Dv freopen , 193.Dv fwopen , 194.Dv getc , 195.Dv getchar , 196.Dv putc , 197.Dv putchar , 198.Dv stderr , 199.Dv stdin , 200.Dv stdout . 201Function versions of the macro functions 202.Xr feof 3 , 203.Xr ferror 3 , 204.Xr clearerr 3 , 205.Xr fileno 3 , 206.Xr getc 3 , 207.Xr getchar 3 , 208.Xr putc 3 , 209and 210.Xr putchar 3 211exist and will be used if the macro 212definitions are explicitly removed. 213.Sh LIST OF FUNCTIONS 214.Bl -column "Description" 215.Sy Function Description 216asprintf formatted output conversion with allocation 217clearerr check and reset stream status 218fclose close a stream 219fdopen stream open functions 220feof check and reset stream status 221ferror check and reset stream status 222fflush flush a stream 223fgetc get next character or word from input stream 224fgetln get a line from a stream 225fgetpos reposition a stream 226fgets get a line from a stream 227fileno get a stream's underlying file descriptor 228fopen stream open functions 229fprintf formatted output conversion 230fpurge flush a stream 231fputc output a character or word to a stream 232fputs output a line to a stream 233fread binary stream input/output 234freopen stream open functions 235fropen open a stream 236fscanf input format conversion 237fseek reposition a stream 238fsetpos reposition a stream 239ftell reposition a stream 240funopen open a stream 241fwopen open a stream 242fwrite binary stream input/output 243getc get next character or word from input stream 244getchar get next character or word from input stream 245gets get a line from a stream 246getw get next character or word from input stream 247mkstemp create unique temporary file 248mktemp create unique temporary file 249perror system error messages 250printf formatted output conversion 251putc output a character or word to a stream 252putchar output a character or word to a stream 253puts output a line to a stream 254putw output a character or word to a stream 255remove remove directory entry 256rewind reposition a stream 257scanf input format conversion 258setbuf stream buffering operations 259setbuffer stream buffering operations 260setlinebuf stream buffering operations 261setvbuf stream buffering operations 262snprintf formatted output conversion 263sprintf formatted output conversion 264sscanf input format conversion 265strerror system error messages 266sys_errlist system error messages 267sys_nerr system error messages 268tempnam temporary file routines 269tmpfile temporary file routines 270tmpnam temporary file routines 271ungetc un-get character from input stream 272vasprintf formatted output conversion with allocation 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 STANDARDS 287The 288.Nm stdio 289library conforms to 290.St -ansiC . 291.Sh BUGS 292The standard buffered functions do not interact well with certain other 293library and system functions, especially 294.Xr vfork 2 295and 296.Xr abort 3 . 297