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