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