stdio.h@ 78782

Last change on this file since 78782 was 58459, checked in by vboxsync, 9 years ago
EFI/Firmware: 'svn merge ^{/vendor/edk2/UDK2010.SR1}/vendor/edk2/current .', reverting and removing files+dirs listed in ReadMe.vbox, resolving conflicts with help from ../UDK2014.SP1/. This is a raw untested merge.
Property svn:eol-style set to `native`
File size: 80.0 KB

Line
1	/** @file
2	Macros, types, and functions for performing I/O.
3
4	The following functions are declared in this file:<BR>
5	@verbatim
6	################### Operations on files. ####
7	int remove (const char *FileName);
8	int rename (const char , const char );
9	FILE *tmpfile (void);
10	char tmpnam (char );
11
12	################### File access functions. ####
13	int fclose (FILE *);
14	int fflush (FILE *);
15	FILE fopen (const char __restrict ,
16	const char * __restrict);
17	FILE freopen (const char __restrict,
18	const char * __restrict, FILE * __restrict);
19	void setbuf (FILE * __restrict, char * __restrict);
20	int setvbuf (FILE * __restrict, char * __restrict,
21	int, size_t);
22
23	################### Formatted Input/Output Functions. ####
24	int fprintf (FILE * __restrict stream,
25	const char * __restrict format, ...);
26	int fscanf (FILE * __restrict, const char * __restrict, ...);
27	int printf (const char * __restrict, ...);
28	int scanf (const char * __restrict, ...);
29	int sprintf (char * __restrict, const char * __restrict, ...);
30	int sscanf (const char * __restrict,
31	const char * __restrict, ...);
32	int vfprintf (FILE * __restrict,
33	const char * __restrict, va_list);
34	int vprintf (const char * __restrict, va_list);
35	int vsprintf (char * __restrict,
36	const char * __restrict, va_list);
37
38	################### Character Input/Output Functions. ####
39	int fgetc (FILE *);
40	char fgets (char __restrict, int, FILE * __restrict);
41	int fputc (int, FILE *);
42	int fputs (const char * __restrict, FILE * __restrict);
43	int getc (FILE *);
44	int getchar (void);
45	char gets (char );
46	int putc (int, FILE *);
47	int putchar (int);
48	int puts (const char *);
49	int ungetc (int, FILE *);
50
51	################### Direct Input/Output Functions. ####
52	size_t fread (void * __restrict, size_t, size_t,
53	FILE * __restrict);
54	size_t fwrite (const void * __restrict, size_t, size_t,
55	FILE * __restrict);
56
57	################### File Positioning Functions. ####
58	int fgetpos (FILE * __restrict, fpos_t * __restrict);
59	int fseek (FILE *, long, int);
60	int fsetpos (FILE , const fpos_t );
61	long ftell (FILE *);
62	void rewind (FILE *);
63
64	################### Error-handling Functions. ####
65	void clearerr (FILE *);
66	int feof (FILE *);
67	int ferror (FILE *);
68	void perror (const char *);
69
70	################### Functions NOT specified by C95 ####
71
72	FILE fdopen (int, const char );
73	void flockfile (FILE *);
74	int ftrylockfile (FILE *);
75	void funlockfile (FILE *);
76	int getc_unlocked (FILE *);
77	int getchar_unlocked(void);
78	int putc_unlocked (int, FILE *);
79	int putchar_unlocked(int);
80	int pclose (FILE *);
81	FILE popen (const char , const char *);
82	int snprintf (char * __restrict, size_t,
83	const char * __restrict, ...);
84	int vsnprintf (char * __restrict, size_t,
85	const char * __restrict, va_list);
86	char mkdtemp (char );
87	int mkstemp (char *);
88	char mktemp (char );
89	char tempnam (const char , const char *);
90	int fseeko (FILE *, off_t, int);
91	char fgetln (FILE __restrict, size_t * __restrict);
92	char fparseln (FILE , size_t , size_t , const char[3], int);
93	int fpurge (FILE *);
94	void setbuffer (FILE , char , int);
95	int setlinebuf (FILE *);
96	int vasprintf (char ** __restrict, const char * __restrict,
97	va_list);
98	int vscanf (const char * __restrict, va_list);
99	int vsscanf (const char * __restrict,
100	const char * __restrict, va_list);
101	@endverbatim
102
103	@note To fit things in six character monocase externals, the stdio
104	code uses the prefix `__s' for stdio objects, typically followed
105	by a three-character attempt at a mnemonic.
106
107
108	Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>
109	This program and the accompanying materials are licensed and made available under
110	the terms and conditions of the BSD License that accompanies this distribution.
111	The full text of the license may be found at
112	http://opensource.org/licenses/bsd-license.
113
114	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
115	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
116
117	* Copyright (c) 1990, 1993
118	* The Regents of the University of California. All rights reserved.
119	*
120	* This code is derived from software contributed to Berkeley by
121	* Chris Torek.
122	*
123	* Redistribution and use in source and binary forms, with or without
124	* modification, are permitted provided that the following conditions
125	* are met:
126	* 1. Redistributions of source code must retain the above copyright
127	* notice, this list of conditions and the following disclaimer.
128	* 2. Redistributions in binary form must reproduce the above copyright
129	* notice, this list of conditions and the following disclaimer in the
130	* documentation and/or other materials provided with the distribution.
131	* 3. Neither the name of the University nor the names of its contributors
132	* may be used to endorse or promote products derived from this software
133	* without specific prior written permission.
134	*
135	* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
136	* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
137	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
138	* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
139	* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
140	* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
141	* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
142	* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
143	* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
144	* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
145	* SUCH DAMAGE.
146	*
147	* @(#)stdio.h 8.5 (Berkeley) 4/29/95
148	NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp
149	*/
150	#ifndef _STDIO_H_
151	#define _STDIO_H_
152
153	#include <stdarg.h>
154	#include <limits.h>
155	#include <sys/ansi.h>
156	#include <machine/ansi.h>
157
158	#ifdef _EFI_SIZE_T_
159	/ size_t is the unsigned integer type of the result of the sizeof operator. /
160	typedef _EFI_SIZE_T_ size_t;
161	#undef _EFI_SIZE_T_
162	#undef _BSD_SIZE_T_
163	#endif
164
165	/** @{
166	An object type capable of holding all information necessary to specify any
167	position within a file.
168
169	Each wide-oriented stream has an associated mbstate_t object that stores the
170	current parse state of the stream. A successful call to fgetpos stores a
171	representation of the value of this mbstate_t object as part of the value
172	of the fpos_t object. A later successful call to fsetpos using the same
173	stored fpos_t value restores the value of the associated mbstate_t object
174	as well as the position within the controlled stream.
175
176	This is fairly grotesque, but pure ANSI code must not inspect the
177	innards of an fpos_t anyway. The library internally uses off_t,
178	which we assume is exactly as big as eight chars.
179	**/
180	#if (!defined(_ANSI_SOURCE) && !defined(__STRICT_ANSI__)) \|\| defined(_LIBC)
181	typedef __off_t fpos_t;
182	#else
183	typedef struct __sfpos {
184	__off_t _pos;
185	} fpos_t;
186	#endif
187	/@}/
188
189	/* stdio buffers */
190	struct __sbuf {
191	unsigned char *_base;
192	int _size;
193	};
194
195	/** Structure which holds all the information needed to control a stream or file.
196	*
197	* The following always hold:<BR>
198	*
199	* - if (_flags&(__SLBF\|__SWR)) == (__SLBF\|__SWR),
200	* - _lbfsize is -_bf._size, else _lbfsize is 0
201	* - if _flags&__SRD, _w is 0
202	* - if _flags&__SWR, _r is 0
203	*
204	* This ensures that the getc and putc macros (or inline functions) never
205	* try to write or read from a file that is in `read' or `write' mode.
206	* (Moreover, they can, and do, automatically switch from read mode to
207	* write mode, and back, on "r+" and "w+" files.)
208	*
209	* _lbfsize is used only to make the inline line-buffered output stream
210	* code as compact as possible.
211	*
212	* _ub, _up, and _ur are used when ungetc() pushes back more characters
213	* than fit in the current _bf, or when ungetc() pushes back a character
214	* that does not match the previous one in _bf. When this happens,
215	* _ub._base becomes non-nil (i.e., a stream has ungetc() data iff
216	* _ub._base!=NULL) and _up and _ur save the current values of _p and _r.
217	*
218	*/
219	typedef struct __sFILE {
220	unsigned char _p; /< current position in (some) buffer /
221	int _r; /*< read space left for getc() /
222	int _w; /*< write space left for putc() /
223	unsigned short _flags; /*< flags, below; this FILE is free if 0 /
224	short _file; /*< fileno, if Unix descriptor, else -1 /
225	struct __sbuf _bf; /*< the buffer (at least 1 byte, if !NULL) /
226	int _lbfsize; /*< 0 or -_bf._size, for inline putc /
227
228	/* operations */
229	void _cookie; /< cookie passed to io functions /
230	int (_close)(void );
231	int (_read) (void , char *, int);
232	fpos_t (_seek) (void , fpos_t, int);
233	int (_write)(void , const char *, int);
234
235	/** file extension */
236	struct __sbuf _ext;
237
238	/** @{
239	Separate buffer for long sequences of ungetc().
240	**/
241	unsigned char _up; /< saved _p when _p is doing ungetc data /
242	int _ur; /*< saved _r when _r is counting ungetc data /
243	/@}/
244
245	/* tricks to meet minimum requirements even when malloc() fails */
246	unsigned char _ubuf[3 * MB_LEN_MAX]; /*< guarantee an ungetc() buffer /
247	unsigned char _nbuf[1 * MB_LEN_MAX]; /*< guarantee a getc() buffer /
248
249	/** separate buffer for fgetln() when line crosses buffer boundary */
250	struct __sbuf _lb; /* buffer for fgetln() */
251
252	/* Unix stdio files get aligned to block boundaries on fseek() */
253	int _blksize; /*< stat.st_blksize (may be != _bf._size) /
254	fpos_t _offset; /*< current lseek offset /
255	} FILE;
256
257	__BEGIN_DECLS
258	extern FILE __sF[];
259	__END_DECLS
260
261	#define __SLBF 0x0001 /*< line buffered /
262	#define __SNBF 0x0002 /*< unbuffered /
263	#define __SRD 0x0004 /*< OK to read /
264	#define __SWR 0x0008 /*< OK to write /
265	/* RD and WR are never simultaneously asserted */
266	#define __SRW 0x0010 /*< open for reading & writing /
267	#define __SEOF 0x0020 /*< found EOF /
268	#define __SERR 0x0040 /*< found error /
269	#define __SMBF 0x0080 /*< _buf is from malloc /
270	#define __SAPP 0x0100 /*< fdopen()ed in append mode /
271	#define __SSTR 0x0200 /*< this is an sprintf/snprintf string /
272	#define __SOPT 0x0400 /*< do fseek() optimization /
273	#define __SNPT 0x0800 /*< do not do fseek() optimization /
274	#define __SOFF 0x1000 /*< set iff _offset is in fact correct /
275	#define __SMOD 0x2000 /*< true => fgetln modified _p text /
276	#define __SALC 0x4000 /*< allocate string space dynamically /
277
278	/* The following three definitions are for ANSI C, which took them
279	from System V, which brilliantly took internal interface macros and
280	made them official arguments to setvbuf(), without renaming them.
281	Hence, these ugly _IOxxx names are supposed to appear in user code.
282
283	Although numbered as their counterparts above, the implementation
284	does not rely on this.
285	*/
286	#define _IOFBF 0 /*< setvbuf should set fully buffered /
287	#define _IOLBF 1 /*< setvbuf should set line buffered /
288	#define _IONBF 2 /*< setvbuf should set unbuffered /
289
290	#define BUFSIZ 1024 /*< size of buffer used by setbuf /
291	#define EOF (-1) /*< A constant integer expression indicating end-of-file. /
292
293	/** FOPEN_MAX is a minimum maximum, and is the number of streams that
294	stdio can provide without attempting to allocate further resources
295	(which could fail). Do not use this for anything.
296	*/
297	#define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */
298
299	/** Size needed for an array of char large enough to hold the longest file name string. */
300	#define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */
301
302	/** Size needed for an array of char large enough to hold the file name string
303	generated by the tmpname() function.
304	**/
305	#define L_tmpnam PATH_MAX /* must be == PATH_MAX */
306
307	#ifndef TMP_MAX
308	#define TMP_MAX 308915776 /**< The maximum number of unique file names
309	that can be generated by tmpnam(). **/
310	#endif
311
312	/* Always ensure that these are consistent with <fcntl.h>! */
313	#ifndef SEEK_SET
314	#define SEEK_SET 0 /*< set file offset to offset /
315	#endif
316	#ifndef SEEK_CUR
317	#define SEEK_CUR 1 /*< set file offset to current plus offset /
318	#endif
319	#ifndef SEEK_END
320	#define SEEK_END 2 /*< set file offset to EOF plus offset /
321	#endif
322
323	#define stdin (&__sF[0]) /*< FILE reference for the STanDard INput stream. /
324	#define stdout (&__sF[1]) /*< FILE reference for the STanDard OUTput stream. /
325	#define stderr (&__sF[2]) /*< FILE reference for the STanDard ERRor stream. /
326
327	__BEGIN_DECLS
328	/* Functions defined in C95 standard. ###################################### */
329
330	/* ################ Operations on files. */
331
332	/** Remove (delete) a file.
333
334	@param[in] FileName The path to the file to be removed.
335
336	@retval Zero The operation succeeded.
337	@retval Non-zero The operation failed.
338	**/
339	int remove (const char *FileName);
340
341	/** Rename the file named OldName to NewName.
342
343	@param[in] OldName The name of the existing file to be renamed.
344	@param[in] NewName The new name of the file.
345
346	@retval Zero The operation succeeded.
347	@retval Non-zero The operation failed. OldName still exists and has been unmodified.
348	If OldName does not exist, or a file named NewName already exists,
349	rename() will fail are return a non-zero value.
350	**/
351	int rename (const char OldName, const char NewName);
352
353	/** Create a guaranteed unique temporary file.
354	A binary file is created in the _PATH_TMP directory that is guaranteed to
355	have a unique name. The file will be open for update with mode "wb+" and
356	its FILE pointer returned upon successfull completion. When the file is
357	closed, or when the creating program terminates, the file will be removed.
358
359	@retval NULL The temporary file could not be created.
360	@retval non-NULL The returned value is a pointer to the FILE object
361	associated with the newly created and open temporary file.
362	**/
363	FILE *tmpfile (void);
364
365	/** Generate a string that is a valid file name, in the _PATH_TMP directory, that
366	is not the same as the name of an existing file. The function can potentially
367	generate up to TMP_MAX different strings.
368
369	@param[out] Buffer A pointer to an array of at least L_tmpnam char elements.
370	or NULL. If non-NULL, the tmpnam function writes its
371	result into that array and returns the argument
372	as its value.
373
374	@return If no suitable string can be generated a NULL pointer is returned.
375	Otherwise, if Buffer is NULL, the result is produced in an internal
376	static object and a pointer to that object is returned. If Buffer
377	is non-null, the results are written into the array pointed to by
378	Buffer and Buffer is returned.
379	**/
380	char tmpnam (char Buffer);
381
382	/* ################ File access functions. */
383
384	/** Close the open stream, specified by fp, and de-associate it from any file or device.
385
386	@param[in] fp Pointer to a stream object, of type FILE, associated with a
387	file or device.
388
389	@retval Zero The stream was successfully closed.
390	@retval Non-zero There was an error closing the stream.
391	**/
392	int fclose (FILE *fp);
393
394	/** Empties any buffers associated with the stream specified by fp.
395
396	@param[in] fp Pointer to a stream object, of type FILE, associated with a
397	file or device.
398
399	@retval Zero The stream's buffers were successfully emptied.
400	@retval EOF There was an error writing to the stream.
401	**/
402	int fflush (FILE *fp);
403
404	/** Associates a file, named by Path, with a stream and prepares it for subsequent
405	operations.
406
407	The parameter Mode points to a string specifying behavior characteristics for
408	the opened file. The recognized Mode strings are:
409	- r Open text file for reading.
410	- w Truncate file to zero length or create text file for writing.
411	- a Open or create a text file for writing at end-of-file (append).
412	- rb Open binary file for reading.
413	- wb Truncate file to zero length or create binary file for writing.
414	- ab Open or create a binary file for writing at end-of-file (append).
415	- r+ Open text file for update (reading and writing).
416	- w+ Truncate file to zero length or create text file for update.
417	- a+ Open or create a text file for update, writing at end-of-file.
418	- r+b or rb+ Open binary file for update (reading and writing).
419	- w+b or wb+ Truncate file to zero length or create binary file for update.
420	- a+b or ab+ Open or create a binary file for update, writing at end-of-file.
421
422	Opening a file with read mode fails if the file does not exist.
423
424	Opening a file with append mode causes all writes to the file to be forced to
425	the current end-of-file, regardless of any intervening calls to fseek.
426
427	@param[in] Path The path or name of the file or device to open.
428	@param[in] Mode The mode in which the file is to be opened.
429
430	@return A pointer to a FILE object associated with the opened file is returned
431	if the file was opened successfully. Otherwise, NULL is returned.
432	**/
433	FILE fopen (const char __restrict Path, const char * __restrict Mode);
434
435	/** Closes the file associated with Ofp then opens the file specified by Path and associates it with
436	stream Ofp.
437
438	Any errors that occur when closing Ofp are ignored. The file specified by Path is opened with mode Mode
439	and associated with stream Ofp instead of producing a new stream object.
440
441	If Path is NULL, the mode of the file associated with Ofp is changed to Mode.
442
443	@param[in] Path The path or name of the file or device to open.
444	@param[in] Mode The mode in which the file is to be opened.
445	@param[in] Ofp Pointer to the FILE object to be closed and associated with the new file.
446
447	@return If Path was not able to be opened, or the mode changed, NULL is returned;
448	otherwise Ofp is returned.
449	**/
450	FILE freopen (const char __restrict Path, const char * __restrict Mode, FILE * __restrict Ofp);
451
452	/** Establishes Fully Buffered or Non-buffered mode for a stream, fp, using Buff as the buffer.
453
454	The file associated with fp must have been successfully opened with no operations, other than
455	possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
456
457	If Buff is non-NULL, the stream associated with fp is set to Fully Buffered mode using the
458	array pointed to by Buff as the buffer. The buffer is assumed to be BUFSIZ char long.
459	This is equivalent to calling setvbuf(fp, Buff, _IOFBF, BUFSIZ);
460
461	If Buff is NULL, stream fp is set to Non-buffered mode.
462	This is equivalent to calling setvbuf(fp, NULL, _IONBF, 0);
463
464	@param[in] fp Pointer to the FILE object which will have its buffer set.
465	@param[in] Buff The buffer to use for fp, or NULL.
466	**/
467	void setbuf (FILE * __restrict fp, char * __restrict Buff);
468
469	/** Establishes a buffering mode and buffer for use by operations performed on the file associated with fp.
470
471	The file associated with fp must have been successfully opened with no operations, other than
472	possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
473
474	Parameter BufMode determines how stream fp will be buffered:
475	- _IOFBF causes I/O to be fully buffered.
476	- _IOLBF causes I/O to be line buffered.
477	- _IONBF causes I/O to be unbuffered.
478
479	If Buff is not NULL, it points to an array to be used as an I/O buffer for stream fp. The
480	buffer is set to BufSize char in length. Otherwise, an array of BufSize char is allocated
481	by the setvbuf function if BufMode is not _IONBF.
482
483	It is an error for BufSize to be zero unless BufMode is _IONBF, in which case BufSize is ignored.
484
485	@param[in] fp Pointer to the FILE object which will have its buffer set.
486	@param[in] Buff The buffer to use for fp, or NULL.
487	@param[in] BufMode The buffering mode to use.
488	@param[in] BufSize The size of the buffer to use, specified in char.
489
490	@retval Zero The buffer and mode were established successfully.
491	@retval Non-zero The request can not be honored, or an invalid value for BufMode was given.
492	**/
493	int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, size_t BufSize);
494
495	/* ################ Formatted Input/Output Functions. */
496
497	/** The fprintf function writes output to the stream pointed to by stream,
498	under control of the string pointed to by format that specifies how
499	subsequent arguments are converted for output. If there are insufficient
500	arguments for the format, the behavior is indeterminate. If the format is
501	exhausted while arguments remain, the excess arguments are evaluated
502	(as always) but are otherwise ignored. The fprintf function returns when
503	the end of the format string is encountered.
504
505	The format is interpreted as a multibyte character sequence, beginning and ending
506	in its initial shift state. The format is composed of zero or more directives:
507	ordinary multibyte characters (not %), which are copied unchanged to the
508	output stream; and conversion specifications, each of which results in
509	fetching zero or more subsequent arguments, converting them, if applicable,
510	according to the corresponding conversion specifier, and then writing the
511	result to the output stream.
512
513	Each conversion specification is introduced by the character %. After
514	the %, the following appear in sequence:
515	- Zero or more flags (in any order) that modify the meaning of the
516	conversion specification.
517	- An optional minimum field width. If the converted value has fewer
518	characters than the field width, it is padded with spaces (by default)
519	on the left (or right, if the left adjustment flag, described later,
520	has been given) to the field width. The field width takes the form of
521	an asterisk * (described later) or a nonnegative decimal integer.
522	- An optional precision that gives the minimum number of digits to appear
523	for the d, i, o, u, x, and X conversions, the number of digits to
524	appear after the decimal-point character for e, E, f, and F
525	conversions, the maximum number of significant digits for the g and G
526	conversions, or the maximum number of bytes to be written for s
527	conversions. The precision takes the form of a period (.) followed
528	either by an asterisk * (described later) or by an optional decimal
529	integer; if only the period is specified, the precision is taken as
530	zero. If a precision appears with any other conversion specifier, it
531	is ignored.
532	- An optional length modifier that specifies the size of the argument.
533	- A conversion specifier character that specifies the type of conversion
534	to be applied.
535
536	As noted above, a field width, or precision, or both, may be indicated by
537	an asterisk. In this case, an int argument supplies the field width or
538	precision. The arguments specifying field width, or precision, or both, shall
539	appear (in that order) before the argument (if any) to be converted. A negative
540	field width argument is taken as a - flag followed by a positive field width.
541	A negative precision argument is interpreted as if the precision were omitted.
542
543	The flag characters and their meanings are:
544	- The result of the conversion is left-justified within the field.
545	(It is right-justified if this flag is not specified.)
546	+ The result of a signed conversion always begins with a plus or
547	minus sign. (It begins with a sign only when a negative value is
548	converted if this flag is not specified.)
549	space If the first character of a signed conversion is not a sign, or
550	if a signed conversion results in no characters, a space is
551	prefixed to the result. If the space and + flags both appear, the
552	space flag is ignored.
553	# The result is converted to an "alternative form".
554	- For o conversion, it increases the precision, if and only if necessary,
555	to force the first digit of the result to be a zero (if the value
556	and precision are both 0, a single 0 is printed).
557	- For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it.
558	- For e, E, f, F, g, and G conversions, the result of converting a
559	floating-point number always contains a decimal-point character,
560	even if no digits follow it. (Normally, a decimal-point character
561	appears in the result of these conversions only if a digit follows
562	it.)
563	- For g and G conversions, trailing zeros are not removed from
564	the result. For other conversions, it is ignored.
565	0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading
566	zeros (following any indication of sign or base) are used to pad to
567	the field width rather than performing space padding, except when
568	converting an infinity or NaN. If the 0 and - flags both appear,
569	the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
570	precision is specified, the 0 flag is ignored.
571
572	The length modifiers and their meanings are:
573	hh Specifies that a following d, i, o, u, x, or X conversion specifier
574	applies to a signed char or unsigned char argument (the argument
575	will have been promoted according to the integer promotions, but
576	its value shall be converted to signed char or unsigned char before
577	printing); or that a following n conversion specifier applies to a
578	pointer to a signed char argument.
579	h Specifies that a following d, i, o, u, x, or X conversion specifier
580	applies to a short int or unsigned short int argument (the argument
581	will have been promoted according to the integer promotions, but
582	its value shall be converted to short int or unsigned short int
583	before printing); or that a following n conversion specifier
584	applies to a pointer to a short int argument.
585	l (ell) Specifies that a following d, i, o, u, x, or X conversion
586	specifier applies to a long int or unsigned long int argument; that
587	a following n conversion specifier applies to a pointer to a long
588	int argument; that a following c conversion specifier applies to a
589	wint_t argument; that a following s conversion specifier applies to
590	a pointer to a wchar_t argument; or has no effect on a following e,
591	E, f, F, g, or G conversion specifier.
592	ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
593	specifier applies to a long long int or unsigned long long int
594	argument; or that a following n conversion specifier applies to a
595	pointer to a long long int argument.
596	j Specifies that a following d, i, o, u, x, or X conversion specifier
597	applies to an intmax_t or uintmax_t argument; or that a following n
598	conversion specifier applies to a pointer to an intmax_t argument.
599	z Specifies that a following d, i, o, u, x, or X conversion specifier
600	applies to a size_t or the corresponding signed integer type
601	argument; or that a following n conversion specifier applies to a
602	pointer to a signed integer type corresponding to size_t argument.
603	t Specifies that a following d, i, o, u, x, or X conversion specifier
604	applies to a ptrdiff_t or the corresponding unsigned integer type
605	argument; or that a following n conversion specifier applies to a
606	pointer to a ptrdiff_t argument.
607	L Specifies that a following e, E, f, F, g, or G conversion specifier
608	applies to a long double argument.
609
610	If a length modifier appears with any conversion specifier other than as
611	specified above, it is ignored.
612
613	The conversion specifiers and their meanings are:
614	d,i The int argument is converted to signed decimal in the style
615	[-]dddd. The precision specifies the minimum number of digits to
616	appear; if the value being converted can be represented in fewer
617	digits, it is expanded with leading zeros. The default precision
618	is 1. The result of converting a zero value with a precision of
619	zero is no characters.
620	o,u,x,X The unsigned int argument is converted to unsigned octal (o),
621	unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
622	the style dddd; the letters abcdef are used for x conversion and
623	the letters ABCDEF for X conversion. The precision specifies the
624	minimum number of digits to appear; if the value being converted
625	can be represented in fewer digits, it is expanded with leading
626	zeros. The default precision is 1. The result of converting a zero
627	value with a precision of zero is no characters.
628	f,F A double argument representing a floating-point number is
629	converted to decimal notation in the style [-]ddd.ddd, where the
630	number of digits after the decimal-point character is equal to the
631	precision specification. If the precision is missing, it is taken
632	as 6; if the precision is zero and the # flag is not specified, no
633	decimal-point character appears. If a decimal-point character
634	appears, at least one digit appears before it. The value is rounded
635	to the appropriate number of digits.
636	A double argument representing an infinity is converted in
637	the style [-]inf. A double argument representing a NaN is
638	converted in the style [-]nan. The F conversion specifier produces INF,
639	INFINITY, or NAN instead of inf, infinity, or nan, respectively.
640	e,E A double argument representing a floating-point number is
641	converted in the style [-]d.ddd e[+-]dd, where there is one digit
642	(which is nonzero if the argument is nonzero) before the
643	decimal-point character and the number of digits after it is equal
644	to the precision; if the precision is missing, it is taken as 6; if
645	the precision is zero and the # flag is not specified, no
646	decimal-point character appears. The value is rounded to the
647	appropriate number of digits. The E conversion specifier produces a
648	number with E instead of e introducing the exponent. The exponent
649	always contains at least two digits, and only as many more digits
650	as necessary to represent the exponent. If the value is zero, the
651	exponent is zero.
652	A double argument representing an infinity or NaN is converted
653	in the style of an f or F conversion specifier.
654	g,G A double argument representing a floating-point number is
655	converted in style f or e (or in style F or E in the case of a G
656	conversion specifier), depending on the value converted and the
657	precision. Let P equal the precision if nonzero, 6 if the precision
658	is omitted, or 1 if the precision is zero. Then, if a conversion
659	with style E would have an exponent of X:
660	- if P > X = -4, the conversion is with style f (or F) and
661	precision P - (X + 1).
662	- otherwise, the conversion is with style e (or E) and
663	precision P - 1.
664
665	Finally, unless the # flag is used, any trailing zeros are removed
666	from the fractional portion of the result and the decimal-point
667	character is removed if there is no fractional portion remaining.
668	A double argument representing an infinity or NaN is converted in
669	the style of an f or F conversion specifier.
670	c If no l length modifier is present, the int argument is
671	converted to an unsigned char, and the resulting character is
672	written. If an l length modifier is present, the wint_t argument is
673	converted as if by an ls conversion specification with no precision
674	and an argument that points to the initial element of a two-element
675	array of wchar_t, the first element containing the wint_t argument
676	to the lc conversion specification and the second a null wide
677	character.
678	s If no l length modifier is present, the argument is a pointer
679	to the initial element of an array of character type. Characters
680	from the array are written up to (but not including) the
681	terminating null character. If the precision is specified, no more
682	than that many bytes are written. If the precision is not specified
683	or is greater than the size of the array, the array shall contain a
684	null character.
685	If an l length modifier is present, the argument shall be a
686	pointer to the initial element of an array of wchar_t type. Wide
687	characters from the array are converted to multibyte characters
688	(each as if by a call to the wcrtomb function, with the conversion
689	state described by an mbstate_t object initialized to zero before
690	the first wide character is converted) up to and including a
691	terminating null wide character. The resulting multibyte characters
692	are written up to (but not including) the terminating null
693	character (byte). If no precision is specified, the array shall
694	contain a null wide character. If a precision is specified, no more
695	than that many bytes are written (including shift sequences, if
696	any), and the array shall contain a null wide character if, to
697	equal the multibyte character sequence length given by the
698	precision, the function would need to access a wide character one
699	past the end of the array. In no case is a partial multibyte
700	character written.
701	p The argument shall be a pointer to void. The value of the
702	pointer is converted to a sequence of printing characters.
703	n The argument shall be a pointer to signed integer into which is
704	written the number of characters written to the output stream so
705	far by this call to fprintf. No argument is converted, but one is
706	consumed. If the conversion specification includes any flags, a
707	field width, or a precision, they will be ignored.
708	% A % character is written. No argument is converted. The
709	complete conversion specification shall be %%.
710
711	In no case does a nonexistent or small field width cause truncation of a
712	field; if the result of a conversion is wider than the field width, the
713	field is expanded to contain the conversion result.
714
715	@param[in] stream An open File specifier to which the output is sent.
716	@param[in] format A multi-byte character sequence containing characters
717	to be copied unchanged, and conversion specifiers
718	which convert their associated arguments.
719	@param ... Variable number of parameters as required by format.
720
721	@return The fprintf function returns the number of characters
722	transmitted, or a negative value if an output or encoding
723	error occurred.
724	**/
725	int fprintf (FILE * __restrict stream, const char * __restrict format, ...);
726
727	/** Reads characters from stream, under control of format, storing the converted values
728	in variables pointed to by the variable-length parameter list.
729
730	The format is interpreted as a multibyte character sequence, beginning and ending
731	in its initial shift state. The format is composed of zero or more directives:
732	one or more white-space characters, an ordinary multibyte character
733	(neither % nor a white-space character), or a conversion specification.
734
735	Each conversion specification is introduced by the character %. After
736	the %, the following appear in sequence:
737	- An optional assignment-suppressing character, *.
738	- An optional decimal integer, greater than zero, that specifies the
739	maximum field width (in characters).
740	- An optional length modifier that specifies the size of the receiving object.
741	- A conversion specifier character that specifies the type of conversion
742	to be applied.
743
744	The fscanf function executes each directive of the format in turn. If a directive fails, as
745	detailed below, the function returns. Failures are described as input failures (due to the
746	occurrence of an encoding error or the unavailability of input characters), or matching
747	failures (due to inappropriate input).
748
749	A directive composed of white-space character(s) is executed by reading input up to the
750	first non-white-space character (which remains unread), or until no more characters can
751	be read.
752
753	A directive that is an ordinary multibyte character is executed by reading the next
754	characters of the stream. If any of those characters differ from the ones composing the
755	directive, the directive fails and the differing and subsequent characters remain unread.
756	Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
757	read, the directive fails.
758
759	The length modifiers and their meanings are:
760	- hh Specifies that a following d, i, o, u, x, X, or n conversion
761	specifier applies to an argument with type pointer to signed
762	char or unsigned char.
763	- h Specifies that a following d, i, o, u, x, X, or n conversion
764	specifier applies to an argument with type pointer to short
765	int or unsigned short int.
766	- l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
767	specifier applies to an argument with type pointer to
768	long int or unsigned long int; that a following a, A, e,
769	E, f, F, g, or G conversion specifier applies to an
770	argument with type pointer to double; or that a following
771	c, s, or [ conversion specifier applies to an argument
772	with type pointer to wchar_t.
773	- ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
774	specifier applies to an argument with type pointer to
775	long long int or unsigned long long int.
776	- j Specifies that a following d, i, o, u, x, X, or n conversion
777	specifier applies to an argument with type pointer to
778	intmax_t or uintmax_t.
779	- z Specifies that a following d, i, o, u, x, X, or n conversion
780	specifier applies to an argument with type pointer to
781	size_t or the corresponding signed integer type.
782	- t Specifies that a following d, i, o, u, x, X, or n conversion
783	specifier applies to an argument with type pointer to
784	ptrdiff_t or the corresponding unsigned integer type.
785	- L Specifies that a following e, E, f, F, g, or G
786	conversion specifier applies to an argument with type
787	pointer to long double.
788
789	If a length modifier appears with any conversion specifier other than as specified above,
790	it will be ignored.
791
792	The conversion specifiers and their meanings are:
793	- d Matches an optionally signed decimal integer, whose format is
794	the same as expected for the subject sequence of the strtol
795	function with the value 10 for the base argument. The
796	corresponding argument shall be a pointer to signed integer.
797	- i Matches an optionally signed integer, whose format is the same
798	as expected for the subject sequence of the strtol function
799	with the value 0 for the base argument. The corresponding
800	argument shall be a pointer to signed integer.
801	- o Matches an optionally signed octal integer, whose format is the
802	same as expected for the subject sequence of the strtoul
803	function with the value 8 for the base argument. The
804	corresponding argument shall be a pointer to unsigned integer.
805	- u Matches an optionally signed decimal integer, whose format is
806	the same as expected for the subject sequence of the strtoul
807	function with the value 10 for the base argument. The
808	corresponding argument shall be a pointer to unsigned integer.
809	- x Matches an optionally signed hexadecimal integer, whose format
810	is the same as expected for the subject sequence of the strtoul
811	function with the value 16 for the base argument. The
812	corresponding argument shall be a pointer to unsigned integer.
813	- e,f,g Matches an optionally signed floating-point number, infinity,
814	or NaN, whose format is the same as expected for the subject
815	sequence of the strtod function. The corresponding argument
816	shall be a pointer to floating.
817	- c Matches a sequence of characters of exactly the number
818	specified by the field width (1 if no field width is present
819	in the directive). If no l length modifier is present, the
820	corresponding argument shall be a pointer to the initial
821	element of a character array large enough to accept the
822	sequence. No null character is added.<BR><BR>
823	If an l length modifier is present, the input shall be a
824	sequence of multibyte characters that begins in the initial
825	shift state. Each multibyte character in the sequence is
826	converted to a wide character as if by a call to the mbrtowc
827	function, with the conversion state described by an mbstate_t
828	object initialized to zero before the first multibyte character
829	is converted. The corresponding argument shall be a pointer to
830	the initial element of an array of wchar_t large enough to
831	accept the resulting sequence of wide characters. No null wide
832	character is added.
833	- s Matches a sequence of non-white-space characters.
834	If no l length modifier is present, the corresponding argument
835	shall be a pointer to the initial element of a character array
836	large enough to accept the sequence and a terminating null
837	character, which will be added automatically. If an l length
838	modifier is present, the input shall be a sequence of multibyte
839	characters that begins in the initial shift state. Each
840	multibyte character is converted to a wide character as if by a
841	call to the mbrtowc function, with the conversion state
842	described by an mbstate_t object initialized to zero before the
843	first multibyte character is converted. The corresponding
844	argument shall be a pointer to the initial element of an array
845	of wchar_t large enough to accept the sequence and the
846	terminating null wide character, which will be added automatically.
847	- [ Matches a nonempty sequence of characters from a set of
848	expected characters (the scanset).<BR><BR>
849	If no l length modifier is present, the corresponding argument
850	shall be a pointer to the initial element of a character array
851	large enough to accept the sequence and a terminating null
852	character, which will be added automatically. If an l length
853	modifier is present, the input shall be a sequence of multibyte
854	characters that begins in the initial shift state. Each
855	multibyte character is converted to a wide character as if by a
856	call to the mbrtowc function, with the conversion state
857	described by an mbstate_t object initialized to zero before the
858	first multibyte character is converted. The corresponding
859	argument shall be a pointer to the initial element of an array
860	of wchar_t large enough to accept the sequence and the
861	terminating null wide character, which will be added
862	automatically.<BR><BR>
863	The conversion specifier includes all subsequent characters in
864	the format string, up to and including the matching right
865	bracket (]). The characters between the brackets (the scanlist)
866	compose the scanset, unless the character after the left
867	bracket is a circumflex (^), in which case the scanset contains
868	all characters that do not appear in the scanlist between the
869	circumflex and the right bracket. If the conversion specifier
870	begins with [] or [^], the right bracket character is in the
871	scanlist and the next following right bracket character is the
872	matching right bracket that ends the specification; otherwise
873	the first following right bracket character is the one that
874	ends the specification. If a - character is in the scanlist and
875	is not the first, nor the second where the first character is
876	a ^, nor the last character, it will be treated as a regular character.
877	- p Matches a set of sequences, which are the same as the set of
878	sequences that are produced by the %p conversion of the fprintf
879	function. The corresponding argument must be a pointer to a
880	pointer to void. The input item is converted to a pointer value.
881	If the input item is a value converted earlier during the same
882	program execution, the pointer that results will compare equal
883	to that value; otherwise the behavior of the %p conversion is
884	indeterminate.
885	- n No input is consumed. The corresponding argument shall be a
886	pointer to signed integer into which is to be written the
887	number of characters read from the input stream so far by this
888	call to the fscanf function. Execution of a %n directive does
889	not increment the assignment count returned at the completion
890	of execution of the fscanf function. No argument is converted,
891	but one is consumed. If the conversion specification includes
892	an assignment suppressing character the conversion specification
893	is ignored. If the conversion specification contains a
894	field width, the field width will be ignored.
895	- % Matches a single % character; no conversion or assignment occurs.
896
897	@param[in] stream An open File specifier from which the input is read.
898	@param[in] format A multi-byte character sequence containing characters
899	to be matched against, and conversion specifiers
900	which convert their associated arguments. Converted
901	items are stored according to their associated arguments.
902	@param ... Variable number of parameters, as required by format,
903	specifying the objects to receive the converted input.
904
905	@return The fscanf function returns EOF if an input failure occurs before
906	any conversion. Otherwise the number of input items assigned
907	is returned; which can be fewer than provided for, or even zero
908	in the event of an early matching failure.
909	**/
910	int fscanf (FILE * __restrict stream, const char * __restrict format, ...);
911
912	/** Formatted print to stdout.
913
914	The printf function is equivalent to fprintf with stdout used as the output stream.
915
916	@param[in] format A multi-byte character sequence containing characters
917	to be copied unchanged, and conversion specifiers
918	which convert their associated arguments. Copied and
919	converted characters are sent to the output stream.
920	@param ... Variable number of parameters as required by format.
921
922	@return The printf function returns the number of characters
923	transmitted, or a negative value if an output or encoding
924	error occurred.
925	**/
926	int printf (const char * __restrict format, ...);
927
928	/** Formatted input from stdin.
929
930	The scanf function is equivalent to fscanf with stdin used as the input stream.
931
932	@param[in] format A multi-byte character sequence containing characters
933	to be matched against, and conversion specifiers
934	which convert their associated arguments. Converted
935	items are stored according to their associated arguments.
936	@param[out] ... Variable number of parameters, as required by format,
937	specifying the objects to receive the converted input.
938
939	@return The scanf function returns EOF if an input failure occurs before
940	any conversion. Otherwise the number of input items assigned
941	is returned; which can be fewer than provided for, or even zero
942	in the event of an early matching failure.
943	**/
944	int scanf (const char * __restrict format, ...);
945
946	/** Formatted output to a buffer.
947
948	The sprintf function is equivalent to fprintf, except that the output is
949	written into array Buff instead of to a stream. A null character is written
950	at the end of the characters written; it is not counted as part of the
951	returned value.
952
953	@param[out] Buff A pointer to the array to receive the formatted output.
954	@param[in] Format A multi-byte character sequence containing characters
955	to be copied unchanged, and conversion specifiers
956	which convert their associated arguments. Copied and
957	converted characters are written to the array pointed
958	to by Buff.
959	@param ... Variable number of parameters as required by format.
960
961	@return The sprintf function returns the number of characters written in
962	the array, not counting the terminating null character, or a
963	negative value if an encoding error occurred.
964	**/
965	int sprintf (char * __restrict Buff, const char * __restrict Format, ...);
966
967	/** Formatted input from a string.
968
969	The sscanf function is equivalent to fscanf, except that input is obtained
970	from a string rather than from a stream. Reaching the end of the string
971	is equivalent to encountering end-of-file for the fscanf function.
972
973	@param[in] Buff Pointer to the string from which to obtain input.
974	@param[in] Format A multi-byte character sequence containing characters
975	to be matched against, and conversion specifiers
976	which convert their associated arguments. Converted
977	items are stored according to their associated arguments.
978	@param[out] ... Variable number of parameters, as required by format,
979	specifying the objects to receive the converted input.
980
981	@return The scanf function returns EOF if an input failure occurs before
982	any conversion. Otherwise the number of input items assigned
983	is returned; which can be fewer than provided for, or even zero
984	in the event of an early matching failure.
985	**/
986	int sscanf (const char * __restrict Buff, const char * __restrict Format, ...);
987
988	/** Print formatted values from an argument list.
989
990	The vfprintf function is equivalent to fprintf, with the variable argument
991	list replaced by Args, which must have been initialized by the va_start macro.
992	The vfprintf function does not invoke the va_end macro.
993
994	@param[in] Stream The output stream to receive the formatted output.
995	@param[in] Format A multi-byte character sequence containing characters
996	to be matched against, and conversion specifiers
997	which convert their associated arguments. Converted
998	items are stored according to their associated arguments.
999	@param[in] Args A list of arguments, initialized by the va_start macro
1000	and accessed using the va_arg macro, used to satisfy
1001	the directives in the Format string.
1002
1003	@return The vfprintf function returns the number of characters transmitted,
1004	or a negative value if an output or encoding error occurred.
1005	**/
1006	int vfprintf(FILE * __restrict Stream, const char * __restrict Format, va_list Args);
1007
1008	/** Formatted print, to stdout, from an argument list.
1009
1010	The vprintf function is equivalent to printf, with the variable argument
1011	list replaced by Args, which must have been initialized by the va_start
1012	macro (and possibly subsequent va_arg calls). The vprintf function does
1013	not invoke the va_end macro.
1014
1015	@param[in] Format A multi-byte character sequence containing characters
1016	to be matched against, and conversion specifiers
1017	which convert their associated arguments. Converted
1018	items are stored according to their associated arguments.
1019	@param[in] Args A list of arguments, initialized by the va_start macro
1020	and accessed using the va_arg macro, used to satisfy
1021	the directives in the Format string.
1022
1023	@return The vprintf function returns the number of characters transmitted,
1024	or a negative value if an output or encoding error occurred.
1025	**/
1026	int vprintf (const char * __restrict Format, va_list Args);
1027
1028	/** Formatted print, to a buffer, from an argument list.
1029
1030	The vsprintf function is equivalent to sprintf, with the variable argument
1031	list replaced by Args, which must have been initialized by the va_start
1032	macro. The vsprintf function does not invoke the va_end macro.
1033
1034	@param[out] Buff A pointer to the array to receive the formatted output.
1035	@param[in] Format A multi-byte character sequence containing characters
1036	to be copied unchanged, and conversion specifiers
1037	which convert their associated arguments. Copied and
1038	converted characters are written to the array pointed
1039	to by Buff.
1040	@param[in] Args A list of arguments, initialized by the va_start macro
1041	and accessed using the va_arg macro, used to satisfy
1042	the directives in the Format string.
1043
1044	@return The vsprintf function returns the number of characters written in
1045	the array, not counting the terminating null character, or a
1046	negative value if an encoding error occurred.
1047	**/
1048	int vsprintf(char * __restrict Buff, const char * __restrict Format, va_list Args);
1049
1050	/* ################ Character Input/Output Functions. */
1051
1052	/** Get a character from an input Stream.
1053
1054	If the end-of-file indicator for the input stream pointed to by Stream is
1055	not set, and a next character is present, the fgetc function obtains that
1056	character as an unsigned char converted to an int and advances the
1057	associated file position indicator for the stream.
1058
1059	@param[in] Stream An input stream from which to obtain a character.
1060
1061	@return If the end-of-file indicator for the stream is set, or if the
1062	stream is at end-of-file, the end-of-file indicator for the
1063	stream is set and the fgetc function returns EOF. Otherwise,
1064	the fgetc function returns the next character from the input
1065	stream pointed to by Stream. If a read error occurs, the
1066	error indicator for the stream is set and the fgetc function
1067	returns EOF.
1068	**/
1069	int fgetc (FILE *Stream);
1070
1071	/** Read a string from an input stream into a buffer.
1072
1073	The fgets function reads at most one less than the number of characters
1074	specified by Limit from the stream pointed to by Stream into the array
1075	pointed to by Buff. No additional characters are read after a
1076	new-line character (which is retained) or after end-of-file. A null
1077	character is written immediately after the last character read into the array.
1078
1079	@param[out] Buff A pointer to the array to receive the input string.
1080	@param[in] Limit The maximum number of characters to put into Buff,
1081	including the terminating null character.
1082	@param[in] Stream An input stream from which to obtain a character.
1083
1084	@return The fgets function returns Buff if successful. If end-of-file is
1085	encountered and no characters have been read into the array, the
1086	contents of the array remain unchanged and a null pointer is
1087	returned. If a read error occurs during the operation, the array
1088	contents are indeterminate and a null pointer is returned.
1089	**/
1090	char fgets (char __restrict Buff, int Limit, FILE * __restrict Stream);
1091
1092	/** Write a character to an output stream.
1093
1094	The fputc function writes the character specified by C (converted to an
1095	unsigned char) to the output stream pointed to by Stream, at the position
1096	indicated by the associated file position indicator for the stream
1097	(if defined), and advances the indicator appropriately. If the file cannot
1098	support positioning requests, or if the stream was opened with append mode,
1099	the character is appended to the output stream.
1100
1101	@param[in] C The character to be written to Stream.
1102	@param[in] Stream The output stream that C is to be written to.
1103
1104	@return The fputc function returns the character written. If a write
1105	error occurs, the error indicator for the stream is set and
1106	fputc returns EOF.
1107	**/
1108	int fputc (int C, FILE *Stream);
1109
1110	/** Write a string to an output stream.
1111
1112	The fputs function writes String to the stream pointed to by Stream. The
1113	terminating null character is not written.
1114
1115	@param[in] String The character string to be written to Stream.
1116	@param[in] Stream The output stream that String is to be written to.
1117
1118	@return The fputs function returns EOF if a write error occurs; otherwise
1119	it returns a non-negative value.
1120	**/
1121	int fputs (const char * __restrict String, FILE * __restrict Stream);
1122
1123	/** Get a character from an input stream.
1124
1125	The getc function is equivalent to fgetc, except that if it is implemented
1126	as a macro, it may evaluate stream more than once, so the argument should
1127	never be an expression with side effects.
1128
1129	@param[in] Stream An input stream from which to obtain a character.
1130
1131	@return If the end-of-file indicator for the stream is set, or if the
1132	stream is at end-of-file, the end-of-file indicator for the
1133	stream is set and getc returns EOF. Otherwise, getc returns
1134	the next character from the input stream pointed to by Stream.
1135	If a read error occurs, the error indicator for the stream is set
1136	and getc returns EOF.
1137	**/
1138	int getc (FILE *);
1139
1140	/** Get a character from stdin.
1141
1142	The getchar function is equivalent to getc with the argument stdin.
1143
1144	@return If the end-of-file indicator for stdin is set, or if stdin
1145	is at end-of-file, the end-of-file indicator is set and getchar
1146	returns EOF. Otherwise, getchar returns the next character from
1147	stdin. If a read error occurs, the error indicator for stdin is
1148	set and getchar returns EOF.
1149	**/
1150	int getchar (void);
1151
1152	/** Read a string from stdin into a buffer.
1153
1154	The gets function reads characters from the input stream pointed to by
1155	stdin, into the array pointed to by Buff, until end-of-file is encountered
1156	or a new-line character is read. Any new-line character is discarded, and
1157	a null character is written immediately after the last character read into
1158	the array.
1159
1160	@param[out] Buff A pointer to the array to receive the input string.
1161
1162	@return The gets function returns Buff if successful. If end-of-file is
1163	encountered and no characters have been read into the array, the
1164	contents of the array remain unchanged and a null pointer is
1165	returned. If a read error occurs during the operation, the array
1166	contents are indeterminate and a null pointer is returned.
1167	**/
1168	char gets (char Buff);
1169
1170	/** Write a character to an output stream.
1171
1172	The putc function is equivalent to fputc, except that if it is implemented
1173	as a macro, it may evaluate Stream more than once, so that argument should
1174	never be an expression with side effects.
1175
1176	@param[in] C The character to be written to Stream.
1177	@param[in] Stream The output stream that C is to be written to.
1178
1179	@return The putc function returns the character written. If a write
1180	error occurs, the error indicator for the stream is set and
1181	putc returns EOF.
1182	**/
1183	int putc (int C, FILE *Stream);
1184
1185	/** Write a character to stdout.
1186
1187	The putchar function is equivalent to putc with stdout as the Stream argument.
1188
1189	@param[in] C The character to be written to stdout.
1190
1191	@return The putchar function returns the character written. If a write
1192	error occurs, the error indicator for stdout is set and putchar
1193	returns EOF.
1194	**/
1195	int putchar (int C);
1196
1197	/** Write String to stdout.
1198
1199	The puts function writes the string pointed to by String to the stream
1200	pointed to by stdout, and appends a new-line character to the output. The
1201	terminating null character is not written.
1202
1203	@param[in] String A pointer to the character string to write to stdout.
1204
1205	@return The puts function returns EOF if a write error occurs; otherwise
1206	it returns a non-negative value.
1207	**/
1208	int puts (const char *String);
1209
1210	/** Return a character to the input Stream as if it had not been read.
1211
1212	The ungetc function pushes the character specified by C (converted to an
1213	unsigned char) back onto the input stream pointed to by Stream. Pushed-back
1214	characters will be returned by subsequent reads on that stream in the
1215	reverse order of their being pushed. A successful intervening call
1216	(with the stream pointed to by Stream) to a file positioning function
1217	(fseek, fsetpos, or rewind) discards any pushed-back characters for the
1218	stream. The external storage corresponding to the stream is unchanged.
1219
1220	One character of pushback is guaranteed. If the ungetc function is called
1221	too many times on the same stream without an intervening read or file
1222	positioning operation on that stream, the operation will fail.
1223
1224	If the value of C equals that of the macro EOF, the operation fails and the
1225	input stream is unchanged.
1226
1227	A successful call to the ungetc function clears the end-of-file indicator
1228	for the stream. The value of the file position indicator for the stream
1229	after reading or discarding all pushed-back characters is the same as it
1230	was before the characters were pushed back. For a binary stream, its
1231	file position indicator is decremented by each successful call to the
1232	ungetc function; if its value was zero before a call, it will remain zero
1233	after the call.
1234
1235	@param[in] C The character to push back onto the Stream.
1236	@param[in] Stream The output stream that C is to be pushed back onto.
1237
1238	@return The ungetc function returns the character pushed back,
1239	or EOF if the operation fails.
1240	**/
1241	int ungetc (int C, FILE *Stream);
1242
1243	/* ################ Direct Input/Output Functions. */
1244
1245	/** Read Num elements of size Size from a Stream into a Buffer.
1246
1247	The fread function reads, into the array pointed to by Buffer, up to Num
1248	elements, whose size is specified by Size, from the stream pointed to by
1249	Stream. For each object, Size calls are made to the fgetc function and the
1250	results stored, in the order read, in an array of unsigned char exactly
1251	overlaying the Buffer object. The file position indicator for the stream
1252	(if defined) is advanced by the number of characters successfully read. If
1253	an error occurs, the resulting value of the file position indicator for the
1254	stream is indeterminate.
1255
1256	@param[out] Buffer Pointer to an object to receive the read data.
1257	@param[in] Size Size of each element to be read.
1258	@param[in] Num Number of elements to read.
1259	@param[in] Stream Input stream to read the data from.
1260
1261	@return The fread function returns the number of elements successfully
1262	read, which may be less than Num if a read error or end-of-file
1263	is encountered. If Size or Num is zero, fread returns zero and
1264	the contents of the array and the state of the stream remain
1265	unchanged.
1266	**/
1267	size_t fread (void * __restrict Buffer,
1268	size_t Size,
1269	size_t Num,
1270	FILE * __restrict Stream
1271	);
1272
1273	/** Write Num elements of size Size from Buffer to Stream.
1274
1275	The fwrite function writes, from the array pointed to by Buffer, up to Num
1276	elements whose size is specified by Size, to the stream pointed to by
1277	Stream. For each object, Size calls are made to the fputc function, taking
1278	the values (in order) from an array of unsigned char exactly overlaying the
1279	Buffer object. The file position indicator for the stream (if defined) is
1280	advanced by the number of characters successfully written. If an error
1281	occurs, the resulting value of the file position indicator for the stream is
1282	indeterminate.
1283
1284	@param[out] Buffer Pointer to an object containing the data to be written.
1285	@param[in] Size Size of each element to be written.
1286	@param[in] Num Number of elements to write.
1287	@param[in] Stream Output stream to write the data to.
1288
1289	@return The fwrite function returns the number of elements successfully
1290	written, which will be less than Num only if a write error is
1291	encountered. If Size or Num is zero, fwrite returns zero and
1292	the state of the stream remains unchanged.
1293	**/
1294	size_t fwrite (const void * __restrict Buffer,
1295	size_t Size,
1296	size_t Num,
1297	FILE * __restrict Stream
1298	);
1299
1300	/* ################ File Positioning Functions. */
1301
1302	/** Get a stream's position and parse state.
1303
1304	The fgetpos function stores the current values of the parse state (if any)
1305	and file position indicator for the stream pointed to by Stream in the
1306	object pointed to by Pos. The values stored contain unspecified
1307	information usable by the fsetpos function for repositioning the stream
1308	to its position at the time of the call to the fgetpos function.
1309
1310	@param[in] Stream Stream to get current position of.
1311	@param[out] Pos Object to receive the stream's state and position information.
1312
1313	@return If successful, the fgetpos function returns zero; if either
1314	parameter is NULL, the fgetpos function returns nonzero and
1315	stores EINVAL in errno.
1316	**/
1317	int fgetpos (FILE * __restrict Stream, fpos_t * __restrict Pos);
1318
1319	/** Set the file position for a stream.
1320
1321	The fseek function sets the file position indicator for the stream pointed
1322	to by Stream. If a read or write error occurs, the error indicator for the
1323	stream is set and fseek fails.
1324
1325	For a binary stream, the new position, measured in characters from the
1326	beginning of the file, is obtained by adding Offset to the position
1327	specified by Whence. The specified position is the beginning of the file if
1328	Whence is SEEK_SET, the current value of the file position indicator if
1329	SEEK_CUR, or end-of-file if SEEK_END.
1330
1331	For a text stream, Offset must either be zero or a value returned by an
1332	earlier successful call to the ftell function, on a stream associated with
1333	the same file, and Whence must be SEEK_SET.
1334
1335	After determining the new position, a successful call to the fseek function
1336	undoes any effects of the ungetc function on the stream, clears the
1337	end-of-file indicator for the stream, and then establishes the new position.
1338	After a successful fseek call, the next operation on an update stream may
1339	be either input or output.
1340
1341	@param[in] Stream The I/O stream to set the position of.
1342	@param[in] Offset The position, interpreted depending upon the value of
1343	Whence, that the stream is to be positioned to.
1344	@param[in] Whence A value indicating how Offset is to be interpreted:
1345	- SEEK_SET indicates Offset is an absolute position.
1346	- SEEK_END indicates Offset is relative to the end of the file.
1347	- SEEK_CUR indicates Offset is relative to the current position.
1348
1349	@return The fseek function returns nonzero only for a request that cannot be satisfied.
1350	**/
1351	int fseek (FILE *Stream, long Offset, int Whence);
1352
1353	/** Set a stream's position and parse state.
1354
1355	The fsetpos function sets the mbstate_t object (if any) and file position
1356	indicator for the stream pointed to by Stream according to the value of the
1357	object pointed to by Pos, which is a value that was obtained from an
1358	earlier successful call to the fgetpos function on a stream associated with
1359	the same file. If a read or write error occurs, the error indicator for the
1360	stream is set and fsetpos fails.
1361
1362	A successful call to the fsetpos function undoes any effects of the ungetc
1363	function on the stream, clears the end-of-file indicator for the stream,
1364	and then establishes the new parse state and position. After a successful
1365	fsetpos call, the next operation on an update stream may be either input or output.
1366
1367	@param[in] Stream Stream to set current position of.
1368	@param[in] Pos Object containing the state and position information.
1369
1370	@return If successful, the fsetpos function returns zero; on failure, the
1371	fsetpos function returns nonzero and stores EINVAL, or ESPIPE,
1372	in errno; depending upon whether the error was because of an invalid
1373	parameter, or because Stream is not seekable.
1374	**/
1375	int fsetpos (FILE Stream, const fpos_t Pos);
1376
1377	/** Get Stream's current position.
1378
1379	The ftell function obtains the current value of the file position indicator
1380	for the stream pointed to by Stream. For a binary stream, the value is the
1381	number of characters from the beginning of the file. For a text stream, its
1382	file position indicator contains unspecified information, usable by the
1383	fseek function for returning the file position indicator for the stream to
1384	its position at the time of the ftell call; the difference between two such
1385	return values is not necessarily a meaningful measure of the number of
1386	characters written or read.
1387
1388	@param[in] Stream Pointer to the FILE object to get the current position of.
1389
1390	@return If successful, the ftell function returns the current value of
1391	the file position indicator for the stream. On failure, the
1392	ftell function returns -1L and stores ESPIPE in errno indicating
1393	that the stream is not seekable.
1394	**/
1395	long ftell (FILE *Stream);
1396
1397	/** Restore a Stream's file position to the beginning of the file.
1398
1399	The rewind function sets the file position indicator for the stream pointed
1400	to by Stream to the beginning of the file and clears the stream's error indicator.
1401
1402	@param[in] Stream Pointer to the stream to be positioned to its beginning.
1403	**/
1404	void rewind (FILE *Stream);
1405
1406	/* ################ Error-handling Functions. */
1407
1408	/** Clear a Stream's error and end-of-file indicators.
1409
1410	@param[in] Stream Pointer to the stream to be cleared of errors.
1411	**/
1412	void clearerr(FILE *Stream);
1413
1414	/** Test the end-of-file indicator for Stream.
1415
1416	@param[in] Stream Pointer to the FILE object to be tested for EOF.
1417
1418	@return The feof function returns non-zero if, and only if, the end-of-file
1419	indicator is set for Stream.
1420	**/
1421	int feof (FILE *Stream);
1422
1423	/** Test the error indicator for Stream.
1424
1425	@param[in] Stream Pointer to the stream to be tested for error.
1426
1427	@return The ferror function returns non-zero if, and only if, the error
1428	indicator is set for Stream.
1429	**/
1430	int ferror (FILE *Stream);
1431
1432	/** Print an error message to stderr based upon the value of errno and String.
1433
1434	The perror function maps the error number in the integer expression errno
1435	to an error message. It writes a sequence of characters to the standard
1436	error stream thus: first (if String is not a null pointer and the character
1437	pointed to by String is not the null character), the string pointed to by
1438	String followed by a colon (:) and a space; then an appropriate error
1439	message string followed by a new-line character. The contents of the error
1440	message strings are the same as those returned by the strerror function
1441	with argument errno.
1442
1443	@param[in] String A text string to prefix the output error message with.
1444
1445	@sa strerror in <string.h>
1446	**/
1447	void perror (const char *String);
1448
1449	__END_DECLS
1450
1451	/*
1452	* IEEE Std 1003.1-90
1453	*/
1454	__BEGIN_DECLS
1455	FILE fdopen(int, const char );
1456	__END_DECLS
1457
1458	/*
1459	* IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2
1460	*/
1461	__BEGIN_DECLS
1462	void flockfile (FILE *);
1463	int ftrylockfile (FILE *);
1464	void funlockfile (FILE *);
1465	int getc_unlocked (FILE *);
1466	int getchar_unlocked(void);
1467	int putc_unlocked (int, FILE *);
1468	int putchar_unlocked(int);
1469	__END_DECLS
1470
1471	/*
1472	* Functions defined in POSIX 1003.2 and XPG2 or later.
1473	*/
1474	__BEGIN_DECLS
1475	int pclose (FILE *);
1476	FILE popen (const char , const char *);
1477	__END_DECLS
1478
1479	/*
1480	* Functions defined in ISO XPG4.2, ISO C99, POSIX 1003.1-2001 or later.
1481	*/
1482	__BEGIN_DECLS
1483	int snprintf (char * __restrict, size_t, const char * __restrict, ...)
1484	__attribute__((__format__(__printf__, 3, 4)));
1485	int vsnprintf(char * __restrict, size_t, const char * __restrict, va_list)
1486	__attribute__((__format__(__printf__, 3, 0)));
1487	__END_DECLS
1488
1489	/*
1490	* Functions defined in XPG4.2.
1491	*/
1492	__BEGIN_DECLS
1493	//int getw(FILE *);
1494	//int putw(int, FILE *);
1495	char mkdtemp(char );
1496	int mkstemp(char *);
1497	char mktemp(char );
1498
1499	char tempnam(const char , const char *);
1500	__END_DECLS
1501
1502	/*
1503	* X/Open CAE Specification Issue 5 Version 2
1504	*/
1505	#ifndef off_t
1506	typedef __off_t off_t;
1507	#define off_t __off_t
1508	#endif /* off_t */
1509
1510	__BEGIN_DECLS
1511	int fseeko(FILE *, off_t, int);
1512	off_t ftello(FILE *);
1513	__END_DECLS
1514
1515	/*
1516	* Routines that are purely local.
1517	*/
1518	#define FPARSELN_UNESCESC 0x01
1519	#define FPARSELN_UNESCCONT 0x02
1520	#define FPARSELN_UNESCCOMM 0x04
1521	#define FPARSELN_UNESCREST 0x08
1522	#define FPARSELN_UNESCALL 0x0f
1523
1524	__BEGIN_DECLS
1525	//int asprintf(char ** __restrict, const char * __restrict, ...)
1526	// __attribute__((__format__(__printf__, 2, 3)));
1527	char fgetln(FILE __restrict, size_t * __restrict);
1528	char fparseln(FILE , size_t , size_t , const char[3], int);
1529	int fpurge(FILE *);
1530	void setbuffer(FILE , char , int);
1531	int setlinebuf(FILE *);
1532	int vasprintf(char ** __restrict, const char * __restrict,
1533	va_list)
1534	__attribute__((__format__(__printf__, 2, 0)));
1535	int vscanf(const char * __restrict, va_list)
1536	__attribute__((__format__(__scanf__, 1, 0)));
1537	//int vfscanf(FILE * __restrict, const char * __restrict,
1538	// va_list)
1539	// __attribute__((__format__(__scanf__, 2, 0)));
1540	int vsscanf(const char * __restrict, const char * __restrict,
1541	va_list)
1542	__attribute__((__format__(__scanf__, 2, 0)));
1543	//const char fmtcheck(const char , const char *)
1544	// __attribute__((__format_arg__(2)));
1545	__END_DECLS
1546
1547	/*
1548	* Stdio function-access interface.
1549	*/
1550	__BEGIN_DECLS
1551	FILE funopen(const void ,
1552	int ()(void , char *, int),
1553	int ()(void , const char *, int),
1554	fpos_t ()(void , fpos_t, int),
1555	int ()(void ));
1556	__END_DECLS
1557	//#define fropen(cookie, fn) funopen(cookie, fn, 0, 0, 0)
1558	//#define fwopen(cookie, fn) funopen(cookie, 0, fn, 0, 0)
1559
1560	/*
1561	* Functions internal to the implementation.
1562	*/
1563	__BEGIN_DECLS
1564	int __srget(FILE *);
1565	int __swbuf(int, FILE *);
1566	__END_DECLS
1567
1568	/*
1569	* The __sfoo macros are here so that we can
1570	* define function versions in the C library.
1571	*/
1572	#define __sgetc(p) (--(p)->_r < 0 ? __srget(p) : (int)(*(p)->_p++))
1573
1574	#if defined(__GNUC__) && defined(__STDC__)
1575	static __inline int __sputc(int _c, FILE *_p) {
1576	if (--_p->_w >= 0 \|\| (_p->_w >= _p->_lbfsize && (char)_c != '\n'))
1577	return (*_p->_p++ = _c);
1578	else
1579	return (__swbuf(_c, _p));
1580	}
1581	#else
1582	/*
1583	* This has been tuned to generate reasonable code on the vax using pcc.
1584	*/
1585	#define __sputc(c, p) \
1586	(--(p)->_w < 0 ? \
1587	(p)->_w >= (p)->_lbfsize ? \
1588	((p)->_p = (unsigned char)(c)), (p)->_p != '\n' ? \
1589	(int)*(p)->_p++ : \
1590	__swbuf('\n', p) : \
1591	__swbuf((int)(c), p) : \
1592	((p)->_p = (unsigned char)(c), (int)(p)->_p++))
1593	#endif
1594
1595	#define __sfeof(p) (((p)->_flags & __SEOF) != 0)
1596	#define __sferror(p) (((p)->_flags & __SERR) != 0)
1597	#define __sclearerr(p) ((void)((p)->_flags &= ~(__SERR\|__SEOF)))
1598	#define __sfileno(p) ((p)->_file)
1599
1600	#ifndef __lint__
1601	#define feof(p) __sfeof(p)
1602	#define ferror(p) __sferror(p)
1603	#define clearerr(p) __sclearerr(p)
1604
1605	#define getc(fp) __sgetc(fp)
1606	#define putc(x, fp) __sputc(x, fp)
1607	#endif /* __lint__ */
1608
1609	#define getchar() getc(stdin)
1610	#define putchar(x) putc(x, stdout)
1611
1612	#define fileno(p) __sfileno(p)
1613
1614	#define getc_unlocked(fp) __sgetc(fp)
1615	#define putc_unlocked(x, fp) __sputc(x, fp)
1616
1617	#define getchar_unlocked() getc_unlocked(stdin)
1618	#define putchar_unlocked(x) putc_unlocked(x, stdout)
1619
1620	#endif /* _STDIO_H_ */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/StdLib/Include/stdio.h@ 78782

Download in other formats: