Google Git
Sign in
fuchsia / third_party / edk2 / refs/tags/vUDK2018 / . / StdLib / Include / stdio.h
blob: c0a4deb7837eaeca1ab64edd8d7d8975fe28dad6 [file] [log] [blame]
/** @file
Macros, types, and functions for performing I/O.
The following functions are declared in this file:<BR>
@verbatim
################### Operations on files. ####
int remove (const char *FileName);
int rename (const char *, const char *);
FILE *tmpfile (void);
char *tmpnam (char *);
################### File access functions. ####
int fclose (FILE *);
int fflush (FILE *);
FILE *fopen (const char * __restrict ,
const char * __restrict);
FILE *freopen (const char * __restrict,
const char * __restrict, FILE * __restrict);
void setbuf (FILE * __restrict, char * __restrict);
int setvbuf (FILE * __restrict, char * __restrict,
int, size_t);
################### Formatted Input/Output Functions. ####
int fprintf (FILE * __restrict stream,
const char * __restrict format, ...);
int fscanf (FILE * __restrict, const char * __restrict, ...);
int printf (const char * __restrict, ...);
int scanf (const char * __restrict, ...);
int sprintf (char * __restrict, const char * __restrict, ...);
int sscanf (const char * __restrict,
const char * __restrict, ...);
int vfprintf (FILE * __restrict,
const char * __restrict, va_list);
int vprintf (const char * __restrict, va_list);
int vsprintf (char * __restrict,
const char * __restrict, va_list);
################### Character Input/Output Functions. ####
int fgetc (FILE *);
char *fgets (char * __restrict, int, FILE * __restrict);
int fputc (int, FILE *);
int fputs (const char * __restrict, FILE * __restrict);
int getc (FILE *);
int getchar (void);
char *gets (char *);
int putc (int, FILE *);
int putchar (int);
int puts (const char *);
int ungetc (int, FILE *);
################### Direct Input/Output Functions. ####
size_t fread (void * __restrict, size_t, size_t,
FILE * __restrict);
size_t fwrite (const void * __restrict, size_t, size_t,
FILE * __restrict);
################### File Positioning Functions. ####
int fgetpos (FILE * __restrict, fpos_t * __restrict);
int fseek (FILE *, long, int);
int fsetpos (FILE *, const fpos_t *);
long ftell (FILE *);
void rewind (FILE *);
################### Error-handling Functions. ####
void clearerr (FILE *);
int feof (FILE *);
int ferror (FILE *);
void perror (const char *);
################### Functions NOT specified by C95 ####
FILE *fdopen (int, const char *);
void flockfile (FILE *);
int ftrylockfile (FILE *);
void funlockfile (FILE *);
int getc_unlocked (FILE *);
int getchar_unlocked(void);
int putc_unlocked (int, FILE *);
int putchar_unlocked(int);
int pclose (FILE *);
FILE *popen (const char *, const char *);
int snprintf (char * __restrict, size_t,
const char * __restrict, ...);
int vsnprintf (char * __restrict, size_t,
const char * __restrict, va_list);
char *mkdtemp (char *);
int mkstemp (char *);
char *mktemp (char *);
char *tempnam (const char *, const char *);
int fseeko (FILE *, off_t, int);
char *fgetln (FILE * __restrict, size_t * __restrict);
char *fparseln (FILE *, size_t *, size_t *, const char[3], int);
int fpurge (FILE *);
void setbuffer (FILE *, char *, int);
int setlinebuf (FILE *);
int vasprintf (char ** __restrict, const char * __restrict,
va_list);
int vscanf (const char * __restrict, va_list);
int vsscanf (const char * __restrict,
const char * __restrict, va_list);
@endverbatim
@note To fit things in six character monocase externals, the stdio
code uses the prefix `__s' for stdio objects, typically followed
by a three-character attempt at a mnemonic.
Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
*
* This code is derived from software contributed to Berkeley by
* Chris Torek.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* @(#)stdio.h 8.5 (Berkeley) 4/29/95
NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp
*/
#ifndef _STDIO_H_
#define _STDIO_H_
#include <stdarg.h>
#include <limits.h>
#include <sys/ansi.h>
#include <machine/ansi.h>
#ifdef _EFI_SIZE_T_
/** size_t is the unsigned integer type of the result of the sizeof operator. **/
typedef _EFI_SIZE_T_ size_t;
#undef _EFI_SIZE_T_
#undef _BSD_SIZE_T_
#endif
/** @{
An object type capable of holding all information necessary to specify any
position within a file.
Each wide-oriented stream has an associated mbstate_t object that stores the
current parse state of the stream. A successful call to fgetpos stores a
representation of the value of this mbstate_t object as part of the value
of the fpos_t object. A later successful call to fsetpos using the same
stored fpos_t value restores the value of the associated mbstate_t object
as well as the position within the controlled stream.
This is fairly grotesque, but pure ANSI code must not inspect the
innards of an fpos_t anyway. The library internally uses off_t,
which we assume is exactly as big as eight chars.
**/
#if (!defined(_ANSI_SOURCE) && !defined(__STRICT_ANSI__)) || defined(_LIBC)
typedef __off_t fpos_t;
#else
typedef struct __sfpos {
__off_t _pos;
} fpos_t;
#endif
/*@}*/
/* stdio buffers */
struct __sbuf {
unsigned char *_base;
int _size;
};
/** Structure which holds all the information needed to control a stream or file.
*
* The following always hold:<BR>
*
* - if (_flags&(__SLBF|__SWR)) == (__SLBF|__SWR),
* - _lbfsize is -_bf._size, else _lbfsize is 0
* - if _flags&__SRD, _w is 0
* - if _flags&__SWR, _r is 0
*
* This ensures that the getc and putc macros (or inline functions) never
* try to write or read from a file that is in `read' or `write' mode.
* (Moreover, they can, and do, automatically switch from read mode to
* write mode, and back, on "r+" and "w+" files.)
*
* _lbfsize is used only to make the inline line-buffered output stream
* code as compact as possible.
*
* _ub, _up, and _ur are used when ungetc() pushes back more characters
* than fit in the current _bf, or when ungetc() pushes back a character
* that does not match the previous one in _bf. When this happens,
* _ub._base becomes non-nil (i.e., a stream has ungetc() data iff
* _ub._base!=NULL) and _up and _ur save the current values of _p and _r.
*
*/
typedef struct __sFILE {
unsigned char *_p; /**< current position in (some) buffer */
int _r; /**< read space left for getc() */
int _w; /**< write space left for putc() */
unsigned short _flags; /**< flags, below; this FILE is free if 0 */
short _file; /**< fileno, if Unix descriptor, else -1 */
struct __sbuf _bf; /**< the buffer (at least 1 byte, if !NULL) */
int _lbfsize; /**< 0 or -_bf._size, for inline putc */
/* operations */
void *_cookie; /**< cookie passed to io functions */
int (*_close)(void *);
int (*_read) (void *, char *, int);
fpos_t (*_seek) (void *, fpos_t, int);
int (*_write)(void *, const char *, int);
/** file extension */
struct __sbuf _ext;
/** @{
Separate buffer for long sequences of ungetc().
**/
unsigned char *_up; /**< saved _p when _p is doing ungetc data */
int _ur; /**< saved _r when _r is counting ungetc data */
/*@}*/
/* tricks to meet minimum requirements even when malloc() fails */
unsigned char _ubuf[3 * MB_LEN_MAX]; /**< guarantee an ungetc() buffer */
unsigned char _nbuf[1 * MB_LEN_MAX]; /**< guarantee a getc() buffer */
/** separate buffer for fgetln() when line crosses buffer boundary */
struct __sbuf _lb; /* buffer for fgetln() */
/* Unix stdio files get aligned to block boundaries on fseek() */
int _blksize; /**< stat.st_blksize (may be != _bf._size) */
fpos_t _offset; /**< current lseek offset */
} FILE;
__BEGIN_DECLS
extern FILE __sF[];
__END_DECLS
#define __SLBF 0x0001 /**< line buffered */
#define __SNBF 0x0002 /**< unbuffered */
#define __SRD 0x0004 /**< OK to read */
#define __SWR 0x0008 /**< OK to write */
/* RD and WR are never simultaneously asserted */
#define __SRW 0x0010 /**< open for reading & writing */
#define __SEOF 0x0020 /**< found EOF */
#define __SERR 0x0040 /**< found error */
#define __SMBF 0x0080 /**< _buf is from malloc */
#define __SAPP 0x0100 /**< fdopen()ed in append mode */
#define __SSTR 0x0200 /**< this is an sprintf/snprintf string */
#define __SOPT 0x0400 /**< do fseek() optimization */
#define __SNPT 0x0800 /**< do not do fseek() optimization */
#define __SOFF 0x1000 /**< set iff _offset is in fact correct */
#define __SMOD 0x2000 /**< true => fgetln modified _p text */
#define __SALC 0x4000 /**< allocate string space dynamically */
/* The following three definitions are for ANSI C, which took them
from System V, which brilliantly took internal interface macros and
made them official arguments to setvbuf(), without renaming them.
Hence, these ugly _IOxxx names are *supposed* to appear in user code.
Although numbered as their counterparts above, the implementation
does not rely on this.
*/
#define _IOFBF 0 /**< setvbuf should set fully buffered */
#define _IOLBF 1 /**< setvbuf should set line buffered */
#define _IONBF 2 /**< setvbuf should set unbuffered */
#define BUFSIZ 1024 /**< size of buffer used by setbuf */
#define EOF (-1) /**< A constant integer expression indicating end-of-file. */
/** FOPEN_MAX is a minimum maximum, and is the number of streams that
stdio can provide without attempting to allocate further resources
(which could fail). Do not use this for anything.
*/
#define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */
/** Size needed for an array of char large enough to hold the longest file name string. */
#define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */
/** Size needed for an array of char large enough to hold the file name string
generated by the tmpname() function.
**/
#define L_tmpnam PATH_MAX /* must be == PATH_MAX */
#ifndef TMP_MAX
#define TMP_MAX 308915776 /**< The maximum number of unique file names
that can be generated by tmpnam(). **/
#endif
/* Always ensure that these are consistent with <fcntl.h>! */
#ifndef SEEK_SET
#define SEEK_SET 0 /**< set file offset to offset */
#endif
#ifndef SEEK_CUR
#define SEEK_CUR 1 /**< set file offset to current plus offset */
#endif
#ifndef SEEK_END
#define SEEK_END 2 /**< set file offset to EOF plus offset */
#endif
#define stdin (&__sF[0]) /**< FILE reference for the STanDard INput stream. */
#define stdout (&__sF[1]) /**< FILE reference for the STanDard OUTput stream. */
#define stderr (&__sF[2]) /**< FILE reference for the STanDard ERRor stream. */
__BEGIN_DECLS
/* Functions defined in C95 standard. ###################################### */
/* ################ Operations on files. */
/** Remove (delete) a file.
@param[in] FileName The path to the file to be removed.
@retval Zero The operation succeeded.
@retval Non-zero The operation failed.
**/
int remove (const char *FileName);
/** Rename the file named OldName to NewName.
@param[in] OldName The name of the existing file to be renamed.
@param[in] NewName The new name of the file.
@retval Zero The operation succeeded.
@retval Non-zero The operation failed. OldName still exists and has been unmodified.
If OldName does not exist, or a file named NewName already exists,
rename() will fail are return a non-zero value.
**/
int rename (const char *OldName, const char *NewName);
/** Create a guaranteed unique temporary file.
A binary file is created in the _PATH_TMP directory that is guaranteed to
have a unique name. The file will be open for update with mode "wb+" and
its FILE pointer returned upon successfull completion. When the file is
closed, or when the creating program terminates, the file will be removed.
@retval NULL The temporary file could not be created.
@retval non-NULL The returned value is a pointer to the FILE object
associated with the newly created and open temporary file.
**/
FILE *tmpfile (void);
/** Generate a string that is a valid file name, in the _PATH_TMP directory, that
is not the same as the name of an existing file. The function can potentially
generate up to TMP_MAX different strings.
@param[out] Buffer A pointer to an array of at least L_tmpnam char elements.
or NULL. If non-NULL, the tmpnam function writes its
result into that array and returns the argument
as its value.
@return If no suitable string can be generated a NULL pointer is returned.
Otherwise, if Buffer is NULL, the result is produced in an internal
static object and a pointer to that object is returned. If Buffer
is non-null, the results are written into the array pointed to by
Buffer and Buffer is returned.
**/
char *tmpnam (char *Buffer);
/* ################ File access functions. */
/** Close the open stream, specified by fp, and de-associate it from any file or device.
@param[in] fp Pointer to a stream object, of type FILE, associated with a
file or device.
@retval Zero The stream was successfully closed.
@retval Non-zero There was an error closing the stream.
**/
int fclose (FILE *fp);
/** Empties any buffers associated with the stream specified by fp.
@param[in] fp Pointer to a stream object, of type FILE, associated with a
file or device.
@retval Zero The stream's buffers were successfully emptied.
@retval EOF There was an error writing to the stream.
**/
int fflush (FILE *fp);
/** Associates a file, named by Path, with a stream and prepares it for subsequent
operations.
The parameter Mode points to a string specifying behavior characteristics for
the opened file. The recognized Mode strings are:
- r Open text file for reading.
- w Truncate file to zero length or create text file for writing.
- a Open or create a text file for writing at end-of-file (append).
- rb Open binary file for reading.
- wb Truncate file to zero length or create binary file for writing.
- ab Open or create a binary file for writing at end-of-file (append).
- r+ Open text file for update (reading and writing).
- w+ Truncate file to zero length or create text file for update.
- a+ Open or create a text file for update, writing at end-of-file.
- r+b or rb+ Open binary file for update (reading and writing).
- w+b or wb+ Truncate file to zero length or create binary file for update.
- a+b or ab+ Open or create a binary file for update, writing at end-of-file.
Opening a file with read mode fails if the file does not exist.
Opening a file with append mode causes all writes to the file to be forced to
the current end-of-file, regardless of any intervening calls to fseek.
@param[in] Path The path or name of the file or device to open.
@param[in] Mode The mode in which the file is to be opened.
@return A pointer to a FILE object associated with the opened file is returned
if the file was opened successfully. Otherwise, NULL is returned.
**/
FILE *fopen (const char * __restrict Path, const char * __restrict Mode);
/** Closes the file associated with Ofp then opens the file specified by Path and associates it with
stream Ofp.
Any errors that occur when closing Ofp are ignored. The file specified by Path is opened with mode Mode
and associated with stream Ofp instead of producing a new stream object.
If Path is NULL, the mode of the file associated with Ofp is changed to Mode.
@param[in] Path The path or name of the file or device to open.
@param[in] Mode The mode in which the file is to be opened.
@param[in] Ofp Pointer to the FILE object to be closed and associated with the new file.
@return If Path was not able to be opened, or the mode changed, NULL is returned;
otherwise Ofp is returned.
**/
FILE *freopen (const char * __restrict Path, const char * __restrict Mode, FILE * __restrict Ofp);
/** Establishes Fully Buffered or Non-buffered mode for a stream, fp, using Buff as the buffer.
The file associated with fp must have been successfully opened with no operations, other than
possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
If Buff is non-NULL, the stream associated with fp is set to Fully Buffered mode using the
array pointed to by Buff as the buffer. The buffer is assumed to be BUFSIZ char long.
This is equivalent to calling setvbuf(fp, Buff, _IOFBF, BUFSIZ);
If Buff is NULL, stream fp is set to Non-buffered mode.
This is equivalent to calling setvbuf(fp, NULL, _IONBF, 0);
@param[in] fp Pointer to the FILE object which will have its buffer set.
@param[in] Buff The buffer to use for fp, or NULL.
**/
void setbuf (FILE * __restrict fp, char * __restrict Buff);
/** Establishes a buffering mode and buffer for use by operations performed on the file associated with fp.
The file associated with fp must have been successfully opened with no operations, other than
possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
Parameter BufMode determines how stream fp will be buffered:
- _IOFBF causes I/O to be fully buffered.
- _IOLBF causes I/O to be line buffered.
- _IONBF causes I/O to be unbuffered.
If Buff is not NULL, it points to an array to be used as an I/O buffer for stream fp. The
buffer is set to BufSize char in length. Otherwise, an array of BufSize char is allocated
by the setvbuf function if BufMode is not _IONBF.
It is an error for BufSize to be zero unless BufMode is _IONBF, in which case BufSize is ignored.
@param[in] fp Pointer to the FILE object which will have its buffer set.
@param[in] Buff The buffer to use for fp, or NULL.
@param[in] BufMode The buffering mode to use.
@param[in] BufSize The size of the buffer to use, specified in char.
@retval Zero The buffer and mode were established successfully.
@retval Non-zero The request can not be honored, or an invalid value for BufMode was given.
**/
int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, size_t BufSize);
/* ################ Formatted Input/Output Functions. */
/** The fprintf function writes output to the stream pointed to by stream,
under control of the string pointed to by format that specifies how
subsequent arguments are converted for output. If there are insufficient
arguments for the format, the behavior is indeterminate. If the format is
exhausted while arguments remain, the excess arguments are evaluated
(as always) but are otherwise ignored. The fprintf function returns when
the end of the format string is encountered.
The format is interpreted as a multibyte character sequence, beginning and ending
in its initial shift state. The format is composed of zero or more directives:
ordinary multibyte characters (not %), which are copied unchanged to the
output stream; and conversion specifications, each of which results in
fetching zero or more subsequent arguments, converting them, if applicable,
according to the corresponding conversion specifier, and then writing the
result to the output stream.
Each conversion specification is introduced by the character %. After
the %, the following appear in sequence:
- Zero or more flags (in any order) that modify the meaning of the
conversion specification.
- An optional minimum field width. If the converted value has fewer
characters than the field width, it is padded with spaces (by default)
on the left (or right, if the left adjustment flag, described later,
has been given) to the field width. The field width takes the form of
an asterisk * (described later) or a nonnegative decimal integer.
- An optional precision that gives the minimum number of digits to appear
for the d, i, o, u, x, and X conversions, the number of digits to
appear after the decimal-point character for e, E, f, and F
conversions, the maximum number of significant digits for the g and G
conversions, or the maximum number of bytes to be written for s
conversions. The precision takes the form of a period (.) followed
either by an asterisk * (described later) or by an optional decimal
integer; if only the period is specified, the precision is taken as
zero. If a precision appears with any other conversion specifier, it
is ignored.
- An optional length modifier that specifies the size of the argument.
- A conversion specifier character that specifies the type of conversion
to be applied.
As noted above, a field width, or precision, or both, may be indicated by
an asterisk. In this case, an int argument supplies the field width or
precision. The arguments specifying field width, or precision, or both, shall
appear (in that order) before the argument (if any) to be converted. A negative
field width argument is taken as a - flag followed by a positive field width.
A negative precision argument is interpreted as if the precision were omitted.
The flag characters and their meanings are:
- The result of the conversion is left-justified within the field.
(It is right-justified if this flag is not specified.)
+ The result of a signed conversion always begins with a plus or
minus sign. (It begins with a sign only when a negative value is
converted if this flag is not specified.)
space If the first character of a signed conversion is not a sign, or
if a signed conversion results in no characters, a space is
prefixed to the result. If the space and + flags both appear, the
space flag is ignored.
# The result is converted to an "alternative form".
- For o conversion, it increases the precision, if and only if necessary,
to force the first digit of the result to be a zero (if the value
and precision are both 0, a single 0 is printed).
- For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it.
- For e, E, f, F, g, and G conversions, the result of converting a
floating-point number always contains a decimal-point character,
even if no digits follow it. (Normally, a decimal-point character
appears in the result of these conversions only if a digit follows
it.)
- For g and G conversions, trailing zeros are not removed from
the result. For other conversions, it is ignored.
0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading
zeros (following any indication of sign or base) are used to pad to
the field width rather than performing space padding, except when
converting an infinity or NaN. If the 0 and - flags both appear,
the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
precision is specified, the 0 flag is ignored.
The length modifiers and their meanings are:
hh Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a signed char or unsigned char argument (the argument
will have been promoted according to the integer promotions, but
its value shall be converted to signed char or unsigned char before
printing); or that a following n conversion specifier applies to a
pointer to a signed char argument.
h Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a short int or unsigned short int argument (the argument
will have been promoted according to the integer promotions, but
its value shall be converted to short int or unsigned short int
before printing); or that a following n conversion specifier
applies to a pointer to a short int argument.
l (ell) Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a long int or unsigned long int argument; that
a following n conversion specifier applies to a pointer to a long
int argument; that a following c conversion specifier applies to a
wint_t argument; that a following s conversion specifier applies to
a pointer to a wchar_t argument; or has no effect on a following e,
E, f, F, g, or G conversion specifier.
ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a long long int or unsigned long long int
argument; or that a following n conversion specifier applies to a
pointer to a long long int argument.
j Specifies that a following d, i, o, u, x, or X conversion specifier
applies to an intmax_t or uintmax_t argument; or that a following n
conversion specifier applies to a pointer to an intmax_t argument.
z Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a size_t or the corresponding signed integer type
argument; or that a following n conversion specifier applies to a
pointer to a signed integer type corresponding to size_t argument.
t Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a ptrdiff_t or the corresponding unsigned integer type
argument; or that a following n conversion specifier applies to a
pointer to a ptrdiff_t argument.
L Specifies that a following e, E, f, F, g, or G conversion specifier
applies to a long double argument.
If a length modifier appears with any conversion specifier other than as
specified above, it is ignored.
The conversion specifiers and their meanings are:
d,i The int argument is converted to signed decimal in the style
[-]dddd. The precision specifies the minimum number of digits to
appear; if the value being converted can be represented in fewer
digits, it is expanded with leading zeros. The default precision
is 1. The result of converting a zero value with a precision of
zero is no characters.
o,u,x,X The unsigned int argument is converted to unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
the style dddd; the letters abcdef are used for x conversion and
the letters ABCDEF for X conversion. The precision specifies the
minimum number of digits to appear; if the value being converted
can be represented in fewer digits, it is expanded with leading
zeros. The default precision is 1. The result of converting a zero
value with a precision of zero is no characters.
f,F A double argument representing a floating-point number is
converted to decimal notation in the style [-]ddd.ddd, where the
number of digits after the decimal-point character is equal to the
precision specification. If the precision is missing, it is taken
as 6; if the precision is zero and the # flag is not specified, no
decimal-point character appears. If a decimal-point character
appears, at least one digit appears before it. The value is rounded
to the appropriate number of digits.
A double argument representing an infinity is converted in
the style [-]inf. A double argument representing a NaN is
converted in the style [-]nan. The F conversion specifier produces INF,
INFINITY, or NAN instead of inf, infinity, or nan, respectively.
e,E A double argument representing a floating-point number is
converted in the style [-]d.ddd e[+-]dd, where there is one digit
(which is nonzero if the argument is nonzero) before the
decimal-point character and the number of digits after it is equal
to the precision; if the precision is missing, it is taken as 6; if
the precision is zero and the # flag is not specified, no
decimal-point character appears. The value is rounded to the
appropriate number of digits. The E conversion specifier produces a
number with E instead of e introducing the exponent. The exponent
always contains at least two digits, and only as many more digits
as necessary to represent the exponent. If the value is zero, the
exponent is zero.
A double argument representing an infinity or NaN is converted
in the style of an f or F conversion specifier.
g,G A double argument representing a floating-point number is
converted in style f or e (or in style F or E in the case of a G
conversion specifier), depending on the value converted and the
precision. Let P equal the precision if nonzero, 6 if the precision
is omitted, or 1 if the precision is zero. Then, if a conversion
with style E would have an exponent of X:
- if P > X = -4, the conversion is with style f (or F) and
precision P - (X + 1).
- otherwise, the conversion is with style e (or E) and
precision P - 1.
Finally, unless the # flag is used, any trailing zeros are removed
from the fractional portion of the result and the decimal-point
character is removed if there is no fractional portion remaining.
A double argument representing an infinity or NaN is converted in
the style of an f or F conversion specifier.
c If no l length modifier is present, the int argument is
converted to an unsigned char, and the resulting character is
written. If an l length modifier is present, the wint_t argument is
converted as if by an ls conversion specification with no precision
and an argument that points to the initial element of a two-element
array of wchar_t, the first element containing the wint_t argument
to the lc conversion specification and the second a null wide
character.
s If no l length modifier is present, the argument is a pointer
to the initial element of an array of character type. Characters
from the array are written up to (but not including) the
terminating null character. If the precision is specified, no more
than that many bytes are written. If the precision is not specified
or is greater than the size of the array, the array shall contain a
null character.
If an l length modifier is present, the argument shall be a
pointer to the initial element of an array of wchar_t type. Wide
characters from the array are converted to multibyte characters
(each as if by a call to the wcrtomb function, with the conversion
state described by an mbstate_t object initialized to zero before
the first wide character is converted) up to and including a
terminating null wide character. The resulting multibyte characters
are written up to (but not including) the terminating null
character (byte). If no precision is specified, the array shall
contain a null wide character. If a precision is specified, no more
than that many bytes are written (including shift sequences, if
any), and the array shall contain a null wide character if, to
equal the multibyte character sequence length given by the
precision, the function would need to access a wide character one
past the end of the array. In no case is a partial multibyte
character written.
p The argument shall be a pointer to void. The value of the
pointer is converted to a sequence of printing characters.
n The argument shall be a pointer to signed integer into which is
written the number of characters written to the output stream so
far by this call to fprintf. No argument is converted, but one is
consumed. If the conversion specification includes any flags, a
field width, or a precision, they will be ignored.
% A % character is written. No argument is converted. The
complete conversion specification shall be %%.
In no case does a nonexistent or small field width cause truncation of a
field; if the result of a conversion is wider than the field width, the
field is expanded to contain the conversion result.
@param[in] stream An open File specifier to which the output is sent.
@param[in] format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments.
@param ... Variable number of parameters as required by format.
@return The fprintf function returns the number of characters
transmitted, or a negative value if an output or encoding
error occurred.
**/
int fprintf (FILE * __restrict stream, const char * __restrict format, ...);
/** Reads characters from stream, under control of format, storing the converted values
in variables pointed to by the variable-length parameter list.
The format is interpreted as a multibyte character sequence, beginning and ending
in its initial shift state. The format is composed of zero or more directives:
one or more white-space characters, an ordinary multibyte character
(neither % nor a white-space character), or a conversion specification.
Each conversion specification is introduced by the character %. After
the %, the following appear in sequence:
- An optional assignment-suppressing character, *.
- An optional decimal integer, greater than zero, that specifies the
maximum field width (in characters).
- An optional length modifier that specifies the size of the receiving object.
- A conversion specifier character that specifies the type of conversion
to be applied.
The fscanf function executes each directive of the format in turn. If a directive fails, as
detailed below, the function returns. Failures are described as input failures (due to the
occurrence of an encoding error or the unavailability of input characters), or matching
failures (due to inappropriate input).
A directive composed of white-space character(s) is executed by reading input up to the
first non-white-space character (which remains unread), or until no more characters can
be read.
A directive that is an ordinary multibyte character is executed by reading the next
characters of the stream. If any of those characters differ from the ones composing the
directive, the directive fails and the differing and subsequent characters remain unread.
Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
read, the directive fails.
The length modifiers and their meanings are:
- hh Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to signed
char or unsigned char.
- h Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to short
int or unsigned short int.
- l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to
long int or unsigned long int; that a following a, A, e,
E, f, F, g, or G conversion specifier applies to an
argument with type pointer to double; or that a following
c, s, or [ conversion specifier applies to an argument
with type pointer to wchar_t.
- ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to
long long int or unsigned long long int.
- j Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to
intmax_t or uintmax_t.
- z Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to
size_t or the corresponding signed integer type.
- t Specifies that a following d, i, o, u, x, X, or n conversion
specifier applies to an argument with type pointer to
ptrdiff_t or the corresponding unsigned integer type.
- L Specifies that a following e, E, f, F, g, or G
conversion specifier applies to an argument with type
pointer to long double.
If a length modifier appears with any conversion specifier other than as specified above,
it will be ignored.
The conversion specifiers and their meanings are:
- d Matches an optionally signed decimal integer, whose format is
the same as expected for the subject sequence of the strtol
function with the value 10 for the base argument. The
corresponding argument shall be a pointer to signed integer.
- i Matches an optionally signed integer, whose format is the same
as expected for the subject sequence of the strtol function
with the value 0 for the base argument. The corresponding
argument shall be a pointer to signed integer.
- o Matches an optionally signed octal integer, whose format is the
same as expected for the subject sequence of the strtoul
function with the value 8 for the base argument. The
corresponding argument shall be a pointer to unsigned integer.
- u Matches an optionally signed decimal integer, whose format is
the same as expected for the subject sequence of the strtoul
function with the value 10 for the base argument. The
corresponding argument shall be a pointer to unsigned integer.
- x Matches an optionally signed hexadecimal integer, whose format
is the same as expected for the subject sequence of the strtoul
function with the value 16 for the base argument. The
corresponding argument shall be a pointer to unsigned integer.
- e,f,g Matches an optionally signed floating-point number, infinity,
or NaN, whose format is the same as expected for the subject
sequence of the strtod function. The corresponding argument
shall be a pointer to floating.
- c Matches a sequence of characters of exactly the number
specified by the field width (1 if no field width is present
in the directive). If no l length modifier is present, the
corresponding argument shall be a pointer to the initial
element of a character array large enough to accept the
sequence. No null character is added.<BR><BR>
If an l length modifier is present, the input shall be a
sequence of multibyte characters that begins in the initial
shift state. Each multibyte character in the sequence is
converted to a wide character as if by a call to the mbrtowc
function, with the conversion state described by an mbstate_t
object initialized to zero before the first multibyte character
is converted. The corresponding argument shall be a pointer to
the initial element of an array of wchar_t large enough to
accept the resulting sequence of wide characters. No null wide
character is added.
- s Matches a sequence of non-white-space characters.
If no l length modifier is present, the corresponding argument
shall be a pointer to the initial element of a character array
large enough to accept the sequence and a terminating null
character, which will be added automatically. If an l length
modifier is present, the input shall be a sequence of multibyte
characters that begins in the initial shift state. Each
multibyte character is converted to a wide character as if by a
call to the mbrtowc function, with the conversion state
described by an mbstate_t object initialized to zero before the
first multibyte character is converted. The corresponding
argument shall be a pointer to the initial element of an array
of wchar_t large enough to accept the sequence and the
terminating null wide character, which will be added automatically.
- [ Matches a nonempty sequence of characters from a set of
expected characters (the scanset).<BR><BR>
If no l length modifier is present, the corresponding argument
shall be a pointer to the initial element of a character array
large enough to accept the sequence and a terminating null
character, which will be added automatically. If an l length
modifier is present, the input shall be a sequence of multibyte
characters that begins in the initial shift state. Each
multibyte character is converted to a wide character as if by a
call to the mbrtowc function, with the conversion state
described by an mbstate_t object initialized to zero before the
first multibyte character is converted. The corresponding
argument shall be a pointer to the initial element of an array
of wchar_t large enough to accept the sequence and the
terminating null wide character, which will be added
automatically.<BR><BR>
The conversion specifier includes all subsequent characters in
the format string, up to and including the matching right
bracket (]). The characters between the brackets (the scanlist)
compose the scanset, unless the character after the left
bracket is a circumflex (^), in which case the scanset contains
all characters that do not appear in the scanlist between the
circumflex and the right bracket. If the conversion specifier
begins with [] or [^], the right bracket character is in the
scanlist and the next following right bracket character is the
matching right bracket that ends the specification; otherwise
the first following right bracket character is the one that
ends the specification. If a - character is in the scanlist and
is not the first, nor the second where the first character is
a ^, nor the last character, it will be treated as a regular character.
- p Matches a set of sequences, which are the same as the set of
sequences that are produced by the %p conversion of the fprintf
function. The corresponding argument must be a pointer to a
pointer to void. The input item is converted to a pointer value.
If the input item is a value converted earlier during the same
program execution, the pointer that results will compare equal
to that value; otherwise the behavior of the %p conversion is
indeterminate.
- n No input is consumed. The corresponding argument shall be a
pointer to signed integer into which is to be written the
number of characters read from the input stream so far by this
call to the fscanf function. Execution of a %n directive does
not increment the assignment count returned at the completion
of execution of the fscanf function. No argument is converted,
but one is consumed. If the conversion specification includes
an assignment suppressing character the conversion specification
is ignored. If the conversion specification contains a
field width, the field width will be ignored.
- % Matches a single % character; no conversion or assignment occurs.
@param[in] stream An open File specifier from which the input is read.
@param[in] format A multi-byte character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return The fscanf function returns EOF if an input failure occurs before
any conversion. Otherwise the number of input items assigned
is returned; which can be fewer than provided for, or even zero
in the event of an early matching failure.
**/
int fscanf (FILE * __restrict stream, const char * __restrict format, ...);
/** Formatted print to stdout.
The printf function is equivalent to fprintf with stdout used as the output stream.
@param[in] format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments. Copied and
converted characters are sent to the output stream.
@param ... Variable number of parameters as required by format.
@return The printf function returns the number of characters
transmitted, or a negative value if an output or encoding
error occurred.
**/
int printf (const char * __restrict format, ...);
/** Formatted input from stdin.
The scanf function is equivalent to fscanf with stdin used as the input stream.
@param[in] format A multi-byte character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param[out] ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return The scanf function returns EOF if an input failure occurs before
any conversion. Otherwise the number of input items assigned
is returned; which can be fewer than provided for, or even zero
in the event of an early matching failure.
**/
int scanf (const char * __restrict format, ...);
/** Formatted output to a buffer.
The sprintf function is equivalent to fprintf, except that the output is
written into array Buff instead of to a stream. A null character is written
at the end of the characters written; it is not counted as part of the
returned value.
@param[out] Buff A pointer to the array to receive the formatted output.
@param[in] Format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments. Copied and
converted characters are written to the array pointed
to by Buff.
@param ... Variable number of parameters as required by format.
@return The sprintf function returns the number of characters written in
the array, not counting the terminating null character, or a
negative value if an encoding error occurred.
**/
int sprintf (char * __restrict Buff, const char * __restrict Format, ...);
/** Formatted input from a string.
The sscanf function is equivalent to fscanf, except that input is obtained
from a string rather than from a stream. Reaching the end of the string
is equivalent to encountering end-of-file for the fscanf function.
@param[in] Buff Pointer to the string from which to obtain input.
@param[in] Format A multi-byte character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param[out] ... Variable number of parameters, as required by format,
specifying the objects to receive the converted input.
@return The scanf function returns EOF if an input failure occurs before
any conversion. Otherwise the number of input items assigned
is returned; which can be fewer than provided for, or even zero
in the event of an early matching failure.
**/
int sscanf (const char * __restrict Buff, const char * __restrict Format, ...);
/** Print formatted values from an argument list.
The vfprintf function is equivalent to fprintf, with the variable argument
list replaced by Args, which must have been initialized by the va_start macro.
The vfprintf function does not invoke the va_end macro.
@param[in] Stream The output stream to receive the formatted output.
@param[in] Format A multi-byte character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vfprintf function returns the number of characters transmitted,
or a negative value if an output or encoding error occurred.
**/
int vfprintf(FILE * __restrict Stream, const char * __restrict Format, va_list Args);
/** Formatted print, to stdout, from an argument list.
The vprintf function is equivalent to printf, with the variable argument
list replaced by Args, which must have been initialized by the va_start
macro (and possibly subsequent va_arg calls). The vprintf function does
not invoke the va_end macro.
@param[in] Format A multi-byte character sequence containing characters
to be matched against, and conversion specifiers
which convert their associated arguments. Converted
items are stored according to their associated arguments.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vprintf function returns the number of characters transmitted,
or a negative value if an output or encoding error occurred.
**/
int vprintf (const char * __restrict Format, va_list Args);
/** Formatted print, to a buffer, from an argument list.
The vsprintf function is equivalent to sprintf, with the variable argument
list replaced by Args, which must have been initialized by the va_start
macro. The vsprintf function does not invoke the va_end macro.
@param[out] Buff A pointer to the array to receive the formatted output.
@param[in] Format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
which convert their associated arguments. Copied and
converted characters are written to the array pointed
to by Buff.
@param[in] Args A list of arguments, initialized by the va_start macro
and accessed using the va_arg macro, used to satisfy
the directives in the Format string.
@return The vsprintf function returns the number of characters written in
the array, not counting the terminating null character, or a
negative value if an encoding error occurred.
**/
int vsprintf(char * __restrict Buff, const char * __restrict Format, va_list Args);
/* ################ Character Input/Output Functions. */
/** Get a character from an input Stream.
If the end-of-file indicator for the input stream pointed to by Stream is
not set, and a next character is present, the fgetc function obtains that
character as an unsigned char converted to an int and advances the
associated file position indicator for the stream.
@param[in] Stream An input stream from which to obtain a character.
@return If the end-of-file indicator for the stream is set, or if the
stream is at end-of-file, the end-of-file indicator for the
stream is set and the fgetc function returns EOF. Otherwise,
the fgetc function returns the next character from the input
stream pointed to by Stream. If a read error occurs, the
error indicator for the stream is set and the fgetc function
returns EOF.
**/
int fgetc (FILE *Stream);
/** Read a string from an input stream into a buffer.
The fgets function reads at most one less than the number of characters
specified by Limit from the stream pointed to by Stream into the array
pointed to by Buff. No additional characters are read after a
new-line character (which is retained) or after end-of-file. A null
character is written immediately after the last character read into the array.
@param[out] Buff A pointer to the array to receive the input string.
@param[in] Limit The maximum number of characters to put into Buff,
including the terminating null character.
@param[in] Stream An input stream from which to obtain a character.
@return The fgets function returns Buff if successful. If end-of-file is
encountered and no characters have been read into the array, the
contents of the array remain unchanged and a null pointer is
returned. If a read error occurs during the operation, the array
contents are indeterminate and a null pointer is returned.
**/
char *fgets (char * __restrict Buff, int Limit, FILE * __restrict Stream);
/** Write a character to an output stream.
The fputc function writes the character specified by C (converted to an
unsigned char) to the output stream pointed to by Stream, at the position
indicated by the associated file position indicator for the stream
(if defined), and advances the indicator appropriately. If the file cannot
support positioning requests, or if the stream was opened with append mode,
the character is appended to the output stream.
@param[in] C The character to be written to Stream.
@param[in] Stream The output stream that C is to be written to.
@return The fputc function returns the character written. If a write
error occurs, the error indicator for the stream is set and
fputc returns EOF.
**/
int fputc (int C, FILE *Stream);
/** Write a string to an output stream.
The fputs function writes String to the stream pointed to by Stream. The
terminating null character is not written.
@param[in] String The character string to be written to Stream.
@param[in] Stream The output stream that String is to be written to.
@return The fputs function returns EOF if a write error occurs; otherwise
it returns a non-negative value.
**/
int fputs (const char * __restrict String, FILE * __restrict Stream);
/** Get a character from an input stream.
The getc function is equivalent to fgetc, except that if it is implemented
as a macro, it may evaluate stream more than once, so the argument should
never be an expression with side effects.
@param[in] Stream An input stream from which to obtain a character.
@return If the end-of-file indicator for the stream is set, or if the
stream is at end-of-file, the end-of-file indicator for the
stream is set and getc returns EOF. Otherwise, getc returns
the next character from the input stream pointed to by Stream.
If a read error occurs, the error indicator for the stream is set
and getc returns EOF.
**/
int getc (FILE *);
/** Get a character from stdin.
The getchar function is equivalent to getc with the argument stdin.
@return If the end-of-file indicator for stdin is set, or if stdin
is at end-of-file, the end-of-file indicator is set and getchar
returns EOF. Otherwise, getchar returns the next character from
stdin. If a read error occurs, the error indicator for stdin is
set and getchar returns EOF.
**/
int getchar (void);
/** Read a string from stdin into a buffer.
The gets function reads characters from the input stream pointed to by
stdin, into the array pointed to by Buff, until end-of-file is encountered
or a new-line character is read. Any new-line character is discarded, and
a null character is written immediately after the last character read into
the array.
@param[out] Buff A pointer to the array to receive the input string.
@return The gets function returns Buff if successful. If end-of-file is
encountered and no characters have been read into the array, the
contents of the array remain unchanged and a null pointer is
returned. If a read error occurs during the operation, the array
contents are indeterminate and a null pointer is returned.
**/
char *gets (char *Buff);
/** Write a character to an output stream.
The putc function is equivalent to fputc, except that if it is implemented
as a macro, it may evaluate Stream more than once, so that argument should
never be an expression with side effects.
@param[in] C The character to be written to Stream.
@param[in] Stream The output stream that C is to be written to.
@return The putc function returns the character written. If a write
error occurs, the error indicator for the stream is set and
putc returns EOF.
**/
int putc (int C, FILE *Stream);
/** Write a character to stdout.
The putchar function is equivalent to putc with stdout as the Stream argument.
@param[in] C The character to be written to stdout.
@return The putchar function returns the character written. If a write
error occurs, the error indicator for stdout is set and putchar
returns EOF.
**/
int putchar (int C);
/** Write String to stdout.
The puts function writes the string pointed to by String to the stream
pointed to by stdout, and appends a new-line character to the output. The
terminating null character is not written.
@param[in] String A pointer to the character string to write to stdout.
@return The puts function returns EOF if a write error occurs; otherwise
it returns a non-negative value.
**/
int puts (const char *String);
/** Return a character to the input Stream as if it had not been read.
The ungetc function pushes the character specified by C (converted to an
unsigned char) back onto the input stream pointed to by Stream. Pushed-back
characters will be returned by subsequent reads on that stream in the
reverse order of their being pushed. A successful intervening call
(with the stream pointed to by Stream) to a file positioning function
(fseek, fsetpos, or rewind) discards any pushed-back characters for the
stream. The external storage corresponding to the stream is unchanged.
One character of pushback is guaranteed. If the ungetc function is called
too many times on the same stream without an intervening read or file
positioning operation on that stream, the operation will fail.
If the value of C equals that of the macro EOF, the operation fails and the
input stream is unchanged.
A successful call to the ungetc function clears the end-of-file indicator
for the stream. The value of the file position indicator for the stream
after reading or discarding all pushed-back characters is the same as it
was before the characters were pushed back. For a binary stream, its
file position indicator is decremented by each successful call to the
ungetc function; if its value was zero before a call, it will remain zero
after the call.
@param[in] C The character to push back onto the Stream.
@param[in] Stream The output stream that C is to be pushed back onto.
@return The ungetc function returns the character pushed back,
or EOF if the operation fails.
**/
int ungetc (int C, FILE *Stream);
/* ################ Direct Input/Output Functions. */
/** Read Num elements of size Size from a Stream into a Buffer.
The fread function reads, into the array pointed to by Buffer, up to Num
elements, whose size is specified by Size, from the stream pointed to by
Stream. For each object, Size calls are made to the fgetc function and the
results stored, in the order read, in an array of unsigned char exactly
overlaying the Buffer object. The file position indicator for the stream
(if defined) is advanced by the number of characters successfully read. If
an error occurs, the resulting value of the file position indicator for the
stream is indeterminate.
@param[out] Buffer Pointer to an object to receive the read data.
@param[in] Size Size of each element to be read.
@param[in] Num Number of elements to read.
@param[in] Stream Input stream to read the data from.
@return The fread function returns the number of elements successfully
read, which may be less than Num if a read error or end-of-file
is encountered. If Size or Num is zero, fread returns zero and
the contents of the array and the state of the stream remain
unchanged.
**/
size_t fread (void * __restrict Buffer,
size_t Size,
size_t Num,
FILE * __restrict Stream
);
/** Write Num elements of size Size from Buffer to Stream.
The fwrite function writes, from the array pointed to by Buffer, up to Num
elements whose size is specified by Size, to the stream pointed to by
Stream. For each object, Size calls are made to the fputc function, taking
the values (in order) from an array of unsigned char exactly overlaying the
Buffer object. The file position indicator for the stream (if defined) is
advanced by the number of characters successfully written. If an error
occurs, the resulting value of the file position indicator for the stream is
indeterminate.
@param[out] Buffer Pointer to an object containing the data to be written.
@param[in] Size Size of each element to be written.
@param[in] Num Number of elements to write.
@param[in] Stream Output stream to write the data to.
@return The fwrite function returns the number of elements successfully
written, which will be less than Num only if a write error is
encountered. If Size or Num is zero, fwrite returns zero and
the state of the stream remains unchanged.
**/
size_t fwrite (const void * __restrict Buffer,
size_t Size,
size_t Num,
FILE * __restrict Stream
);
/* ################ File Positioning Functions. */
/** Get a stream's position and parse state.
The fgetpos function stores the current values of the parse state (if any)
and file position indicator for the stream pointed to by Stream in the
object pointed to by Pos. The values stored contain unspecified
information usable by the fsetpos function for repositioning the stream
to its position at the time of the call to the fgetpos function.
@param[in] Stream Stream to get current position of.
@param[out] Pos Object to receive the stream's state and position information.
@return If successful, the fgetpos function returns zero; if either
parameter is NULL, the fgetpos function returns nonzero and
stores EINVAL in errno.
**/
int fgetpos (FILE * __restrict Stream, fpos_t * __restrict Pos);
/** Set the file position for a stream.
The fseek function sets the file position indicator for the stream pointed
to by Stream. If a read or write error occurs, the error indicator for the
stream is set and fseek fails.
For a binary stream, the new position, measured in characters from the
beginning of the file, is obtained by adding Offset to the position
specified by Whence. The specified position is the beginning of the file if
Whence is SEEK_SET, the current value of the file position indicator if
SEEK_CUR, or end-of-file if SEEK_END.
For a text stream, Offset must either be zero or a value returned by an
earlier successful call to the ftell function, on a stream associated with
the same file, and Whence must be SEEK_SET.
After determining the new position, a successful call to the fseek function
undoes any effects of the ungetc function on the stream, clears the
end-of-file indicator for the stream, and then establishes the new position.
After a successful fseek call, the next operation on an update stream may
be either input or output.
@param[in] Stream The I/O stream to set the position of.
@param[in] Offset The position, interpreted depending upon the value of
Whence, that the stream is to be positioned to.
@param[in] Whence A value indicating how Offset is to be interpreted:
- SEEK_SET indicates Offset is an absolute position.
- SEEK_END indicates Offset is relative to the end of the file.
- SEEK_CUR indicates Offset is relative to the current position.
@return The fseek function returns nonzero only for a request that cannot be satisfied.
**/
int fseek (FILE *Stream, long Offset, int Whence);
/** Set a stream's position and parse state.
The fsetpos function sets the mbstate_t object (if any) and file position
indicator for the stream pointed to by Stream according to the value of the
object pointed to by Pos, which is a value that was obtained from an
earlier successful call to the fgetpos function on a stream associated with
the same file. If a read or write error occurs, the error indicator for the
stream is set and fsetpos fails.
A successful call to the fsetpos function undoes any effects of the ungetc
function on the stream, clears the end-of-file indicator for the stream,
and then establishes the new parse state and position. After a successful
fsetpos call, the next operation on an update stream may be either input or output.
@param[in] Stream Stream to set current position of.
@param[in] Pos Object containing the state and position information.
@return If successful, the fsetpos function returns zero; on failure, the
fsetpos function returns nonzero and stores EINVAL, or ESPIPE,
in errno; depending upon whether the error was because of an invalid
parameter, or because Stream is not seekable.
**/
int fsetpos (FILE *Stream, const fpos_t *Pos);
/** Get Stream's current position.
The ftell function obtains the current value of the file position indicator
for the stream pointed to by Stream. For a binary stream, the value is the
number of characters from the beginning of the file. For a text stream, its
file position indicator contains unspecified information, usable by the
fseek function for returning the file position indicator for the stream to
its position at the time of the ftell call; the difference between two such
return values is not necessarily a meaningful measure of the number of
characters written or read.
@param[in] Stream Pointer to the FILE object to get the current position of.
@return If successful, the ftell function returns the current value of
the file position indicator for the stream. On failure, the
ftell function returns -1L and stores ESPIPE in errno indicating
that the stream is not seekable.
**/
long ftell (FILE *Stream);
/** Restore a Stream's file position to the beginning of the file.
The rewind function sets the file position indicator for the stream pointed
to by Stream to the beginning of the file and clears the stream's error indicator.
@param[in] Stream Pointer to the stream to be positioned to its beginning.
**/
void rewind (FILE *Stream);
/* ################ Error-handling Functions. */
/** Clear a Stream's error and end-of-file indicators.
@param[in] Stream Pointer to the stream to be cleared of errors.
**/
void clearerr(FILE *Stream);
/** Test the end-of-file indicator for Stream.
@param[in] Stream Pointer to the FILE object to be tested for EOF.
@return The feof function returns non-zero if, and only if, the end-of-file
indicator is set for Stream.
**/
int feof (FILE *Stream);
/** Test the error indicator for Stream.
@param[in] Stream Pointer to the stream to be tested for error.
@return The ferror function returns non-zero if, and only if, the error
indicator is set for Stream.
**/
int ferror (FILE *Stream);
/** Print an error message to stderr based upon the value of errno and String.
The perror function maps the error number in the integer expression errno
to an error message. It writes a sequence of characters to the standard
error stream thus: first (if String is not a null pointer and the character
pointed to by String is not the null character), the string pointed to by
String followed by a colon (:) and a space; then an appropriate error
message string followed by a new-line character. The contents of the error
message strings are the same as those returned by the strerror function
with argument errno.
@param[in] String A text string to prefix the output error message with.
@sa strerror in <string.h>
**/
void perror (const char *String);
__END_DECLS
/*
* IEEE Std 1003.1-90
*/
__BEGIN_DECLS
FILE *fdopen(int, const char *);
__END_DECLS
/*
* IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2
*/
__BEGIN_DECLS
void flockfile (FILE *);
int ftrylockfile (FILE *);
void funlockfile (FILE *);
int getc_unlocked (FILE *);
int getchar_unlocked(void);
int putc_unlocked (int, FILE *);
int putchar_unlocked(int);
__END_DECLS
/*
* Functions defined in POSIX 1003.2 and XPG2 or later.
*/
__BEGIN_DECLS
int pclose (FILE *);
FILE *popen (const char *, const char *);
__END_DECLS
/*
* Functions defined in ISO XPG4.2, ISO C99, POSIX 1003.1-2001 or later.
*/
__BEGIN_DECLS
int snprintf (char * __restrict, size_t, const char * __restrict, ...)
__attribute__((__format__(__printf__, 3, 4)));
int vsnprintf(char * __restrict, size_t, const char * __restrict, va_list)
__attribute__((__format__(__printf__, 3, 0)));
__END_DECLS
/*
* Functions defined in XPG4.2.
*/
__BEGIN_DECLS
//int getw(FILE *);
//int putw(int, FILE *);
char *mkdtemp(char *);
int mkstemp(char *);
char *mktemp(char *);
char *tempnam(const char *, const char *);
__END_DECLS
/*
* X/Open CAE Specification Issue 5 Version 2
*/
#ifndef off_t
typedef __off_t off_t;
#define off_t __off_t
#endif /* off_t */
__BEGIN_DECLS
int fseeko(FILE *, off_t, int);
off_t ftello(FILE *);
__END_DECLS
/*
* Routines that are purely local.
*/
#define FPARSELN_UNESCESC 0x01
#define FPARSELN_UNESCCONT 0x02
#define FPARSELN_UNESCCOMM 0x04
#define FPARSELN_UNESCREST 0x08
#define FPARSELN_UNESCALL 0x0f
__BEGIN_DECLS
//int asprintf(char ** __restrict, const char * __restrict, ...)
// __attribute__((__format__(__printf__, 2, 3)));
char *fgetln(FILE * __restrict, size_t * __restrict);
char *fparseln(FILE *, size_t *, size_t *, const char[3], int);
int fpurge(FILE *);
void setbuffer(FILE *, char *, int);
int setlinebuf(FILE *);
int vasprintf(char ** __restrict, const char * __restrict,
va_list)
__attribute__((__format__(__printf__, 2, 0)));
int vscanf(const char * __restrict, va_list)
__attribute__((__format__(__scanf__, 1, 0)));
//int vfscanf(FILE * __restrict, const char * __restrict,
// va_list)
// __attribute__((__format__(__scanf__, 2, 0)));
int vsscanf(const char * __restrict, const char * __restrict,
va_list)
__attribute__((__format__(__scanf__, 2, 0)));
//const char *fmtcheck(const char *, const char *)
// __attribute__((__format_arg__(2)));
__END_DECLS
/*
* Stdio function-access interface.
*/
__BEGIN_DECLS
FILE *funopen(const void *,
int (*)(void *, char *, int),
int (*)(void *, const char *, int),
fpos_t (*)(void *, fpos_t, int),
int (*)(void *));
__END_DECLS
//#define fropen(cookie, fn) funopen(cookie, fn, 0, 0, 0)
//#define fwopen(cookie, fn) funopen(cookie, 0, fn, 0, 0)
/*
* Functions internal to the implementation.
*/
__BEGIN_DECLS
int __srget(FILE *);
int __swbuf(int, FILE *);
__END_DECLS
/*
* The __sfoo macros are here so that we can
* define function versions in the C library.
*/
#define __sgetc(p) (--(p)->_r < 0 ? __srget(p) : (int)(*(p)->_p++))
#if defined(__GNUC__) && defined(__STDC__)
static __inline int __sputc(int _c, FILE *_p) {
if (--_p->_w >= 0 || (_p->_w >= _p->_lbfsize && (char)_c != '\n'))
return (*_p->_p++ = _c);
else
return (__swbuf(_c, _p));
}
#else
/*
* This has been tuned to generate reasonable code on the vax using pcc.
*/
#define __sputc(c, p) \
(--(p)->_w < 0 ? \
(p)->_w >= (p)->_lbfsize ? \
(*(p)->_p = (unsigned char)(c)), *(p)->_p != '\n' ? \
(int)*(p)->_p++ : \
__swbuf('\n', p) : \
__swbuf((int)(c), p) : \
(*(p)->_p = (unsigned char)(c), (int)*(p)->_p++))
#endif
#define __sfeof(p) (((p)->_flags & __SEOF) != 0)
#define __sferror(p) (((p)->_flags & __SERR) != 0)
#define __sclearerr(p) ((void)((p)->_flags &= ~(__SERR|__SEOF)))
#define __sfileno(p) ((p)->_file)
#ifndef __lint__
#define feof(p) __sfeof(p)
#define ferror(p) __sferror(p)
#define clearerr(p) __sclearerr(p)
#define getc(fp) __sgetc(fp)
#define putc(x, fp) __sputc(x, fp)
#endif /* __lint__ */
#define getchar() getc(stdin)
#define putchar(x) putc(x, stdout)
#define fileno(p) __sfileno(p)
#define getc_unlocked(fp) __sgetc(fp)
#define putc_unlocked(x, fp) __sputc(x, fp)
#define getchar_unlocked() getc_unlocked(stdin)
#define putchar_unlocked(x) putc_unlocked(x, stdout)
#endif /* _STDIO_H_ */