Tue May 4 07:43:12 2010 UTC ()
Remove the list of functions.

This list was updated only two times in nearly two decades.

(If people need to learn the standard I/O functions in C, it would be better
to mention K&R or some other textbook; if people need to know the list of
functions, it would be better to point out the location of the standard.)

In addition, some clean-up and structural editing.


(jruoho)
diff -r1.22 -r1.23 src/lib/libc/stdio/stdio.3
cvs diff -r1.22 -r1.23 src/lib/libc/stdio/stdio.3 (expand / switch to unified diff)

--- src/lib/libc/stdio/stdio.3 2009/07/13 22:31:59 1.22
+++ src/lib/libc/stdio/stdio.3 2010/05/04 07:43:12 1.23
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: stdio.3,v 1.22 2009/07/13 22:31:59 wiz Exp $ 1.\" $NetBSD: stdio.3,v 1.23 2010/05/04 07:43:12 jruoho Exp $
2.\" 2.\"
3.\" Copyright (c) 1990, 1991, 1993 3.\" Copyright (c) 1990, 1991, 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
@@ -19,51 +19,49 @@ @@ -19,51 +19,49 @@
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 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 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 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 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE. 28.\" SUCH DAMAGE.
29.\" 29.\"
30.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94 30.\" @(#)stdio.3 8.7 (Berkeley) 4/19/94
31.\" 31.\"
32.Dd July 13, 2009 32.Dd May 4, 2010
33.Dt STDIO 3 33.Dt STDIO 3
34.Os 34.Os
35.Sh NAME 35.Sh NAME
36.Nm stdio 36.Nm stdio
37.Nd standard input/output library functions 37.Nd standard input/output library functions
38.Sh LIBRARY 38.Sh LIBRARY
39.Lb libc 39.Lb libc
40.Sh SYNOPSIS 40.Sh SYNOPSIS
41.In stdio.h 41.In stdio.h
42.Fd FILE *stdin; 42.Vt FILE *stdin;
43.Fd FILE *stdout; 43.Vt FILE *stdout;
44.Fd FILE *stderr; 44.Vt FILE *stderr;
45.Sh DESCRIPTION 45.Sh DESCRIPTION
46The standard 46The standard
47.Tn I/O 47.Tn I/O
48library provides a simple and efficient buffered stream 48library provides a simple and efficient buffered stream
49.Tn I/O 49.Tn I/O
50interface. 50interface.
51Input and output is mapped into logical data streams 51Input and output is mapped into logical data streams
52and the physical 52and the physical
53.Tn I/O 53.Tn I/O
54characteristics are concealed. 54characteristics are concealed.
55The functions and macros are listed below; 
56more information is available from the individual man pages. 
57.Pp 55.Pp
58A stream is associated with an external file (which may be a physical 56A stream is associated with an external file (which may be a physical
59device) by 57device) by
60.Em opening 58.Em opening
61a file, which may involve creating a new file. 59a file, which may involve creating a new file.
62Creating an existing file causes its former contents to be discarded. 60Creating an existing file causes its former contents to be discarded.
63If a file can support positioning requests (such as a disk file, as opposed 61If a file can support positioning requests (such as a disk file, as opposed
64to a terminal) then a 62to a terminal) then a
65.Em file position indicator 63.Em file position indicator
66associated with the stream is positioned at the start of the file (byte 64associated with the stream is positioned at the start of the file (byte
67zero), unless the file is opened with append mode. 65zero), unless the file is opened with append mode.
68If append mode 66If append mode
69is used, the position indicator will be placed the end-of-file. 67is used, the position indicator will be placed the end-of-file.
@@ -98,41 +96,44 @@ Other methods of program termination, su @@ -98,41 +96,44 @@ Other methods of program termination, su
98do not bother about closing files properly. 96do not bother about closing files properly.
99.Pp 97.Pp
100This implementation needs and makes 98This implementation needs and makes
101no distinction between 99no distinction between
102.Dq text 100.Dq text
103and 101and
104.Dq binary 102.Dq binary
105streams. 103streams.
106In effect, all streams are binary. 104In effect, all streams are binary.
107No translation is performed and no extra padding appears on any stream. 105No translation is performed and no extra padding appears on any stream.
108.Pp 106.Pp
109At program startup, three streams are predefined and need not be 107At program startup, three streams are predefined and need not be
110opened explicitly: 108opened explicitly:
111.Bl -bullet -compact -offset indent 109.Bl -enum -offset indent
112.It 110.It
113.Em standard input 111.Em standard input
114(for reading conventional input), 112for reading conventional input,
115.It 113.It
116.Em standard output 114.Em standard output
117(for writing conventional output), and 115for writing conventional output, and
118.It 116.It
119.Em standard error 117.Em standard error
120(for writing diagnostic output). 118for writing diagnostic output.
121.El 119.El
 120.Pp
122These streams are abbreviated 121These streams are abbreviated
123.Em stdin , stdout 122.Em stdin ,
 123.Em stdout ,
