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