| blob | 7caa622e69e7095d72b9d8d55ac095f8d25f3584 |
1 .\" $NetBSD: stdio.3,v 1.26 2015/09/06 04:20:50 mrg 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 September 6, 2015
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 asprintf formatted output conversion with allocation
232 .It asprintf_l formatted output conversion with allocation
233 .It clearerr check and reset stream status
234 .It dprintf formatted output conversion
235 .It dprintf_l formatted output conversion
236 .It fclose close a stream
237 .It fdopen stream open functions
238 .It feof check and reset stream status
239 .It ferror check and reset stream status
240 .It fflush flush a stream
241 .It fgetc get next character or word from input stream
242 .It fgetln get a line from a stream
243 .It fgetpos reposition a stream
244 .It fgets get a line from a stream
245 .It fgetwc get next wide character from input stream
246 .It fileno check and reset stream status
247 .It flockfile lock a stream
248 .It fmemopen open a stream that points to a memory buffer
249 .It fopen stream open functions
250 .It fprintf formatted output conversion
251 .It fprintf_l formatted output conversion
252 .It fpurge flush a stream
253 .It fputc output a character or word to a stream
254 .It fputs output a line to a stream
255 .It fputwc output a wide character to a stream
256 .It fread binary stream input/output
257 .It freopen stream open functions
258 .It fropen open a stream
259 .It fscanf input format conversion
260 .It fscanf_l input format conversion
261 .It fseek reposition a stream
262 .It fseeko reposition a stream
263 .It fsetpos reposition a stream
264 .It ftell reposition a stream
265 .It ftello reposition a stream
266 .It ftrylockfile lock a stream (non-blocking)
267 .It funlockfile unlock a stream
268 .It funopen open a stream
269 .It funopen2 open a stream, with flush support
270 .It fwide set/get orientation of a stream
271 .It fwopen open a stream
272 .It fwrite binary stream input/output
273 .It getc get next character or word from input stream
274 .It getc_unlocked get next character or word from input stream
275 .It Ta (no implicit locking)
276 .It getchar get next character or word from input stream
277 .It getchar_unlocked get next character or word from input stream
278 .It Ta (no implicit locking)
279 .It getdelim get a delimited record from a stream
280 .It getline get a line from a stream
281 .It gets get a line from a stream
282 .It getw get next character or word from input stream
283 .It getwc get next wide character from input stream
284 .It getwchar get next wide character from input stream
285 .It mkstemp create unique temporary file
286 .It mktemp create unique temporary file
287 .It open_memstream open memory as a stream
288 .It popen open a program as a stream
289 .It popenve open a program as a stream
290 .It pclose close an opened program stream
291 .It perror system error messages
292 .It printf formatted output conversion
293 .It printf_l formatted output conversion
294 .It putc output a character or word to a stream
295 .It putc_unlocked output a character or word to a stream
296 .It Ta (no implicit locking)
297 .It putchar output a character or word to a stream
298 .It putchar_unlocked output a character or word to a stream
299 .It Ta (no implicit locking)
300 .It puts output a line to a stream
301 .It putw output a character or word to a stream
302 .It putwc output a wide character to a stream
303 .It putwchar output a wide character to a stream
304 .It remove remove directory entry
305 .It rewind reposition a stream
306 .It scanf input format conversion
307 .It scanf_l input format conversion
308 .It setbuf stream buffering operations
309 .It setbuffer stream buffering operations
310 .It setlinebuf stream buffering operations
311 .It setvbuf stream buffering operations
312 .It snprintf formatted output conversion
313 .It snprintf_l formatted output conversion
314 .It sprintf formatted output conversion
315 .It sscanf input format conversion
316 .It sscanf_l input format conversion
317 .It strerror system error messages
318 .It sys_errlist system error messages
319 .It sys_nerr system error messages
320 .It tempnam temporary file routines
321 .It tmpfile temporary file routines
322 .It tmpnam temporary file routines
323 .It ungetc un-get character from input stream
324 .It ungetwc un-get wide character from input stream
325 .It vasprintf formatted output conversion with allocation
326 .It vasprintf_l formatted output conversion with allocation
327 .It vdprintf formatted output conversion
328 .It vdprintf_l formatted output conversion
329 .It vfprintf formatted output conversion
330 .It vfprintf_l formatted output conversion
331 .It vfscanf input format conversion
332 .It vfscanf_l input format conversion
333 .It vprintf formatted output conversion
334 .It vprintf_l formatted output conversion
335 .It vscanf input format conversion
336 .It vscanf_l input format conversion
337 .It vsnprintf formatted output conversion
338 .It vsnprintf_l formatted output conversion
339 .It vsprintf formatted output conversion
340 .It vsprintf_l formatted output conversion
341 .It vsscanf input format conversion
342 .It vsscanf_l input format conversion
343 .El
344 .Sh BUGS
345 The standard buffered functions do not interact well with certain other
346 library and system functions, especially
347 .Xr vfork 2
348 and
349 .Xr abort 3 .