124and 124and
125.Em stderr . 125.Em stderr .
 126.Pp
126Initially, the standard error stream 127Initially, the standard error stream
127is unbuffered; the standard input and output streams are 128is unbuffered; the standard input and output streams are
128fully buffered if and only if the streams do not refer to 129fully buffered if and only if the streams do not refer to
129an interactive or 130an interactive or
130.Dq terminal 131.Dq terminal
131device, as determined by the 132device, as determined by the
132.Xr isatty 3 133.Xr isatty 3
133function. 134function.
134In fact, 135In fact,
135.Em all 136.Em all
136freshly-opened streams that refer to terminal devices 137freshly-opened streams that refer to terminal devices
137default to line buffering, and 138default to line buffering, and
138pending output to such streams is written automatically 139pending output to such streams is written automatically
@@ -140,53 +141,40 @@ whenever an such an input stream is read @@ -140,53 +141,40 @@ whenever an such an input stream is read
140Note that this applies only to 141Note that this applies only to
141.Dq "true reads" ; 142.Dq "true reads" ;
142if the read request can be satisfied by existing buffered data, 143if the read request can be satisfied by existing buffered data,
143no automatic flush will occur. 144no automatic flush will occur.
144In these cases, 145In these cases,
145or when a large amount of computation is done after printing 146or when a large amount of computation is done after printing
146part of a line on an output terminal, it is necessary to 147part of a line on an output terminal, it is necessary to
147.Xr fflush 3 148.Xr fflush 3
148the standard output before going off and computing so that the output 149the standard output before going off and computing so that the output
149will appear. 150will appear.
150Alternatively, these defaults may be modified via the 151Alternatively, these defaults may be modified via the
151.Xr setvbuf 3 152.Xr setvbuf 3
152function. 153function.
153.Pp 154.Sh IMPLEMENTATION NOTES
154The 
155.Nm 
156library is a part of the library 
157.Pa libc.a 
158and routines are automatically loaded as needed by compilers such 
159as 
160.Xr cc 1 . 
161The 
162.Tn SYNOPSIS 
163sections of the following manual pages indicate which include files 
164are to be used, what the compiler declaration for the function 
165looks like and which external variables are of interest. 
166.Pp 
167In multi-threaded applications, operations on streams perform implicit 155In multi-threaded applications, operations on streams perform implicit
168locking, except for the 156locking, except for the
169.Fa getc_unlocked , 157.Fn getc_unlocked ,
170.Fa getchar_unlocked , 158.Fn getchar_unlocked ,
171.Fa putc_unlocked , 159.Fn putc_unlocked ,
172and 160and
173.Fa putchar_unlocked 161.Fn putchar_unlocked
174functions. 162functions.
175Explicit control of stream locking is available through the 163Explicit control of stream locking is available through the
176.Fa flockfile , 164.Fn flockfile ,
177.Fa ftrylockfile , 165.Fn ftrylockfile ,
178and 166and
179.Fa funlockfile 167.Fn funlockfile
180functions . 168functions .
181.Pp 169.Pp
182The following are defined as macros; these names may not be re-used 170The following are defined as macros; these names may not be re-used
183without first removing their current definitions with 171without first removing their current definitions with
184.Dv #undef : 172.Dv #undef :
185.Dv BUFSIZ , 173.Dv BUFSIZ ,
186.Dv EOF , 174.Dv EOF ,
187.Dv FILENAME_MAX , 175.Dv FILENAME_MAX ,
188.Dv FOPEN_MAX , 176.Dv FOPEN_MAX ,
189.Dv L_cuserid , 177.Dv L_cuserid ,
190.Dv L_ctermid , 178.Dv L_ctermid ,
191.Dv L_tmpnam , 179.Dv L_tmpnam ,
192.Dv NULL , 180.Dv NULL ,
@@ -201,131 +189,45 @@ without first removing their current def @@ -201,131 +189,45 @@ without first removing their current def
201.Fn freopen , 189.Fn freopen ,
202.Fn fwopen , 190.Fn fwopen ,
203.Fn getc , 191.Fn getc ,
204.Fn getc_unlocked , 192.Fn getc_unlocked ,
205.Fn getchar , 193.Fn getchar ,
206.Fn getchar_unlocked , 194.Fn getchar_unlocked ,
207.Fn putc , 195.Fn putc ,
208.Fn putc_unlocked , 196.Fn putc_unlocked ,
209.Fn putchar , 197.Fn putchar ,
210.Fn putchar_unlocked , 198.Fn putchar_unlocked ,
211.Dv stderr , 199.Dv stderr ,
212.Dv stdin , 200.Dv stdin ,
213.Dv stdout . 201.Dv stdout .
 202.Pp
