| blob | eff53c8bc341c6b4e57d8eb8239a936e4cfb0c93 |
1 .\" $NetBSD: stdio.3,v 1.24 2010/05/05 04:13:16 jruoho 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 May 5, 2010
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
46 The standard
47 .Tn I/O
48 library provides a simple and efficient buffered stream
49 .Tn I/O
50 interface.
51 Input and output is mapped into logical data streams
52 and the physical
53 .Tn I/O
54 characteristics are concealed.
55 .Pp
56 A stream is associated with an external file (which may be a physical
57 device) by
58 .Em opening
59 a file, which may involve creating a new file.
60 Creating an existing file causes its former contents to be discarded.
61 If a file can support positioning requests (such as a disk file, as opposed
62 to a terminal) then a
63 .Em file position indicator
64 associated with the stream is positioned at the start of the file (byte
65 zero), unless the file is opened with append mode.
66 If append mode
67 is used, the position indicator will be placed the end-of-file.
68 The position indicator is maintained by subsequent reads, writes
69 and positioning requests.
70 All input occurs as if the characters
71 were read by successive calls to the
72 .Xr fgetc 3
73 function; all output takes place as if all characters were
74 read by successive calls to the
75 .Xr fputc 3
76 function.
77 .Pp
78 A file is disassociated from a stream by
79 .Em closing
80 the file.
81 Output streams are flushed (any unwritten buffer contents are transferred
82 to the host environment) before the stream is disassociated from the file.
83 The value of a pointer to a
84 .Dv FILE
85 object is indeterminate after a file is closed (garbage).
86 .Pp
87 A file may be subsequently reopened, by the same or another program
88 execution, and its contents reclaimed or modified (if it can be repositioned
89 at the start).
90 If the main function returns to its original caller, or the
91 .Xr exit 3
92 function is called, all open files are closed (hence all output
93 streams are flushed) before program termination.
94 Other methods of program termination, such as
95 .Xr abort 3
96 do not bother about closing files properly.
97 .Pp
98 This implementation needs and makes
99 no distinction between
100 .Dq text
101 and
102 .Dq binary
103 streams.
104 In effect, all streams are binary.
105 No translation is performed and no extra padding appears on any stream.
106 .Pp
107 At program startup, three streams are predefined and need not be
108 opened explicitly:
109 .Bl -enum -offset indent
110 .It
111 .Em standard input
112 for reading conventional input,
113 .It
114 .Em standard output
115 for writing conventional output, and
116 .It
117 .Em standard error
118 for writing diagnostic output.
119 .El
120 .Pp
121 These streams are abbreviated
122 .Em stdin ,
123 .Em stdout ,
124 and
125 .Em stderr .
126 .Pp
127 Initially, the standard error stream
128 is unbuffered; the standard input and output streams are
129 fully buffered if and only if the streams do not refer to
130 an interactive or
131 .Dq terminal
132 device, as determined by the
133 .Xr isatty 3
134 function.
135 In fact,
136 .Em all
137 freshly-opened streams that refer to terminal devices
138 default to line buffering, and
139 pending output to such streams is written automatically
140 whenever an such an input stream is read.
141 Note that this applies only to
142 .Dq "true reads" ;
143 if the read request can be satisfied by existing buffered data,
144 no automatic flush will occur.
145 In these cases,
146 or when a large amount of computation is done after printing
147 part of a line on an output terminal, it is necessary to
148 .Xr fflush 3
149 the standard output before going off and computing so that the output
150 will appear.
151 Alternatively, these defaults may be modified via the
152 .Xr setvbuf 3
153 function.
154 .Sh IMPLEMENTATION NOTES
155 In multi-threaded applications, operations on streams perform implicit
156 locking, except for the
157 .Fn getc_unlocked ,
158 .Fn getchar_unlocked ,
159 .Fn putc_unlocked ,
160 and
161 .Fn putchar_unlocked
162 functions.
163 Explicit control of stream locking is available through the
164 .Fn flockfile ,
165 .Fn ftrylockfile ,
166 and
167 .Fn funlockfile
168 functions .
169 .Pp
170 The following are defined as macros; these names may not be re-used
171 without first removing their current definitions with
172 .Dv #undef :
173 .Dv BUFSIZ ,
174 .Dv EOF ,
175 .Dv FILENAME_MAX ,
176 .Dv FOPEN_MAX ,
177 .Dv L_cuserid ,
178 .Dv L_ctermid ,
179 .Dv L_tmpnam ,
180 .Dv NULL ,
181 .Dv SEEK_END ,
182 .Dv SEEK_SET ,
183 .Dv SEE_CUR ,
184 .Dv TMP_MAX ,
185 .Fn clearerr ,
186 .Fn feof ,
187 .Fn ferror ,
188 .Fn fileno ,
189 .Fn freopen ,
190 .Fn fwopen ,
191 .Fn getc ,
192 .Fn getc_unlocked ,
193 .Fn getchar ,
194 .Fn getchar_unlocked ,
195 .Fn putc ,
196 .Fn putc_unlocked ,
197 .Fn putchar ,
198 .Fn putchar_unlocked ,
199 .Dv stderr ,
200 .Dv stdin ,
201 .Dv stdout .
202 .Pp
203 Function versions of the macro functions
204 .Fn feof ,
205 .Fn ferror ,
206 .Fn clearerr ,
207 .Fn fileno ,
208 .Fn getc ,
209 .Fn getc_unlocked ,
210 .Fn getchar ,
211 .Fn getchar_unlocked ,
212 .Fn putc ,
213 .Fn putc_unlocked ,
214 .Fn putchar ,
215 and
216 .Fn putchar_unlocked
217 exist and will be used if the macros definitions are explicitly removed.
218 .Sh SEE ALSO
219 .Xr close 2 ,
220 .Xr open 2 ,
221 .Xr read 2 ,
222 .Xr write 2
223 .Sh STANDARDS
224 The
225 .Nm
226 library conforms to
227 .St -ansiC .
228 .Sh LIST OF FUNCTIONS
229 .Bl -column "putchar_unlocked" "Description"
230 .It Sy Function Description
231 .It clearerr check and reset stream status
232 .It fclose close a stream
233 .It fdopen stream open functions
234 .It feof check and reset stream status
235 .It ferror check and reset stream status
236 .It fflush flush a stream
237 .It fgetc get next character or word from input stream
238 .It fgetln get a line from a stream
239 .It fgetpos reposition a stream
240 .It fgets get a line from a stream
241 .It fgetwc get next wide character from input stream
242 .It fileno check and reset stream status
243 .It flockfile lock a stream
244 .It fopen stream open functions
245 .It fprintf formatted output conversion
246 .It fpurge flush a stream
247 .It fputc output a character or word to a stream
248 .It fputs output a line to a stream
249 .It fputwc output a wide character to a stream
250 .It fread binary stream input/output
251 .It freopen stream open functions
252 .It fropen open a stream
253 .It fscanf input format conversion
254 .It fseek reposition a stream
255 .It fsetpos reposition a stream
256 .It ftell reposition a stream
257 .It ftrylockfile lock a stream (non-blocking)
258 .It funlockfile unlock a stream
259 .It funopen open a stream
260 .It fwide set/get orientation of a stream
261 .It fwopen open a stream
262 .It fwrite binary stream input/output
263 .It getc get next character or word from input stream
264 .It getc_unlocked get next character or word from input stream
265 .It Ta (no implicit locking)
266 .It getchar get next character or word from input stream
267 .It getchar_unlocked get next character or word from input stream
268 .It Ta (no implicit locking)
269 .It getdelim get a delimited record from a stream
270 .It getline get a line from a stream
271 .It gets get a line from a stream
272 .It getw get next character or word from input stream
273 .It getwc get next wide character from input stream
274 .It getwchar get next wide character from input stream
275 .It mkstemp create unique temporary file
276 .It mktemp create unique temporary file
277 .It perror system error messages
278 .It printf formatted output conversion
279 .It putc output a character or word to a stream
280 .It putc_unlocked output a character or word to a stream
281 .It Ta (no implicit locking)
282 .It putchar output a character or word to a stream
283 .It putchar_unlocked output a character or word to a stream
284 .It Ta (no implicit locking)
285 .It puts output a line to a stream
286 .It putw output a character or word to a stream
287 .It putwc output a wide character to a stream
288 .It putwchar output a wide character to a stream
289 .It remove remove directory entry
290 .It rewind reposition a stream
291 .It scanf input format conversion
292 .It setbuf stream buffering operations
293 .It setbuffer stream buffering operations
294 .It setlinebuf stream buffering operations
295 .It setvbuf stream buffering operations
296 .It snprintf formatted output conversion
297 .It sprintf formatted output conversion
298 .It sscanf input format conversion
299 .It strerror system error messages
300 .It sys_errlist system error messages
301 .It sys_nerr system error messages
302 .It tempnam temporary file routines
303 .It tmpfile temporary file routines
304 .It tmpnam temporary file routines
305 .It ungetc un-get character from input stream
306 .It ungetwc un-get wide character from input stream
307 .It vfprintf formatted output conversion
308 .It vfscanf input format conversion
309 .It vprintf formatted output conversion
310 .It vscanf input format conversion
311 .It vsnprintf formatted output conversion
312 .It vsprintf formatted output conversion
313 .It vsscanf input format conversion
314 .El
315 .Sh BUGS
316 The standard buffered functions do not interact well with certain other
317 library and system functions, especially
318 .Xr vfork 2
319 and
320 .Xr abort 3 .