Update or add comments to files and functions for use by Doxygen.

[mirror_edk2.git] / StdLib / Include / stdio.h

/** @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 - 2011, 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];   /**< guarantee an ungetc() buffer */
  unsigned char   _nbuf[1];   /**< 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.  Copied and
                          converted characters are sent to the output stream.
    @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  (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_ */