xref: /minix3/lib/libc/stdio/stdio.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
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