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