1.\" $NetBSD: stdio.3,v 1.28 2020/08/29 15:25:57 rillig 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.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 31.\" 32.Dd August 29, 2020 33.Dt STDIO 3 34.Os 35.Sh NAME 36.Nm stdio 37.Nd standard input/output library functions 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In stdio.h 42.Vt FILE *stdin; 43.Vt FILE *stdout; 44.Vt FILE *stderr; 45.Sh DESCRIPTION 46The standard 47.Tn I/O 48library provides a simple and efficient buffered stream 49.Tn I/O 50interface. 51Input and output is mapped into logical data streams 52and the physical 53.Tn I/O 54characteristics are concealed. 55.Pp 56A stream is associated with an external file (which may be a physical 57device) by 58.Em opening 59a file, which may involve creating a new file. 60Creating an existing file causes its former contents to be discarded. 61If a file can support positioning requests (such as a disk file, as opposed 62to a terminal) then a 63.Em file position indicator 64associated with the stream is positioned at the start of the file (byte 65zero), unless the file is opened with append mode. 66If append mode is used, the position indicator is placed at the end-of-file. 67The position indicator is maintained by subsequent reads, writes 68and positioning requests. 69All input occurs as if the characters were 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.Em closing 78the file. 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 after a file is closed (garbage). 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, such as 93.Xr abort 3 94do not bother about closing files properly. 95.Pp 96This implementation needs and makes 97no distinction between 98.Dq text 99and 100.Dq binary 101streams. 102In effect, all streams are binary. 103No translation is performed and no extra padding appears on any stream. 104.Pp 105At program startup, three streams are predefined and need not be 106opened explicitly: 107.Bl -enum -offset indent 108.It 109.Em standard input 110for reading conventional input, 111.It 112.Em standard output 113for writing conventional output, and 114.It 115.Em standard error 116for writing diagnostic output. 117.El 118.Pp 119These streams are abbreviated 120.Em stdin , 121.Em stdout , 122and 123.Em stderr . 124.Pp 125Initially, the standard error stream 126is unbuffered; the standard input and output streams are 127fully buffered if and only if the streams do not refer to 128an interactive or 129.Dq terminal 130device, as determined by the 131.Xr isatty 3 132function. 133In fact, 134.Em all 135freshly-opened streams that refer to terminal devices 136default to line buffering, and 137pending output to such streams is written automatically 138whenever such an input stream is read. 139Note that this applies only to 140.Dq "true reads" ; 141if the read request can be satisfied by existing buffered data, 142no automatic flush will occur. 143In these cases, 144or when a large amount of computation is done after printing 145part of a line on an output terminal, it is necessary to 146.Xr fflush 3 147the standard output before going off and computing so that the output 148will appear. 149Alternatively, these defaults may be modified via the 150.Xr setvbuf 3 151function. 152.Sh IMPLEMENTATION NOTES 153In multi-threaded applications, operations on streams perform implicit 154locking, except for the 155.Fn getc_unlocked , 156.Fn getchar_unlocked , 157.Fn putc_unlocked , 158and 159.Fn putchar_unlocked 160functions. 161Explicit control of stream locking is available through the 162.Fn flockfile , 163.Fn ftrylockfile , 164and 165.Fn funlockfile 166functions . 167.Pp 168The following are defined as macros; these names may not be re-used 169without first removing their current definitions with 170.Dv #undef : 171.Dv BUFSIZ , 172.Dv EOF , 173.Dv FILENAME_MAX , 174.Dv FOPEN_MAX , 175.Dv L_cuserid , 176.Dv L_ctermid , 177.Dv L_tmpnam , 178.Dv NULL , 179.Dv SEEK_END , 180.Dv SEEK_SET , 181.Dv SEE_CUR , 182.Dv TMP_MAX , 183.Fn clearerr , 184.Fn feof , 185.Fn ferror , 186.Fn fileno , 187.Fn freopen , 188.Fn fwopen , 189.Fn getc , 190.Fn getc_unlocked , 191.Fn getchar , 192.Fn getchar_unlocked , 193.Fn putc , 194.Fn putc_unlocked , 195.Fn putchar , 196.Fn putchar_unlocked , 197.Dv stderr , 198.Dv stdin , 199.Dv stdout . 200.Pp 201Function versions of the macro functions 202.Fn feof , 203.Fn ferror , 204.Fn clearerr , 205.Fn fileno , 206.Fn getc , 207.Fn getc_unlocked , 208.Fn getchar , 209.Fn getchar_unlocked , 210.Fn putc , 211.Fn putc_unlocked , 212.Fn putchar , 213and 214.Fn putchar_unlocked 215exist and will be used if the macros definitions are explicitly removed. 216.Sh SEE ALSO 217.Xr close 2 , 218.Xr open 2 , 219.Xr read 2 , 220.Xr write 2 221.Sh STANDARDS 222The 223.Nm 224library conforms to 225.St -ansiC . 226.Sh LIST OF FUNCTIONS 227.Bl -column "putchar_unlocked" "Description" 228.It Sy Function Description 229.It asprintf formatted output conversion with allocation 230.It asprintf_l formatted output conversion with allocation 231.It clearerr check and reset stream status 232.It dprintf formatted output conversion 233.It dprintf_l formatted output conversion 234.It fclose close a stream 235.It fdopen stream open functions 236.It feof check and reset stream status 237.It ferror check and reset stream status 238.It fflush flush a stream 239.It fgetc get next character or word from input stream 240.It fgetln get a line from a stream 241.It fgetpos reposition a stream 242.It fgets get a line from a stream 243.It fgetwc get next wide character from input stream 244.It fileno check and reset stream status 245.It flockfile lock a stream 246.It fmemopen open a stream that points to a memory buffer 247.It fopen stream open functions 248.It fprintf formatted output conversion 249.It fprintf_l formatted output conversion 250.It fpurge flush a stream 251.It fputc output a character or word to a stream 252.It fputs output a line to a stream 253.It fputwc output a wide character to a stream 254.It fread binary stream input/output 255.It freopen stream open functions 256.It fropen open a stream 257.It fscanf input format conversion 258.It fscanf_l input format conversion 259.It fseek reposition a stream 260.It fseeko reposition a stream 261.It fsetpos reposition a stream 262.It ftell reposition a stream 263.It ftello reposition a stream 264.It ftrylockfile lock a stream (non-blocking) 265.It funlockfile unlock a stream 266.It funopen open a stream 267.It funopen2 open a stream, with flush support 268.It fwide set/get orientation of a stream 269.It fwopen open a stream 270.It fwrite binary stream input/output 271.It getc get next character or word from input stream 272.It getc_unlocked get next character or word from input stream 273.It Ta (no implicit locking) 274.It getchar get next character or word from input stream 275.It getchar_unlocked get next character or word from input stream 276.It Ta (no implicit locking) 277.It getdelim get a delimited record from a stream 278.It getline get a line from a stream 279.It gets get a line from a stream 280.It getw get next character or word from input stream 281.It getwc get next wide character from input stream 282.It getwchar get next wide character from input stream 283.It mkstemp create unique temporary file 284.It mktemp create unique temporary file 285.It open_memstream open memory as a stream 286.It popen open a program as a stream 287.It popenve open a program as a stream 288.It pclose close an opened program stream 289.It perror system error messages 290.It printf formatted output conversion 291.It printf_l formatted output conversion 292.It putc output a character or word to a stream 293.It putc_unlocked output a character or word to a stream 294.It Ta (no implicit locking) 295.It putchar output a character or word to a stream 296.It putchar_unlocked output a character or word to a stream 297.It Ta (no implicit locking) 298.It puts output a line to a stream 299.It putw output a character or word to a stream 300.It putwc output a wide character to a stream 301.It putwchar output a wide character to a stream 302.It remove remove directory entry 303.It rewind reposition a stream 304.It scanf input format conversion 305.It scanf_l input format conversion 306.It setbuf stream buffering operations 307.It setbuffer stream buffering operations 308.It setlinebuf stream buffering operations 309.It setvbuf stream buffering operations 310.It snprintf formatted output conversion 311.It snprintf_l formatted output conversion 312.It sprintf formatted output conversion 313.It sscanf input format conversion 314.It sscanf_l input format conversion 315.It strerror system error messages 316.It sys_errlist system error messages 317.It sys_nerr system error messages 318.It tempnam temporary file routines 319.It tmpfile temporary file routines 320.It tmpnam temporary file routines 321.It ungetc un-get character from input stream 322.It ungetwc un-get wide character from input stream 323.It vasprintf formatted output conversion with allocation 324.It vasprintf_l formatted output conversion with allocation 325.It vdprintf formatted output conversion 326.It vdprintf_l formatted output conversion 327.It vfprintf formatted output conversion 328.It vfprintf_l formatted output conversion 329.It vfscanf input format conversion 330.It vfscanf_l input format conversion 331.It vprintf formatted output conversion 332.It vprintf_l formatted output conversion 333.It vscanf input format conversion 334.It vscanf_l input format conversion 335.It vsnprintf formatted output conversion 336.It vsnprintf_l formatted output conversion 337.It vsprintf formatted output conversion 338.It vsprintf_l formatted output conversion 339.It vsscanf input format conversion 340.It vsscanf_l input format conversion 341.El 342.Sh BUGS 343The standard buffered functions do not interact well with certain other 344library and system functions, especially 345.Xr vfork 2 346and 347.Xr abort 3 . 348