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