pd.if.org Git - pdclib/blob - includes/stdio.h

   1 /* Input/output <stdio.h>
   2
   3    This file is part of the Public Domain C Library (PDCLib).
   4    Permission is granted to use, modify, and / or redistribute at will.
   5 */
   6
   7 #ifndef _PDCLIB_STDIO_H
   8 #define _PDCLIB_STDIO_H _PDCLIB_STDIO_H
   9
  10 #include <_PDCLIB_int.h>
  11
  12 #ifndef _PDCLIB_SIZE_T_DEFINED
  13 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
  14 typedef _PDCLIB_size_t size_t;
  15 #endif
  16
  17 #ifndef _PDCLIB_NULL_DEFINED
  18 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
  19 #define NULL _PDCLIB_NULL
  20 #endif
  21
  22 /* See setvbuf(), third argument */
  23 #define _IOFBF 1
  24 #define _IOLBF 2
  25 #define _IONBF 4
  26
  27 /* The following are platform-dependant, and defined in _PDCLIB_config.h. */
  28 typedef struct _PDCLIB_fpos_t fpos_t;
  29 typedef struct _PDCLIB_file_t FILE;
  30 #define EOF -1
  31 #define BUFSIZ _PDCLIB_BUFSIZ
  32 #define FOPEN_MAX _PDCLIB_FOPEN_MAX
  33 #define FILENAME_MAX _PDCLIB_FILENAME_MAX
  34 #define L_tmpnam _PDCLIB_L_tmpnam
  35 #define TMP_MAX _PDCLIB_TMP_MAX
  36
  37 /* See fseek(), third argument */
  38 #define SEEK_CUR _PDCLIB_SEEK_CUR
  39 #define SEEK_END _PDCLIB_SEEK_END
  40 #define SEEK_SET _PDCLIB_SEEK_SET
  41
  42 extern FILE * stdin;
  43 extern FILE * stdout;
  44 extern FILE * stderr;
  45
  46 /* Operations on files */
  47
  48 /* Remove the given file.
  49    Returns zero if successful, non-zero otherwise.
  50    This implementation does detect if a file of that name is currently open,
  51    and fails the remove in this case. This does not detect two distinct names
  52    that merely result in the same file (e.g. "/home/user/foo" vs. "~/foo").
  53 */
  54 int remove( const char * filename );
  55
  56 /* Rename the given old file to the given new name.
  57    Returns zero if successful, non-zero otherwise.
  58    This implementation does detect if the old filename corresponds to an open
  59    file, and fails the rename in this case.
  60    If there already is a file with the new filename, behaviour is defined by
  61    the glue code (see functions/_PDCLIB/rename.c).
  62 */
  63 int rename( const char * old, const char * new );
  64
  65 /* Open a temporary file with mode "wb+", i.e. binary-update. Remove the file
  66    automatically if it is closed or the program exits normally (by returning
  67    from main() or calling exit()).
  68    Returns a pointer to a FILE handle for this file.
  69    This implementation does not remove temporary files if the process aborts
  70    abnormally (e.g. abort()).
  71 */
  72 FILE * tmpfile( void );
  73
  74 /* Generate a file name that is not equal to any existing filename AT THE TIME
  75    OF GENERATION. Generate a different name each time it is called.
  76    Returns a pointer to an internal static buffer containing the filename if s
  77    is a NULL pointer. (This is not thread-safe!)
  78    Returns s if it is not a NULL pointer (s is then assumed to point to an array
  79    of at least L_tmpnam characters).
  80    Returns NULL if unable to generate a suitable name (because all possible
  81    names already exist, or the function has been called TMP_MAX times already).
  82    Note that this implementation cannot guarantee a file of the name generated
  83    is not generated between the call to this function and a subsequent fopen().
  84 */
  85 char * tmpnam( char * s );
  86
  87 /* File access functions */
  88
  89 /* Close the file associated with the given stream (after flushing its buffers).
  90    Returns zero if successful, EOF if any errors occur.
  91 */
  92 int fclose( FILE * stream );
  93
  94 /* Flush the buffers of the given output stream. If the stream is an input
  95    stream, or an update stream with the last operation being an input operation,
  96    behaviour is undefined.
  97    If stream is a NULL pointer, perform the buffer flushing for all applicable
  98    streams.
  99    Returns zero if successful, EOF if a write error occurs.
 100    Sets the error indicator of the stream if a write error occurs.
 101 */
 102 int fflush( FILE * stream );
 103
 104 /* Open the file with the given filename in the given mode, and return a stream
 105    handle for it in which error and end-of-file indicator are cleared. Defined
 106    values for mode are:
 107
 108    READ MODES
 109                       text files        binary files
 110    without update     "r"               "rb"
 111    with update        "r+"              "rb+" or "r+b"
 112
 113    Opening in read mode fails if no file with the given filename exists, or if
 114    cannot be read.
 115
 116    WRITE MODES
 117                       text files        binary files
 118    without update     "w"               "wb"
 119    with update        "w+"              "wb+" or "w+b"
 120
 121    With write modes, if a file with the given filename already exists, it is
 122    truncated to zero length.
 123
 124    APPEND MODES
 125                       text files        binary files
 126    without update     "a"               "ab"
 127    with update        "a+"              "ab+" or "a+b"
 128
 129    With update modes, if a file with the given filename already exists, it is
 130    not truncated to zero length, but all writes are forced to end-of-file (this
 131    regardless to fseek() calls). Note that binary files opened in append mode
 132    might have their end-of-file padded with '\0' characters.
 133
 134    Update modes mean that both input and output functions can be performed on
 135    the stream, but output must be terminated with a call to either fflush(),
 136    fseek(), fsetpos(), or rewind() before input is performed, and input must
 137    be terminated with a call to either fseek(), fsetpos(), or rewind() before
 138    output is performed, unless input encountered end-of-file.
 139
 140    If a text file is opened with update mode, the implementation is at liberty
 141    to open a binary stream instead. This implementation honors the exact mode
 142    given.
 143
 144    The stream is fully buffered if and only if it can be determined not to
 145    refer to an interactive device.
 146
 147    If the mode string begins with but is longer than one of the above sequences
 148    the implementation is at liberty to ignore the additional characters, or do
 149    implementation-defined things. This implementation only accepts the exact
 150    modes above.
 151
 152    Returns a pointer to the stream handle if successfull, NULL otherwise.
 153 */
 154 FILE * fopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode );
 155
 156 /* Close any file currently associated with the given stream. Open the file
 157    identified by the given filename with the given mode (equivalent to fopen()),
 158    and associate it with the given stream. If filename is a NULL pointer,
 159    attempt to change the mode of the given stream.
 160    This implementation allows any mode changes on "real" files, and associating
 161    of the standard streams with files. It does *not* support mode changes on
 162    standard streams.
 163    (Primary use of this function is to redirect stdin, stdout, and stderr.)
 164 */
 165 FILE * freopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode, FILE * _PDCLIB_restrict stream );
 166
 167 /* If buf is a NULL pointer, call setvbuf( stream, NULL, _IONBF, BUFSIZ ).
 168    If buf is not a NULL pointer, call setvbuf( stream, buf, _IOFBF, BUFSIZ ).
 169 */
 170 void setbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf );
 171
 172 /* Set the given stream to the given buffering mode. If buf is not a NULL
 173    pointer, use buf as file buffer (of given size). If buf is a NULL pointer,
 174    use a buffer of given size allocated internally. _IONBF causes unbuffered
 175    behaviour, _IOLBF causes line-buffered behaviour, _IOFBF causes fully
 176    buffered behaviour. Calling this function is only valid right after a file is
 177    opened, and before any other operation (except for any unsuccessful calls to
 178    setvbuf()) has been performed.
 179    Returns zero if successful, nonzero otherwise.
 180 */
 181 int setvbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf, int mode, size_t size );
 182
 183 /* Formatted input/output functions */
 184
 185 /*
 186    Write output to the given stream, as defined by the given format string and
 187    0..n subsequent arguments (the argument stack).
 188
 189    The format string is written to the given stream verbatim, except for any
 190    conversion specifiers included, which start with the letter '%' and are
 191    documented below. If the given conversion specifiers require more arguments
 192    from the argument stack than provided, behaviour is undefined. Additional
 193    arguments not required by conversion specifiers are evaluated but otherwise
 194    ignored.
 195
 196    (The standard specifies the format string is allowed to contain multibyte
 197    character sequences as long as it starts and ends in initial shift state,
 198    but this is not yet supported by this implementation, which interprets the
 199    format string as sequence of char.)
 200    TODO: Add multibyte support to printf() functions.
 201
 202    A conversion specifier consists of:
 203    - Zero or more flags (one of the characters "-+ #0").
 204    - Optional minimum field width as decimal integer. Default is padding to the
 205      left, using spaces. Note that 0 is taken as a flag, not the beginning of a
 206      field width. Note also that a small field width will not result in the
 207      truncation of a value.
 208    - Optional precision (given as ".#" with # being a decimal integer),
 209      specifying:
 210      - the min. number of digits to appear (diouxX),
 211      - the max. number of digits after the decimal point (aAeEfF),
 212      - the max. number of significant digits (gG),
 213      - the max. number of bytes to be written (s).
 214      - behaviour with other conversion specifiers is undefined.
 215    - Optional length modifier specifying the size of the argument (one of "hh",
 216      "ll", or one of the characters "hljztL").
 217    - Conversion specifier character specifying the type of conversion to be
 218      applied (and the type of the next argument from the argument stack). One
 219      of the characters "diouxXfFeEgGaAcspn%".
 220
 221    Minimum field width and/or precision may be given as asterisk ('*') instead
 222    of a decimal integer. In this case, the next argument from the argument
 223    stack is assumed to be an int value specifying the width / precision. A
 224    negative field width is interpreted as flag '-' followed by a positive field
 225    width. A negative precision is interpreted as if no precision was given.
 226
 227    FLAGS
 228    -     Left-justify the conversion result within its field width.
 229    +     Prefix a '+' on positive signed conversion results. Prefix a '-' on
 230          floating conversions resulting in negative zero, or negative values
 231          rounding to zero.
 232    space Prefix a space on positive signed conversion results, or if a signed
 233          conversion results in no characters. If both '+' and ' ' are given,
 234          ' ' is ignored.
 235    #     Use an "alternative form" for
 236          - 'o' conversion, increasing precision until the first digit of the
 237            result is a zero;
 238          - 'x' or 'X' conversion, prefixing "0x" or "0X" to nonzero results;
 239          - "aAeEfF" conversions, always printing a decimal point even if no
 240            digits are following;
 241          - 'g' or 'G' conversions, always printing a decimal point even if no
 242            digits are following, and not removing trailing zeroes.
 243          - behaviour for other conversions is unspecified.
 244    0     Use leading zeroes instead of spaces for field width padding. If both
 245          '-' and '0' are given, '0' is ignored. If a precision is specified for
 246          any of the "diouxX" conversions, '0' is ignored. Behaviour is only
 247          defined for "diouxXaAeEfFgG".
 248
 249    LENGTH MODIFIERS
 250    hh  For "diouxX" conversions, the argument from the argument stack is
 251        assumed to be of char width. (It will have been subject to integer
 252        promotion but will be converted back.) For 'n' conversions, the argument
 253        is assumed to be a pointer to signed char.
 254    h   For "diouxX" conversions, the argument from the argument stack is
 255        assumed to be of short int width. (It will have been subject to integer
 256        promotion but will be converted back.) For 'n' conversions, the argument
 257        is assumed to be a pointer to short int.
 258    l   For "diouxX" conversions, the argument from the argument stack is
 259        assumed to be of long int width. For 'n' conversions, the argument is
 260        assumed to be a pointer to short int. For 'c' conversions, the argument
 261        is assumed to be a wint_t. For 's' conversions, the argument is assumed
 262        to be a pointer to wchar_t. No effect on "aAeEfFgG" conversions.
 263    ll  For "diouxX" conversions, the argument from the argument stack is
 264        assumed to be of long long int width. For 'n' conversions, the argument
 265        is assumed to be a pointer to long long int.
 266    j   For "diouxX" conversions, the argument from the argument stack is
 267        assumed to be of intmax_t width. For 'n' conversions, the argument is
 268        assumed to be a pointer to intmax_t.
 269    z   For "diouxX" conversions, the argument from the argument stack is
 270        assumed to be of size_t width. For 'n' conversions, the argument is
 271        assumed to be a pointer to size_t.
 272    t   For "diouxX" conversions, the argument from the argument stack is
 273        assumed to be of ptrdiff_t width. For 'n' conversions, the argument is
 274        assumed to be a pointer to ptrdiff_t.
 275    L   For "aAeEfFgG" conversions, the argument from the argument stack is
 276        assumed to be a long double.
 277    Length modifiers appearing for any conversions not mentioned above will have
 278    undefined behaviour.
 279    If a length modifier appears with any conversion specifier other than as
 280    specified above, the behavior is undefined.
 281
 282    CONVERSION SPECIFIERS
 283    d,i The argument from the argument stack is assumed to be of type int, and
 284        is converted to a signed decimal value with a minimum number of digits
 285        as specified by the precision (default 1), padded with leading zeroes.
 286        A zero value converted with precision zero yields no output.
 287    o   The argument from the argument stack is assumed to be of type unsigned
 288        int, and is converted to an unsigned octal value, other behaviour being
 289        as above.
 290    u   The argument from the argument stack is assumed to be of type unsigned
 291        int, and converted to an unsigned decimal value, other behaviour being
 292        as above.
 293    x,X The argument from the argument stack is assumed to be of type unsigned
 294        int, and converted to an unsigned hexadecimal value, using lowercase
 295        "abcdef" for 'x' and uppercase "ABCDEF" for 'X' conversion, other
 296        behaviour being as above.
 297    f,F The argument from the argument stack is assumed to be of type double,
 298        and converted to a decimal floating point in decimal-point notation,
 299        with the number of digits after the decimal point as specified by the
 300        precision (default 6) and the value being rounded appropriately. If
 301        precision is zero (and the '#' flag is not given), no decimal point is
 302        printed. At least one digit is always printed before the decimal point.
 303        For 'f' conversions, an infinity value is printed as either [-]inf or
 304        [-]infinity (, depending on the configuration of this implementation. A
 305        NaN value is printed as [-]nan. For 'F' conversions uppercase characters
 306        are used for these special values. The flags '-', '+' and ' ' apply as
 307        usual to these special values, '#' and '0' have no effect.
 308    e,E The argument from the argument stack is assumed to be of type double,
 309        and converted to a decimal floating point in normalized exponential
 310        notation ([?]d.ddd edd). "Normalized" means one nonzero digit before
 311        the decimal point, unless the value is zero. The number of digits after
 312        the decimal point is specified by the precision (default 6), the value
 313        being rounded appropriately. If precision is zero (and the '#' flag is
 314        not given), no decimal point is printed. The exponent has at least two
 315        digits, and not more than necessary to represent the exponent. If the
 316        value is zero, the exponent is zero. The 'e' written to indicate the
 317        exponend is uppercase for 'E' conversions.
 318        Infinity or NaN values are represented as for 'f' and 'F' conversions,
 319        respectively.
 320    g,G The argument from the argument stack is assumed to be of type double,
 321        and converted according to either 'f' or 'e' format for 'g' conversions,
 322        or 'F' or 'E' format for 'G' conversions, respectively, with the actual
 323        conversion chosen depending on the value. 'e' / 'E' conversion is chosen
 324        if the resulting exponent is < -4 or >= the precision (default 1).
 325        Trailing zeroes are removed (unless the '#' flag is given). A decimal
 326        point appears only if followed by a digit.
 327        Infinity or NaN values are represented as for 'f' and 'F' conversions,
 328        respectively.
 329    a,A The argument from the argument stack is assumed to be of type double,
 330        and converted to a floating point hexadecimal notation ([?]0xh.hhhh pd)
 331        with one hexadecimal digit (being nonzero if the value is normalized,
 332        and otherwise unspecified) before the decimal point, and the number of
 333        digits after the decimal point being specified by the precision. If no
 334        precision is given, the default is to print as many digits as nevessary
 335        to give an exact representation of the value (if FLT_RADIX is a power of
 336        2). If no precision is given and FLT_RADIX is not a power of 2, the
 337        default is to print as many digits to distinguish values of type double
 338        (possibly omitting trailing zeroes). (A precision p is sufficient to
 339        distinguish values of the source type if 16^p-1 > b^n where b is
 340        FLT_RADIX and n is the number of digits in the significand (to base b)
 341        of the source type. A smaller p might suffice depending on the
 342        implementation's scheme for determining the digit to the left of the
 343        decimal point.) The error has the correct sign for the current rounding
 344        direction.
 345        Unless the '#' flag is given, no decimal-point is given for zero
 346        precision.
 347        The 'a' conversion uses lowercase "abcdef", "0x" and 'p', the 'A'
 348        conversion uppercase "ABCDEF", "0X" and 'P'.
 349        The exponent always has at least one digit, and not more than necessary
 350        to represent the decimal exponent of 2. If the value is zero, the
 351        exponent is zero.
 352        Infinity or NaN values are represented as for 'f' and 'F' conversions,
 353        respectively.
 354        Binary implementations are at liberty to chose the hexadecimal digit to
 355        the left of the decimal point so that subsequent digits align to nibble
 356        boundaries.
 357    c   The argument from the argument stack is assumed to be of type int, and
 358        converted to a character after the value has been cast to unsigned char.
 359        If the 'l' length modifier is given, the argument is assumed to be of
 360        type wint_t, and converted as by a "%ls" conversion with no precision
 361        and a pointer to a two-element wchar_t array, with the first element
 362        being the wint_t argument and the second a '\0' wide character.
 363    s   The argument from the argument stack is assumed to be a char array (i.e.
 364        pointer to char). Characters from that array are printed until a zero
 365        byte is encountered or as many bytes as specified by a given precision
 366        have been written.
 367        If the l length modifier is given, the argument from the argument stack
 368        is assumed to be a wchar_t array (i.e. pointer to wchar_t). Wide
 369        characters from that array are converted to multibyte characters as by
 370        calls to wcrtomb() (using a mbstate_t object initialized to zero prior
 371        to the first conversion), up to and including the terminating null wide
 372        character. The resulting multibyte character sequence is then printed up
 373        to but not including the terminating null character. If a precision is
 374        given, it specifies the maximum number of bytes to be written (including
 375        shift sequences). If the given precision would require access to a wide
 376        character one past the end of the array, the array shall contain a '\0'
 377        wide character. In no case is a partial multibyte character written.
 378        Redundant shift sequences may result if the multibyte characters have a
 379        state-dependent encoding.
 380        TODO: Clarify these statements regarding %ls.
 381    p   The argument from the argument stack is assumed to be a void pointer,
 382        and converted to a sequence of printing characters in an implementation-
 383        defined manner.
 384        This implementation casts the pointer to type intptr_t, and prints the
 385        value as if a %#x conversion specifier was given.
 386    n   The argument from the argument stack is assumed to be a pointer to a
 387        signed integer, into which the number of characters written so far by
 388        this call to fprintf is stored. The behaviour, should any flags, field
 389        widths, or precisions be given is undefined.
 390    %   A verbatim '%' character is written. No argument is taken from the
 391        argument stack.
 392
 393    Returns the number of characters written if successful, a negative value
 394    otherwise.
 395 */
 396 int fprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 397
 398 /* TODO: fscanf() documentation */
 399 /*
 400    Read input from a given stream, as defined by the given format string, and
 401    store converted input in the objects pointed to by 0..n subsequent arguments
 402    (the argument stack).
 403
 404    The format string contains a sequence of directives that are expected to
 405    match the input. If such a directive fails to match, the function returns
 406    (matching error). It also returns if an input error occurs (input error).
 407
 408    Directives can be:
 409    - one or more whitespaces, matching any number of whitespaces in the input;
 410    - printing characters, matching the input verbatim;
 411    - conversion specifications, which convert an input sequence into a value as
 412      defined by the individual specifier, and store that value in a memory
 413      location pointed to by the next pointer on the argument stack. Details are
 414      documented below. If there is an insufficient number of pointers on the
 415      argument stack, behaviour is undefined. Additional arguments not required
 416      by any conversion specifications are evaluated, but otherwise ignored.
 417
 418    (The standard specifies the format string is allowed to contain multibyte
 419    character sequences as long as it starts and ends in initial shift state,
 420    but this is not yet supported by this implementation, which interprets the
 421    format string as sequence of char.)
 422    TODO: Add multibyte support to scanf() functions.
 423
 424    A conversion specifier consists of:
 425    - Optional assignment-suppressing character ('*') that makes the conversion
 426      read input as usual, but does not assign the conversion result.
 427    - Optional maximum field width as decimal integer.
 428    - Optional length modifier specifying the size of the argument (one of "hh",
 429      "ll", or one of the characters "hljztL").
 430    - Conversion specifier character specifying the type of conversion to be
 431      applied (and the type of the next argument from the argument stack). One
 432      of the characters "diouxXaAeEfFgGcs[pn%".
 433
 434    LENGTH MODIFIERS
 435    hh  For "diouxXn" conversions, the next pointer from the argument stack is
 436        assumed to point to a variable of of char width.
 437    h   For "diouxXn" conversions, the next pointer from the argument stack is
 438        assumed to point to a variable of short int width.
 439    l   For "diouxXn" conversions, the next pointer from the argument stack is
 440        assumed to point to a variable of long int width.
 441        For "aAeEfFgG" conversions, it is assumed to point to a variable of type
 442        double.
 443        For "cs[" conversions, it is assumed to point to a variable of type
 444        wchar_t.
 445    ll  For "diouxXn" conversions, the next pointer from the argument stack is
 446        assumed to point to a variable of long long int width.
 447    j   For "diouxXn" conversions, the next pointer from the argument stack is
 448        assumed to point to a variable of intmax_t width.
 449    z   For "diouxXn" conversions, the next pointer from the argument stack is
 450        assumed to point to a variable of size_t width.
 451    t   For "diouxXn" conversions, the next pointer from the argument stack is
 452        assumed to point to a variable of ptrdiff_t width.
 453    L   For "aAeEfFgG" conversions, the next pointer from the argument stack is
 454        assumed to point to a variable of type long double.
 455    Length modifiers appearing for any conversions not mentioned above will have
 456    undefined behaviour.
 457    If a length modifier appears with any conversion specifier other than as
 458    specified above, the behavior is undefined.
 459
 460    CONVERSION SPECIFIERS
 461    d    Matches an (optionally signed) decimal integer of the format expected
 462         by strtol() with base 10. The next pointer from the argument stack is
 463         assumed to point to a signed integer.
 464    i    Matches an (optionally signed) integer of the format expected by
 465         strtol() with base 0. The next pointer from the argument stack is
 466         assumed to point to a signed integer.
 467    o    Matches an (optionally signed) octal integer of the format expected by
 468         strtoul() with base 8. The next pointer from the argument stack is
 469         assumed to point to an unsigned integer.
 470    u    Matches an (optionally signed) decimal integer of the format expected
 471         by strtoul() with base 10. The next pointer from the argument stack is
 472         assumed to point to an unsigned integer.
 473    x    Matches an (optionally signed) hexadecimal integer of the format
 474         expected by strtoul() with base 16. The next pointer from the argument
 475         stack is assumed to point to an unsigned integer.
 476    aefg Matches an (optionally signed) floating point number, infinity, or not-
 477         a-number-value of the format expected by strtod(). The next pointer
 478         from the argument stack is assumed to point to a float.
 479    c    Matches a number of characters as specified by the field width (default
 480         1). The next pointer from the argument stack is assumed to point to a
 481         character array large enough to hold that many characters.
 482         If the 'l' length modifier is given, the input is assumed to match a
 483         sequence of multibyte characters (starting in the initial shift state),
 484         which will be converted to a wide character sequence as by successive
 485         calls to mbrtowc() with a mbstate_t object initialized to zero prior to
 486         the first conversion. The next pointer from the argument stack is
 487         assumed to point to a wchar_t array large enough to hold that many
 488         characters.
 489         In either case, note that no '\0' character is added to terminate the
 490         sequence.
 491    s    Matches a sequence of non-white-space characters. The next pointer from
 492         the argument stack is assumed to point to a character array large
 493         enough to hold the sequence including terminating '\0' character.
 494         If the 'l' length modifier is given, the input is assumed to match a
 495         sequence of multibyte characters (starting in the initial shift state),
 496         which will be converted to a wide character sequence as by a call to
 497         mbrtowc() with a mbstate_t object initialized to zero prior to the
 498         first conversion. The next pointer from the argument stack is assumed
 499         to point to a wchar_t array large enough to hold the sequence including
 500         terminating '\0' character.
 501    [    Matches a nonempty sequence consisting of any of those characters
 502         specified between itself and a corresponding closing bracket (']').
 503         If the first character in the list is a circumflex ('^'), this matches
 504         a nonempty sequence consisting of any characters NOT specified. If the
 505         closing bracket appears as the first character in the scanset ("[]" or
 506         "[^]", it is assumed to belong to the scanset, which then ends with the
 507         NEXT closing bracket.
 508         If there is a '-' character in the scanset which is not the first after
 509         the opening bracket (or the circumflex, see above) or the last in the
 510         scanset, behaviour is implementation-defined. This implementation
 511         handles this character like any other.
 512
 513         The extend of the input field is determined byte-by-byte for the above
 514         conversions ('c', 's', '['), with no special provisions being made for
 515         multibyte characters. The resulting field is nevertheless a multibyte
 516         sequence begining in intial shift state.
 517
 518    p    Matches a sequence of characters as produced by the printf() "%p"
 519         conversion. The next pointer from the argument stack is assumed to
 520         point to a void pointer, which will be filled with the same location
 521         as the pointer used in the printf() statement. Note that behaviour is
 522         undefined if the input value is not the result of an earlier printf()
 523         call.
 524    n    Does not read input. The next pointer from the argument stack is
 525         assumed to point to a signed integer, into which the number of
 526         characters read from input so far by this call to fscanf() is stored.
 527         This does not affect the return value of fscanf(). The behaviour,
 528         should an assignment-supressing character of field width be given,
 529         is undefined.
 530         This can be used to test the success of literal matches and suppressed
 531         assignments.
 532    %    Matches a single, verbatim '%' character.
 533
 534    A, E, F, G and X are valid, and equivalent to their lowercase counterparts.
 535
 536    All conversions except [, c, or n imply that whitespace characters from the
 537    input stream are consumed until a non-whitespace character is encountered.
 538    Such whitespaces do not count against a maximum field width.
 539
 540    Conversions push at most one character back into the input stream. That
 541    implies that some character sequences converted by the strtol() and strtod()
 542    function families are not converted identically by the scnaf() function
 543    family.
 544
 545    Returns the number of input items successfully assigned. This can be zero if
 546    an early mismatch occurs. Returns EOF if an input failure occurs before the
 547    first conversion.
 548 */
 549 int fscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 550
 551 /* Equivalent to fprintf( stdout, format, ... ). */
 552 int printf( const char * _PDCLIB_restrict format, ... );
 553
 554 /* Equivalent to fscanf( stdin, format, ... ). */
 555 int scanf( const char * _PDCLIB_restrict format, ... );
 556
 557 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
 558    written into the buffer pointed to by s, instead of stdout, and that any
 559    characters beyond the (n-1)th are discarded. The (n)th character is
 560    replaced by a '\0' character in this case.
 561    Returns the number of characters that would have been written (not counting
 562    the terminating '\0' character) if n had been sufficiently large, if
 563    successful, and a negative number if an encoding error ocurred.
 564 */
 565 int snprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, ... );
 566
 567 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
 568    written into the buffer pointed to by s, instead of stdout.
 569 */
 570 int sprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 571
 572 /* Equivalent to fscanf( stdin, format, ... ), except that the input is read
 573    from the buffer pointed to by s, instead of stdin.
 574 */
 575 int sscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 576
 577 /* Equivalent to fprintf( stream, format, ... ), except that the argument stack
 578    is passed as va_list parameter. Note that va_list is not declared by
 579    <stdio.h>.
 580 */
 581 int vfprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 582
 583 /* Equivalent to fscanf( stream, format, ... ), except that the argument stack
 584    is passed as va_list parameter. Note that va_list is not declared by
 585    <stdio.h>.
 586 */
 587 int vfscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 588
 589 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
 590    is passed as va_list parameter. Note that va_list is not declared by
 591    <stdio.h>.
 592 */
 593 int vprintf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 594
 595 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
 596    is passed as va_list parameter. Note that va_list is not declared by
 597    <stdio.h>.
 598 */
 599 int vscanf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 600
 601 /* Equivalent to snprintf( s, n, format, ... ), except that the argument stack
 602    is passed as va_list parameter. Note that va_list is not declared by
 603    <stdio.h>.
 604    */
 605 int vsnprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 606
 607 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
 608    is passed as va_list parameter, and the result is written to the buffer
 609    pointed to by s, instead of stdout. Note that va_list is not declared by
 610    <stdio.h>.
 611 */
 612 int vsprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 613
 614 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
 615    is passed as va_list parameter, and the input is read from the buffer
 616    pointed to by s, instead of stdin. Note that va_list is not declared by
 617    <stdio.h>.
 618 */
 619 int vsscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 620
 621 /* Character input/output functions */
 622
 623 /* Retrieve the next character from given stream.
 624    Returns the character, EOF otherwise.
 625    If end-of-file is reached, the EOF indicator of the stream is set.
 626    If a read error occurs, the error indicator of the stream is set.
 627 */
 628 int fgetc( FILE * stream );
 629
 630 /* Read at most n-1 characters from given stream into the array s, stopping at
 631    \n or EOF. Terminate the read string with \n. If EOF is encountered before
 632    any characters are read, leave the contents of s unchanged.
 633    Returns s if successful, NULL otherwise.
 634    If a read error occurs, the error indicator of the stream is set. In this
 635    case, the contents of s are indeterminate.
 636 */
 637 char * fgets( char * _PDCLIB_restrict s, int n, FILE * _PDCLIB_restrict stream );
 638
 639 /* Write the value c (cast to unsigned char) to the given stream.
 640    Returns c if successful, EOF otherwise.
 641    If a write error occurs, sets the error indicator of the stream is set.
 642 */
 643 int fputc( int c, FILE * stream );
 644
 645 /* Write the string s (not including the terminating \0) to the given stream.
 646    Returns a value >=0 if successful, EOF otherwise.
 647    This implementation does set the error indicator of the stream if a write
 648    error occurs.
 649 */
 650 int fputs( const char * _PDCLIB_restrict s, FILE * _PDCLIB_restrict stream );
 651
 652 /* Equivalent to fgetc( stream ), but may be overloaded by a macro that
 653    evaluates its parameter more than once.
 654 */
 655 int getc( FILE * stream );
 656
 657 /* Equivalent to fgetc( stdin ). */
 658 int getchar( void );
 659
 660 /* Equivalent to fputc( c, stream ), but may be overloaded by a macro that
 661    evaluates its parameter more than once.
 662 */
 663 int putc( int c, FILE * stream );
 664
 665 /* Equivalent to fputc( c, stdout ), but may be overloaded by a macro that
 666    evaluates its parameter more than once.
 667 */
 668 int putchar( int c );
 669
 670 /* Write the string s (not including the terminating \0) to stdout, and append
 671    a newline to the output. Returns a value >= 0 when successful, EOF if a
 672    write error occurred.
 673 */
 674 int puts( const char * s );
 675
 676 /* Push the value c (cast to unsigned char) back onto the given (input) stream.
 677    A character pushed back in this way will be delivered by subsequent read
 678    operations (and skipped by subsequent file positioning operations) as if it
 679    has not been read. The external representation of the stream is unaffected
 680    by this pushback (it is a buffer operation). One character of pushback is
 681    guaranteed, further pushbacks may fail. EOF as value for c does not change
 682    the input stream and results in failure of the function.
 683    For text files, the file position indicator is indeterminate until all
 684    pushed-back characters are read. For binary files, the file position
 685    indicator is decremented by each successful call of ungetc(). If the file
 686    position indicator for a binary file was zero before the call of ungetc(),
 687    behaviour is undefined. (Older versions of the library allowed such a call.)
 688    Returns the pushed-back character if successful, EOF if it fails.
 689 */
 690 int ungetc( int c, FILE * stream );
 691
 692 /* Direct input/output functions */
 693
 694 /* Read up to nmemb elements of given size from given stream into the buffer
 695    pointed to by ptr. Returns the number of elements successfully read, which
 696    may be less than nmemb if a read error or EOF is encountered. If a read
 697    error is encountered, the value of the file position indicator is
 698    indeterminate. If a partial element is read, its value is indeterminate.
 699    If size or nmemb are zero, the function does nothing and returns zero.
 700 */
 701 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 702
 703 /* Write up to nmemb elements of given size from buffer pointed to by ptr to
 704    the given stream. Returns the number of elements successfully written, which
 705    will be less than nmemb only if a write error is encountered. If a write
 706    error is encountered, the value of the file position indicator is
 707    indeterminate. If size or nmemb are zero, the function does nothing and
 708    returns zero.
 709 */
 710 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 711
 712 /* File positioning functions */
 713
 714 /* Store the current position indicator (and, where appropriate, the current
 715    mbstate_t status object) for the given stream into the given pos object. The
 716    actual contents of the object are unspecified, but it can be used as second
 717    parameter to fsetpos() to reposition the stream to the exact position and
 718    parse state at the time fgetpos() was called.
 719    Returns zero if successful, nonzero otherwise.
 720    TODO: Implementation-defined errno setting for fgetpos().
 721 */
 722 int fgetpos( FILE * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
 723
 724 /* Set the position indicator for the given stream to the given offset from:
 725    - the beginning of the file if whence is SEEK_SET,
 726    - the current value of the position indicator if whence is SEEK_CUR,
 727    - end-of-file if whence is SEEK_END.
 728    On text streams, non-zero offsets are only allowed with SEEK_SET, and must
 729    have been returned by ftell() for the same file.
 730    Any characters buffered by ungetc() are dropped, the end-of-file indicator
 731    for the stream is cleared. If the given stream is an update stream, the next
 732    operation after a successful fseek() may be either input or output.
 733    Returns zero if successful, nonzero otherwise. If a read/write error occurs,
 734    the error indicator for the given stream is set.
 735 */
 736 int fseek( FILE * stream, long int offset, int whence );
 737
 738 /* Set the position indicator (and, where appropriate the mbstate_t status
 739    object) for the given stream to the given pos object (created by an earlier
 740    call to fgetpos() on the same file).
 741    Any characters buffered by ungetc() are dropped, the end-of-file indicator
 742    for the stream is cleared. If the given stream is an update stream, the next
 743    operation after a successful fsetpos() may be either input or output.
 744    Returns zero if successful, nonzero otherwise. If a read/write error occurs,
 745    the error indicator for the given stream is set.
 746    TODO: Implementation-defined errno setting for fsetpos().
 747 */
 748 int fsetpos( FILE * stream, const fpos_t * pos );
 749
 750 /* Return the current offset of the given stream from the beginning of the
 751    associated file. For text streams, the exact value returned is unspecified
 752    (and may not be equal to the number of characters), but may be used in
 753    subsequent calls to fseek().
 754    Returns -1L if unsuccessful.
 755    TODO: Implementation-defined errno setting for ftell().
 756 */
 757 long int ftell( FILE * stream );
 758
 759 /* Equivalent to (void)fseek( stream, 0L, SEEK_SET ), except that the error
 760    indicator for the stream is also cleared.
 761 */
 762 void rewind( FILE * stream );
 763
 764 /* Error-handling functions */
 765
 766 /* Clear the end-of-file and error indicators for the given stream. */
 767 void clearerr( FILE * stream );
 768
 769 /* Return zero if the end-of-file indicator for the given stream is not set,
 770    nonzero otherwise.
 771 */
 772 int feof( FILE * stream );
 773
 774 /* Return zero if the error indicator for the given stream is not set, nonzero
 775    otherwise.
 776 */
 777 int ferror( FILE * stream );
 778
 779 /* If s is neither a NULL pointer nor an empty string, print the string to
 780    stderr (with appended colon (':') and a space) first. In any case, print an
 781    error message depending on the current value of errno (being the same as if
 782    strerror( errno ) had been called).
 783 */
 784 void perror( const char * s );
 785
 786 #endif