214Function versions of the macro functions 203Function versions of the macro functions
215.Fn feof , 204.Fn feof ,
216.Fn ferror , 205.Fn ferror ,
217.Fn clearerr , 206.Fn clearerr ,
218.Fn fileno , 207.Fn fileno ,
219.Fn getc , 208.Fn getc ,
220.Fn getc_unlocked , 209.Fn getc_unlocked ,
221.Fn getchar , 210.Fn getchar ,
222.Fn getchar_unlocked , 211.Fn getchar_unlocked ,
223.Fn putc , 212.Fn putc ,
224.Fn putc_unlocked , 213.Fn putc_unlocked ,
225.Fn putchar , 214.Fn putchar ,
226and 215and
227.Fn putchar_unlocked 216.Fn putchar_unlocked
228exist and will be used if the macros definitions are explicitly removed. 217exist and will be used if the macros definitions are explicitly removed.
229.Sh SEE ALSO 218.Sh SEE ALSO
230.Xr close 2 , 219.Xr close 2 ,
231.Xr open 2 , 220.Xr open 2 ,
232.Xr read 2 , 221.Xr read 2 ,
233.Xr write 2 222.Xr write 2
234.Sh STANDARDS 223.Sh STANDARDS
235The 224The
236.Nm 225.Nm
237library conforms to 226library conforms to
238.St -ansiC . 227.St -ansiC .
239.Sh LIST OF FUNCTIONS 
240.Bl -column "putchar_unlocked" "Description" 
241.It Sy Function Description 
242.It clearerr check and reset stream status 
243.It fclose close a stream 
244.It fdopen stream open functions 
245.It feof check and reset stream status 
246.It ferror check and reset stream status 
247.It fflush flush a stream 
248.It fgetc get next character or word from input stream 
249.It fgetln get a line from a stream 
250.It fgetpos reposition a stream 
251.It fgets get a line from a stream 
252.It fgetwc get next wide character from input stream 
253.It fileno check and reset stream status 
254.It flockfile lock a stream 
255.It fopen stream open functions 
256.It fprintf formatted output conversion 
257.It fpurge flush a stream 
258.It fputc output a character or word to a stream 
259.It fputs output a line to a stream 
260.It fputwc output a wide character to a stream 
261.It fread binary stream input/output 
262.It freopen stream open functions 
263.It fropen open a stream 
264.It fscanf input format conversion 
265.It fseek reposition a stream 
266.It fsetpos reposition a stream 
267.It ftell reposition a stream 
268.It ftrylockfile lock a stream (non-blocking) 
269.It funlockfile unlock a stream 
270.It funopen open a stream 
271.It fwide set/get orientation of a stream 
272.It fwopen open a stream 
273.It fwrite binary stream input/output 
274.It getc get next character or word from input stream 
275.It getc_unlocked get next character or word from input stream 
276.It Ta (no implicit locking) 
277.It getchar get next character or word from input stream 
278.It getchar_unlocked get next character or word from input stream 
279.It Ta (no implicit locking) 
280.It getdelim get a delimited record from a stream 
281.It getline get a line from a stream 
282.It gets get a line from a stream 
283.It getw get next character or word from input stream 
284.It getwc get next wide character from input stream 
285.It getwchar get next wide character from input stream 
286.It mkstemp create unique temporary file 
287.It mktemp create unique temporary file 
288.It perror system error messages 
289.It printf formatted output conversion 
290.It putc output a character or word to a stream 
291.It putc_unlocked output a character or word to a stream 
292.It Ta (no implicit locking) 
293.It putchar output a character or word to a stream 
294.It putchar_unlocked output a character or word to a stream 
295.It Ta (no implicit locking) 
296.It puts output a line to a stream 
297.It putw output a character or word to a stream 
298.It putwc output a wide character to a stream 
299.It putwchar output a wide character to a stream 
300.It remove remove directory entry 
301.It rewind reposition a stream 
302.It scanf input format conversion 
303.It setbuf stream buffering operations 
304.It setbuffer stream buffering operations 
305.It setlinebuf stream buffering operations 
306.It setvbuf stream buffering operations 
307.It snprintf formatted output conversion 
308.It sprintf formatted output conversion 
309.It sscanf input format conversion 
310.It strerror system error messages 
311.It sys_errlist system error messages 
312.It sys_nerr system error messages 
313.It tempnam temporary file routines 
314.It tmpfile temporary file routines 
315.It tmpnam temporary file routines 
316.It ungetc un-get character from input stream 
317.It ungetwc un-get wide character from input stream 
318.It vfprintf formatted output conversion 
319.It vfscanf input format conversion 
320.It vprintf formatted output conversion 
321.It vscanf input format conversion 
322.It vsnprintf formatted output conversion 
323.It vsprintf formatted output conversion 
324.It vsscanf input format conversion 
325.El 
326.Sh BUGS 228.Sh BUGS
327The standard buffered functions do not interact well with certain other 229The standard buffered functions do not interact well with certain other
328library and system functions, especially 230library and system functions, especially
329.Xr vfork 2 231.Xr vfork 2
330and 232and
331.Xr abort 3 . 233.Xr abort 3 .