1*0a6a1f1dSLionel Sambuc.\" $NetBSD: stdio.3,v 1.26 2015/09/06 04:20:50 mrg Exp $ 22fe8fb19SBen Gras.\" 32fe8fb19SBen Gras.\" Copyright (c) 1990, 1991, 1993 42fe8fb19SBen Gras.\" The Regents of the University of California. All rights reserved. 52fe8fb19SBen Gras.\" 62fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 72fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 82fe8fb19SBen Gras.\" are met: 92fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 102fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 112fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 122fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 132fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 142fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors 152fe8fb19SBen Gras.\" may be used to endorse or promote products derived from this software 162fe8fb19SBen Gras.\" without specific prior written permission. 172fe8fb19SBen Gras.\" 182fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 192fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 202fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 212fe8fb19SBen Gras.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 222fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 232fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 242fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 252fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 262fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 272fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 282fe8fb19SBen Gras.\" SUCH DAMAGE. 292fe8fb19SBen Gras.\" 302fe8fb19SBen Gras.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 312fe8fb19SBen Gras.\" 32*0a6a1f1dSLionel Sambuc.Dd September 6, 2015 332fe8fb19SBen Gras.Dt STDIO 3 342fe8fb19SBen Gras.Os 352fe8fb19SBen Gras.Sh NAME 362fe8fb19SBen Gras.Nm stdio 372fe8fb19SBen Gras.Nd standard input/output library functions 382fe8fb19SBen Gras.Sh LIBRARY 392fe8fb19SBen Gras.Lb libc 402fe8fb19SBen Gras.Sh SYNOPSIS 412fe8fb19SBen Gras.In stdio.h 422fe8fb19SBen Gras.Vt FILE *stdin; 432fe8fb19SBen Gras.Vt FILE *stdout; 442fe8fb19SBen Gras.Vt FILE *stderr; 452fe8fb19SBen Gras.Sh DESCRIPTION 462fe8fb19SBen GrasThe standard 472fe8fb19SBen Gras.Tn I/O 482fe8fb19SBen Graslibrary provides a simple and efficient buffered stream 492fe8fb19SBen Gras.Tn I/O 502fe8fb19SBen Grasinterface. 512fe8fb19SBen GrasInput and output is mapped into logical data streams 522fe8fb19SBen Grasand the physical 532fe8fb19SBen Gras.Tn I/O 542fe8fb19SBen Grascharacteristics are concealed. 552fe8fb19SBen Gras.Pp 562fe8fb19SBen GrasA stream is associated with an external file (which may be a physical 572fe8fb19SBen Grasdevice) by 582fe8fb19SBen Gras.Em opening 592fe8fb19SBen Grasa file, which may involve creating a new file. 602fe8fb19SBen GrasCreating an existing file causes its former contents to be discarded. 612fe8fb19SBen GrasIf a file can support positioning requests (such as a disk file, as opposed 622fe8fb19SBen Grasto a terminal) then a 632fe8fb19SBen Gras.Em file position indicator 642fe8fb19SBen Grasassociated with the stream is positioned at the start of the file (byte 652fe8fb19SBen Graszero), unless the file is opened with append mode. 662fe8fb19SBen GrasIf append mode 672fe8fb19SBen Grasis used, the position indicator will be placed the end-of-file. 682fe8fb19SBen GrasThe position indicator is maintained by subsequent reads, writes 692fe8fb19SBen Grasand positioning requests. 702fe8fb19SBen GrasAll input occurs as if the characters 712fe8fb19SBen Graswere read by successive calls to the 722fe8fb19SBen Gras.Xr fgetc 3 732fe8fb19SBen Grasfunction; all output takes place as if all characters were 742fe8fb19SBen Grasread by successive calls to the 752fe8fb19SBen Gras.Xr fputc 3 762fe8fb19SBen Grasfunction. 772fe8fb19SBen Gras.Pp 782fe8fb19SBen GrasA file is disassociated from a stream by 792fe8fb19SBen Gras.Em closing 802fe8fb19SBen Grasthe file. 812fe8fb19SBen GrasOutput streams are flushed (any unwritten buffer contents are transferred 822fe8fb19SBen Grasto the host environment) before the stream is disassociated from the file. 832fe8fb19SBen GrasThe value of a pointer to a 842fe8fb19SBen Gras.Dv FILE 852fe8fb19SBen Grasobject is indeterminate after a file is closed (garbage). 862fe8fb19SBen Gras.Pp 872fe8fb19SBen GrasA file may be subsequently reopened, by the same or another program 882fe8fb19SBen Grasexecution, and its contents reclaimed or modified (if it can be repositioned 892fe8fb19SBen Grasat the start). 902fe8fb19SBen GrasIf the main function returns to its original caller, or the 912fe8fb19SBen Gras.Xr exit 3 922fe8fb19SBen Grasfunction is called, all open files are closed (hence all output 932fe8fb19SBen Grasstreams are flushed) before program termination. 942fe8fb19SBen GrasOther methods of program termination, such as 952fe8fb19SBen Gras.Xr abort 3 962fe8fb19SBen Grasdo not bother about closing files properly. 972fe8fb19SBen Gras.Pp 982fe8fb19SBen GrasThis implementation needs and makes 992fe8fb19SBen Grasno distinction between 1002fe8fb19SBen Gras.Dq text 1012fe8fb19SBen Grasand 1022fe8fb19SBen Gras.Dq binary 1032fe8fb19SBen Grasstreams. 1042fe8fb19SBen GrasIn effect, all streams are binary. 1052fe8fb19SBen GrasNo translation is performed and no extra padding appears on any stream. 1062fe8fb19SBen Gras.Pp 1072fe8fb19SBen GrasAt program startup, three streams are predefined and need not be 1082fe8fb19SBen Grasopened explicitly: 1092fe8fb19SBen Gras.Bl -enum -offset indent 1102fe8fb19SBen Gras.It 1112fe8fb19SBen Gras.Em standard input 1122fe8fb19SBen Grasfor reading conventional input, 1132fe8fb19SBen Gras.It 1142fe8fb19SBen Gras.Em standard output 1152fe8fb19SBen Grasfor writing conventional output, and 1162fe8fb19SBen Gras.It 1172fe8fb19SBen Gras.Em standard error 1182fe8fb19SBen Grasfor writing diagnostic output. 1192fe8fb19SBen Gras.El 1202fe8fb19SBen Gras.Pp 1212fe8fb19SBen GrasThese streams are abbreviated 1222fe8fb19SBen Gras.Em stdin , 1232fe8fb19SBen Gras.Em stdout , 1242fe8fb19SBen Grasand 1252fe8fb19SBen Gras.Em stderr . 1262fe8fb19SBen Gras.Pp 1272fe8fb19SBen GrasInitially, the standard error stream 1282fe8fb19SBen Grasis unbuffered; the standard input and output streams are 1292fe8fb19SBen Grasfully buffered if and only if the streams do not refer to 1302fe8fb19SBen Grasan interactive or 1312fe8fb19SBen Gras.Dq terminal 1322fe8fb19SBen Grasdevice, as determined by the 1332fe8fb19SBen Gras.Xr isatty 3 1342fe8fb19SBen Grasfunction. 1352fe8fb19SBen GrasIn fact, 1362fe8fb19SBen Gras.Em all 1372fe8fb19SBen Grasfreshly-opened streams that refer to terminal devices 1382fe8fb19SBen Grasdefault to line buffering, and 1392fe8fb19SBen Graspending output to such streams is written automatically 1402fe8fb19SBen Graswhenever an such an input stream is read. 1412fe8fb19SBen GrasNote that this applies only to 1422fe8fb19SBen Gras.Dq "true reads" ; 1432fe8fb19SBen Grasif the read request can be satisfied by existing buffered data, 1442fe8fb19SBen Grasno automatic flush will occur. 1452fe8fb19SBen GrasIn these cases, 1462fe8fb19SBen Grasor when a large amount of computation is done after printing 1472fe8fb19SBen Graspart of a line on an output terminal, it is necessary to 1482fe8fb19SBen Gras.Xr fflush 3 1492fe8fb19SBen Grasthe standard output before going off and computing so that the output 1502fe8fb19SBen Graswill appear. 1512fe8fb19SBen GrasAlternatively, these defaults may be modified via the 1522fe8fb19SBen Gras.Xr setvbuf 3 1532fe8fb19SBen Grasfunction. 1542fe8fb19SBen Gras.Sh IMPLEMENTATION NOTES 1552fe8fb19SBen GrasIn multi-threaded applications, operations on streams perform implicit 1562fe8fb19SBen Graslocking, except for the 1572fe8fb19SBen Gras.Fn getc_unlocked , 1582fe8fb19SBen Gras.Fn getchar_unlocked , 1592fe8fb19SBen Gras.Fn putc_unlocked , 1602fe8fb19SBen Grasand 1612fe8fb19SBen Gras.Fn putchar_unlocked 1622fe8fb19SBen Grasfunctions. 1632fe8fb19SBen GrasExplicit control of stream locking is available through the 1642fe8fb19SBen Gras.Fn flockfile , 1652fe8fb19SBen Gras.Fn ftrylockfile , 1662fe8fb19SBen Grasand 1672fe8fb19SBen Gras.Fn funlockfile 1682fe8fb19SBen Grasfunctions . 1692fe8fb19SBen Gras.Pp 1702fe8fb19SBen GrasThe following are defined as macros; these names may not be re-used 1712fe8fb19SBen Graswithout first removing their current definitions with 1722fe8fb19SBen Gras.Dv #undef : 1732fe8fb19SBen Gras.Dv BUFSIZ , 1742fe8fb19SBen Gras.Dv EOF , 1752fe8fb19SBen Gras.Dv FILENAME_MAX , 1762fe8fb19SBen Gras.Dv FOPEN_MAX , 1772fe8fb19SBen Gras.Dv L_cuserid , 1782fe8fb19SBen Gras.Dv L_ctermid , 1792fe8fb19SBen Gras.Dv L_tmpnam , 1802fe8fb19SBen Gras.Dv NULL , 1812fe8fb19SBen Gras.Dv SEEK_END , 1822fe8fb19SBen Gras.Dv SEEK_SET , 1832fe8fb19SBen Gras.Dv SEE_CUR , 1842fe8fb19SBen Gras.Dv TMP_MAX , 1852fe8fb19SBen Gras.Fn clearerr , 1862fe8fb19SBen Gras.Fn feof , 1872fe8fb19SBen Gras.Fn ferror , 1882fe8fb19SBen Gras.Fn fileno , 1892fe8fb19SBen Gras.Fn freopen , 1902fe8fb19SBen Gras.Fn fwopen , 1912fe8fb19SBen Gras.Fn getc , 1922fe8fb19SBen Gras.Fn getc_unlocked , 1932fe8fb19SBen Gras.Fn getchar , 1942fe8fb19SBen Gras.Fn getchar_unlocked , 1952fe8fb19SBen Gras.Fn putc , 1962fe8fb19SBen Gras.Fn putc_unlocked , 1972fe8fb19SBen Gras.Fn putchar , 1982fe8fb19SBen Gras.Fn putchar_unlocked , 1992fe8fb19SBen Gras.Dv stderr , 2002fe8fb19SBen Gras.Dv stdin , 2012fe8fb19SBen Gras.Dv stdout . 2022fe8fb19SBen Gras.Pp 2032fe8fb19SBen GrasFunction versions of the macro functions 2042fe8fb19SBen Gras.Fn feof , 2052fe8fb19SBen Gras.Fn ferror , 2062fe8fb19SBen Gras.Fn clearerr , 2072fe8fb19SBen Gras.Fn fileno , 2082fe8fb19SBen Gras.Fn getc , 2092fe8fb19SBen Gras.Fn getc_unlocked , 2102fe8fb19SBen Gras.Fn getchar , 2112fe8fb19SBen Gras.Fn getchar_unlocked , 2122fe8fb19SBen Gras.Fn putc , 2132fe8fb19SBen Gras.Fn putc_unlocked , 2142fe8fb19SBen Gras.Fn putchar , 2152fe8fb19SBen Grasand 2162fe8fb19SBen Gras.Fn putchar_unlocked 2172fe8fb19SBen Grasexist and will be used if the macros definitions are explicitly removed. 2182fe8fb19SBen Gras.Sh SEE ALSO 2192fe8fb19SBen Gras.Xr close 2 , 2202fe8fb19SBen Gras.Xr open 2 , 2212fe8fb19SBen Gras.Xr read 2 , 2222fe8fb19SBen Gras.Xr write 2 2232fe8fb19SBen Gras.Sh STANDARDS 2242fe8fb19SBen GrasThe 2252fe8fb19SBen Gras.Nm 2262fe8fb19SBen Graslibrary conforms to 2272fe8fb19SBen Gras.St -ansiC . 2282fe8fb19SBen Gras.Sh LIST OF FUNCTIONS 2292fe8fb19SBen Gras.Bl -column "putchar_unlocked" "Description" 2302fe8fb19SBen Gras.It Sy Function Description 231*0a6a1f1dSLionel Sambuc.It asprintf formatted output conversion with allocation 232*0a6a1f1dSLionel Sambuc.It asprintf_l formatted output conversion with allocation 2332fe8fb19SBen Gras.It clearerr check and reset stream status 234*0a6a1f1dSLionel Sambuc.It dprintf formatted output conversion 235*0a6a1f1dSLionel Sambuc.It dprintf_l formatted output conversion 2362fe8fb19SBen Gras.It fclose close a stream 2372fe8fb19SBen Gras.It fdopen stream open functions 2382fe8fb19SBen Gras.It feof check and reset stream status 2392fe8fb19SBen Gras.It ferror check and reset stream status 2402fe8fb19SBen Gras.It fflush flush a stream 2412fe8fb19SBen Gras.It fgetc get next character or word from input stream 2422fe8fb19SBen Gras.It fgetln get a line from a stream 2432fe8fb19SBen Gras.It fgetpos reposition a stream 2442fe8fb19SBen Gras.It fgets get a line from a stream 2452fe8fb19SBen Gras.It fgetwc get next wide character from input stream 2462fe8fb19SBen Gras.It fileno check and reset stream status 2472fe8fb19SBen Gras.It flockfile lock a stream 248*0a6a1f1dSLionel Sambuc.It fmemopen open a stream that points to a memory buffer 2492fe8fb19SBen Gras.It fopen stream open functions 2502fe8fb19SBen Gras.It fprintf formatted output conversion 251*0a6a1f1dSLionel Sambuc.It fprintf_l formatted output conversion 2522fe8fb19SBen Gras.It fpurge flush a stream 2532fe8fb19SBen Gras.It fputc output a character or word to a stream 2542fe8fb19SBen Gras.It fputs output a line to a stream 2552fe8fb19SBen Gras.It fputwc output a wide character to a stream 2562fe8fb19SBen Gras.It fread binary stream input/output 2572fe8fb19SBen Gras.It freopen stream open functions 2582fe8fb19SBen Gras.It fropen open a stream 2592fe8fb19SBen Gras.It fscanf input format conversion 260*0a6a1f1dSLionel Sambuc.It fscanf_l input format conversion 2612fe8fb19SBen Gras.It fseek reposition a stream 262*0a6a1f1dSLionel Sambuc.It fseeko reposition a stream 2632fe8fb19SBen Gras.It fsetpos reposition a stream 2642fe8fb19SBen Gras.It ftell reposition a stream 265*0a6a1f1dSLionel Sambuc.It ftello reposition a stream 2662fe8fb19SBen Gras.It ftrylockfile lock a stream (non-blocking) 2672fe8fb19SBen Gras.It funlockfile unlock a stream 2682fe8fb19SBen Gras.It funopen open a stream 269*0a6a1f1dSLionel Sambuc.It funopen2 open a stream, with flush support 2702fe8fb19SBen Gras.It fwide set/get orientation of a stream 2712fe8fb19SBen Gras.It fwopen open a stream 2722fe8fb19SBen Gras.It fwrite binary stream input/output 2732fe8fb19SBen Gras.It getc get next character or word from input stream 2742fe8fb19SBen Gras.It getc_unlocked get next character or word from input stream 2752fe8fb19SBen Gras.It Ta (no implicit locking) 2762fe8fb19SBen Gras.It getchar get next character or word from input stream 2772fe8fb19SBen Gras.It getchar_unlocked get next character or word from input stream 2782fe8fb19SBen Gras.It Ta (no implicit locking) 2792fe8fb19SBen Gras.It getdelim get a delimited record from a stream 2802fe8fb19SBen Gras.It getline get a line from a stream 2812fe8fb19SBen Gras.It gets get a line from a stream 2822fe8fb19SBen Gras.It getw get next character or word from input stream 2832fe8fb19SBen Gras.It getwc get next wide character from input stream 2842fe8fb19SBen Gras.It getwchar get next wide character from input stream 2852fe8fb19SBen Gras.It mkstemp create unique temporary file 2862fe8fb19SBen Gras.It mktemp create unique temporary file 287*0a6a1f1dSLionel Sambuc.It open_memstream open memory as a stream 288*0a6a1f1dSLionel Sambuc.It popen open a program as a stream 289*0a6a1f1dSLionel Sambuc.It popenve open a program as a stream 290*0a6a1f1dSLionel Sambuc.It pclose close an opened program stream 2912fe8fb19SBen Gras.It perror system error messages 2922fe8fb19SBen Gras.It printf formatted output conversion 293*0a6a1f1dSLionel Sambuc.It printf_l formatted output conversion 2942fe8fb19SBen Gras.It putc output a character or word to a stream 2952fe8fb19SBen Gras.It putc_unlocked output a character or word to a stream 2962fe8fb19SBen Gras.It Ta (no implicit locking) 2972fe8fb19SBen Gras.It putchar output a character or word to a stream 2982fe8fb19SBen Gras.It putchar_unlocked output a character or word to a stream 2992fe8fb19SBen Gras.It Ta (no implicit locking) 3002fe8fb19SBen Gras.It puts output a line to a stream 3012fe8fb19SBen Gras.It putw output a character or word to a stream 3022fe8fb19SBen Gras.It putwc output a wide character to a stream 3032fe8fb19SBen Gras.It putwchar output a wide character to a stream 3042fe8fb19SBen Gras.It remove remove directory entry 3052fe8fb19SBen Gras.It rewind reposition a stream 3062fe8fb19SBen Gras.It scanf input format conversion 307*0a6a1f1dSLionel Sambuc.It scanf_l input format conversion 3082fe8fb19SBen Gras.It setbuf stream buffering operations 3092fe8fb19SBen Gras.It setbuffer stream buffering operations 3102fe8fb19SBen Gras.It setlinebuf stream buffering operations 3112fe8fb19SBen Gras.It setvbuf stream buffering operations 3122fe8fb19SBen Gras.It snprintf formatted output conversion 313*0a6a1f1dSLionel Sambuc.It snprintf_l formatted output conversion 3142fe8fb19SBen Gras.It sprintf formatted output conversion 3152fe8fb19SBen Gras.It sscanf input format conversion 316*0a6a1f1dSLionel Sambuc.It sscanf_l input format conversion 3172fe8fb19SBen Gras.It strerror system error messages 3182fe8fb19SBen Gras.It sys_errlist system error messages 3192fe8fb19SBen Gras.It sys_nerr system error messages 3202fe8fb19SBen Gras.It tempnam temporary file routines 3212fe8fb19SBen Gras.It tmpfile temporary file routines 3222fe8fb19SBen Gras.It tmpnam temporary file routines 3232fe8fb19SBen Gras.It ungetc un-get character from input stream 3242fe8fb19SBen Gras.It ungetwc un-get wide character from input stream 325*0a6a1f1dSLionel Sambuc.It vasprintf formatted output conversion with allocation 326*0a6a1f1dSLionel Sambuc.It vasprintf_l formatted output conversion with allocation 327*0a6a1f1dSLionel Sambuc.It vdprintf formatted output conversion 328*0a6a1f1dSLionel Sambuc.It vdprintf_l formatted output conversion 3292fe8fb19SBen Gras.It vfprintf formatted output conversion 330*0a6a1f1dSLionel Sambuc.It vfprintf_l formatted output conversion 3312fe8fb19SBen Gras.It vfscanf input format conversion 332*0a6a1f1dSLionel Sambuc.It vfscanf_l input format conversion 3332fe8fb19SBen Gras.It vprintf formatted output conversion 334*0a6a1f1dSLionel Sambuc.It vprintf_l formatted output conversion 3352fe8fb19SBen Gras.It vscanf input format conversion 336*0a6a1f1dSLionel Sambuc.It vscanf_l input format conversion 3372fe8fb19SBen Gras.It vsnprintf formatted output conversion 338*0a6a1f1dSLionel Sambuc.It vsnprintf_l formatted output conversion 3392fe8fb19SBen Gras.It vsprintf formatted output conversion 340*0a6a1f1dSLionel Sambuc.It vsprintf_l formatted output conversion 3412fe8fb19SBen Gras.It vsscanf input format conversion 342*0a6a1f1dSLionel Sambuc.It vsscanf_l input format conversion 3432fe8fb19SBen Gras.El 3442fe8fb19SBen Gras.Sh BUGS 3452fe8fb19SBen GrasThe standard buffered functions do not interact well with certain other 3462fe8fb19SBen Graslibrary and system functions, especially 3472fe8fb19SBen Gras.Xr vfork 2 3482fe8fb19SBen Grasand 3492fe8fb19SBen Gras.Xr abort 3 . 350