3 /* Input/output <stdio.h>
5 This file is part of the Public Domain C Library (PDCLib).
6 Permission is granted to use, modify, and / or redistribute at will.
9 #ifndef _PDCLIB_STDIO_H
10 #define _PDCLIB_STDIO_H _PDCLIB_STDIO_H
13 #define _PDCLIB_INT_H _PDCLIB_INT_H
14 #include <_PDCLIB_int.h>
17 #ifndef _PDCLIB_SIZE_T_DEFINED
18 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
19 typedef _PDCLIB_size_t size_t;
22 #ifndef _PDCLIB_NULL_DEFINED
23 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
24 #define NULL _PDCLIB_NULL
27 /* See setvbuf(), third argument */
32 /* The following are platform-dependant, and defined in _PDCLIB_config.h. */
33 typedef _PDCLIB_fpos_t fpos_t;
34 typedef struct _PDCLIB_file_t FILE;
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
42 /* See fseek(), third argument */
50 /* Operations on files */
52 /* Remove the given file.
53 Returns zero if successful, non-zero otherwise.
54 This implementation does detect if the filename corresponds to an open file,
55 and closes it before attempting the rename.
57 int remove( const char * filename );
59 /* Rename the given old file to the given new name.
60 Returns zero if successful, non-zero otherwise.
61 This implementation does detect if the old filename corresponds to an open
62 file, and closes it before attempting the rename.
63 If the already is a file with the new filename, behaviour is defined by the
66 int rename( const char * old, const char * new );
68 /* Open a temporary file with mode "wb+", i.e. binary-update. Remove the file
69 automatically if it is closed or the program exits normally (by returning
70 from main() or calling exit()).
71 Returns a pointer to a FILE handle for this file.
72 This implementation does not remove temporary files if the process aborts
73 abnormally (e.g. abort()).
75 FILE * tmpfile( void );
77 /* Generate a file name that is not equal to any existing filename AT THE TIME
78 OF GENERATION. Generate a different name each time it is called.
79 Returns a pointer to an internal static buffer containing the filename if s
80 is a NULL pointer. (This is not thread-safe!)
81 Returns s if it is not a NULL pointer (s is then assumed to point to an array
82 of at least L_tmpnam characters).
83 Returns NULL if unable to generate a suitable name (because all possible
84 names already exist, or the function has been called TMP_MAX times already).
85 Note that this implementation cannot guarantee a file of the name generated
86 is not generated between the call to this function and a subsequent fopen().
88 char * tmpnam( char * s );
90 /* File access functions */
92 /* Close the file associated with the given stream (after flushing its buffers).
93 Returns zero if successful, EOF if any errors occur.
95 int fclose( FILE * stream );
97 /* Flush the buffers of the given output stream. If the stream is an input
98 stream, or an update stream with the last operation being an input operation,
99 behaviour is undefined.
100 If stream is a NULL pointer, perform the buffer flushing for all applicable
102 Returns zero if successful, EOF if a write error occurs.
103 Sets the error indicator of the stream if a write error occurs.
105 int fflush( FILE * stream );
107 /* Open the file with the given filename in the given mode, and return a stream
108 handle for it in which error and end-of-file indicator are cleared. Defined
112 text files binary files
113 without update "r" "rb"
114 with update "r+" "rb+" or "r+b"
116 Opening in read mode fails if no file with the given filename exists, or if
120 text files binary files
121 without update "w" "wb"
122 with update "w+" "wb+" or "w+b"
124 With write modes, if a file with the given filename already exists, it is
125 truncated to zero length.
128 text files binary files
129 without update "a" "ab"
130 with update "a+" "ab+" or "a+b"
132 With update modes, if a file with the given filename already exists, it is
133 not truncated to zero length, but all writes are forced to end-of-file (this
134 regardless to fseek() calls). Note that binary files opened in append mode
135 might have their end-of-file padded with '\0' characters.
137 Update modes mean that both input and output functions can be performed on
138 the stream, but output must be terminated with a call to either fflush(),
139 fseek(), fsetpos(), or rewind() before input is performed, and input must
140 be terminated with a call to either fseek(), fsetpos(), or rewind() before
141 output is performed, unless input encountered end-of-file.
143 If a text file is opened with update mode, the implementation is at liberty
144 to open a binary stream instead. This implementation honors the exact mode
147 The stream is fully buffered if and only if it can be determined not to
148 refer to an interactive device. As the generic code of this implementation
149 cannot determine this, _IOLBF (line buffering) is used for all streams.
151 If the mode string begins with but is longer than one of the above sequences
152 the implementation is at liberty to ignore the additional characters, or do
153 implementation-defined things. This implementation only accepts the exact
156 Returns a pointer to the stream handle if successfull, NULL otherwise.
158 FILE * fopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode );
160 /* Close any file currently associated with the given stream. Open the file
161 identified by the given filename with the given mode (equivalent to fopen()),
162 and associate it with the given stream. If filename is a NULL pointer,
163 attempt to change the mode of the given stream.
164 This implementation allows the following mode changes: TODO
165 (Primary use of this function is to redirect stdin, stdout, and stderr.)
167 FILE * freopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode, FILE * _PDCLIB_restrict stream );
169 /* If buf is a NULL pointer, call setvbuf( stream, NULL, _IONBF, BUFSIZ ).
170 If buf is not a NULL pointer, call setvbuf( stream, buf, _IOFBF, BUFSIZ ).
172 void setbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf );
174 /* Set the given stream to the given buffering mode. If buf is not a NULL
175 pointer, use buf as file buffer (of given size). If buf is a NULL pointer,
176 use a buffer of given size allocated internally. _IONBF causes unbuffered
177 behaviour, _IOLBF causes line-buffered behaviour, _IOFBF causes fully
178 buffered behaviour. Calling this function is only valid right after a file is
179 opened, and before any other operation (except for any unsuccessful calls to
180 setvbuf()) has been performed.
181 Returns zero if successful, nonzero otherwise.
183 int setvbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf, int mode, size_t size );
185 /* Formatted input/output functions */
188 Write output to the given stream, as defined by the given format string and
189 0..n subsequent arguments (the argument stack).
191 The format string is written to the given stream verbatim, except for any
192 conversion specifiers included, which start with the letter '%' and are
193 documented below. If the given conversion specifiers require more arguments
194 from the argument stack than provided, behaviour is undefined. Additional
195 arguments not required by conversion specifiers are evaluated but otherwise
198 (The standard specifies the format string is allowed to contain multibyte
199 character sequences as long as it starts and ends in initial shift state,
200 but this is not yet supported by this implementation, which interprets the
201 format string as sequence of char.)
202 TODO: Add multibyte support to printf() functions.
204 A conversion specifier consists of:
205 - Zero or more flags (one of the characters "-+ #0").
206 - Optional minimum field width as decimal integer. Default is padding to the
207 left, using spaces. Note that 0 is taken as a flag, not the beginning of a
208 field width. Note also that a small field width will not result in the
209 truncation of a value.
210 - Optional precision (given as ".#" with # being a decimal integer),
212 - the min. number of digits to appear (diouxX),
213 - the max. number of digits after the decimal point (aAeEfF),
214 - the max. number of significant digits (gG),
215 - the max. number of bytes to be written (s).
216 - behaviour with other conversion specifiers is undefined.
217 - Optional length modifier specifying the size of the argument (one of "hh",
218 "ll", or one of the characters "hljztL").
219 - Conversion specifier character specifying the type of conversion to be
220 applied (and the type of the next argument from the argument stack). One
221 of the characters "diouxXfFeEgGaAcspn%".
223 Minimum field width and/or precision may be given as asterisk ('*') instead
224 of a decimal integer. In this case, the next argument from the argument
225 stack is assumed to be an int value specifying the width / precision. A
226 negative field width is interpreted as flag '-' followed by a positive field
227 width. A negative precision is interpreted as if no precision was given.
230 - Left-justify the conversion result within its field width.
231 + Prefix a '+' on positive signed conversion results. Prefix a '-' on
232 floating conversions resulting in negative zero, or negative values
234 space Prefix a space on positive signed conversion results, or if a signed
235 conversion results in no characters. If both '+' and ' ' are given,
237 # Use an "alternative form" for
238 - 'o' conversion, increasing precision until the first digit of the
240 - 'x' or 'X' conversion, prefixing "0x" or "0X" to nonzero results;
241 - "aAeEfF" conversions, always printing a decimal point even if no
242 digits are following;
243 - 'g' or 'G' conversions, always printing a decimal point even if no
244 digits are following, and not removing trailing zeroes.
245 - behaviour for other conversions is unspecified.
246 0 Use leading zeroes instead of spaces for field width padding. If both
247 '-' and '0' are given, '0' is ignored. If a precision is specified for
248 any of the "diouxX" conversions, '0' is ignored. Behaviour is only
249 defined for "diouxXaAeEfFgG".
252 hh For "diouxX" conversions, the argument from the argument stack is
253 assumed to be of char width. (It will have been subject to integer
254 promotion but will be converted back.) For 'n' conversions, the argument
255 is assumed to be a pointer to signed char.
256 h For "diouxX" conversions, the argument from the argument stack is
257 assumed to be of short int width. (It will have been subject to integer
258 promotion but will be converted back.) For 'n' conversions, the argument
259 is assumed to be a pointer to short int.
260 l For "diouxX" conversions, the argument from the argument stack is
261 assumed to be of long int width. For 'n' conversions, the argument is
262 assumed to be a pointer to short int. For 'c' conversions, the argument
263 is assumed to be a wint_t. For 's' conversions, the argument is assumed
264 to be a pointer to wchar_t. No effect on "aAeEfFgG" conversions.
265 ll For "diouxX" conversions, the argument from the argument stack is
266 assumed to be of long long int width. For 'n' conversions, the argument
267 is assumed to be a pointer to long long int.
268 j For "diouxX" conversions, the argument from the argument stack is
269 assumed to be of intmax_t width. For 'n' conversions, the argument is
270 assumed to be a pointer to intmax_t.
271 z For "diouxX" conversions, the argument from the argument stack is
272 assumed to be of size_t width. For 'n' conversions, the argument is
273 assumed to be a pointer to size_t.
274 t For "diouxX" conversions, the argument from the argument stack is
275 assumed to be of ptrdiff_t width. For 'n' conversions, the argument is
276 assumed to be a pointer to ptrdiff_t.
277 L For "aAeEfFgG" conversions, the argument from the argument stack is
278 assumed to be a long double.
279 Length modifiers appearing for any conversions not mentioned above will have
281 If a length modifier appears with any conversion specifier other than as
282 specified above, the behavior is undefined.
284 CONVERSION SPECIFIERS
285 d,i The argument from the argument stack is assumed to be of type int, and
286 is converted to a signed decimal value with a minimum number of digits
287 as specified by the precision (default 1), padded with leading zeroes.
288 A zero value converted with precision zero yields no output.
289 o The argument from the argument stack is assumed to be of type unsigned
290 int, and is converted to an unsigned octal value, other behaviour being
292 u The argument from the argument stack is assumed to be of type unsigned
293 int, and converted to an unsigned decimal value, other behaviour being
295 x,X The argument from the argument stack is assumed to be of type unsigned
296 int, and converted to an unsigned hexadecimal value, using lowercase
297 "abcdef" for 'x' and uppercase "ABCDEF" for 'X' conversion, other
298 behaviour being as above.
299 f,F The argument from the argument stack is assumed to be of type double,
300 and converted to a decimal floating point in decimal-point notation,
301 with the number of digits after the decimal point as specified by the
302 precision (default 6) and the value being rounded appropriately. If
303 precision is zero (and the '#' flag is not given), no decimal point is
304 printed. At least one digit is always printed before the decimal point.
305 For 'f' conversions, an infinity value is printed as either [-]inf or
306 [-]infinity (, depending on the configuration of this implementation. A
307 NaN value is printed as [-]nan. For 'F' conversions uppercase characters
308 are used for these special values. The flags '-', '+' and ' ' apply as
309 usual to these special values, '#' and '0' have no effect.
310 e,E The argument from the argument stack is assumed to be of type double,
311 and converted to a decimal floating point in normalized exponential
312 notation ([?]d.ddd e±dd). "Normalized" means one nonzero digit before
313 the decimal point, unless the value is zero. The number of digits after
314 the decimal point is specified by the precision (default 6), the value
315 being rounded appropriately. If precision is zero (and the '#' flag is
316 not given), no decimal point is printed. The exponent has at least two
317 digits, and not more than necessary to represent the exponent. If the
318 value is zero, the exponent is zero. The 'e' written to indicate the
319 exponend is uppercase for 'E' conversions.
320 Infinity or NaN values are represented as for 'f' and 'F' conversions,
322 g,G The argument from the argument stack is assumed to be of type double,
323 and converted according to either 'f' or 'e' format for 'g' conversions,
324 or 'F' or 'E' format for 'G' conversions, respectively, with the actual
325 conversion chosen depending on the value. 'e' / 'E' conversion is chosen
326 if the resulting exponent is < -4 or >= the precision (default 1).
327 Trailing zeroes are removed (unless the '#' flag is given). A decimal
328 point appears only if followed by a digit.
329 Infinity or NaN values are represented as for 'f' and 'F' conversions,
331 a,A The argument from the argument stack is assumed to be of type double,
332 and converted to a floating point hexadecimal notation ([?]0xh.hhhh p±d)
333 with one hexadecimal digit (being nonzero if the value is normalized,
334 and otherwise unspecified) before the decimal point, and the number of
335 digits after the decimal point being specified by the precision. If no
336 precision is given, the default is to print as many digits as nevessary
337 to give an exact representation of the value (if FLT_RADIX is a power of
338 2). If no precision is given and FLT_RADIX is not a power of 2, the
339 default is to print as many digits to distinguish values of type double
340 (possibly omitting trailing zeroes). (A precision p is sufficient to
341 distinguish values of the source type if 16^p-1 > b^n where b is
342 FLT_RADIX and n is the number of digits in the significand (to base b)
343 of the source type. A smaller p might suffice depending on the
344 implementation's scheme for determining the digit to the left of the
345 decimal point.) The error has the correct sign for the current rounding
347 Unless the '#' flag is given, no decimal-point is given for zero
349 The 'a' conversion uses lowercase "abcdef", "0x" and 'p', the 'A'
350 conversion uppercase "ABCDEF", "0X" and 'P'.
351 The exponent always has at least one digit, and not more than necessary
352 to represent the decimal exponent of 2. If the value is zero, the
354 Infinity or NaN values are represented as for 'f' and 'F' conversions,
356 Binary implementations are at liberty to chose the hexadecimal digit to
357 the left of the decimal point so that subsequent digits align to nibble
359 c The argument from the argument stack is assumed to be of type int, and
360 converted to a character after the value has been cast to unsigned char.
361 If the 'l' length modifier is given, the argument is assumed to be of
362 type wint_t, and converted as by a "%ls" conversion with no precision
363 and a pointer to a two-element wchar_t array, with the first element
364 being the wint_t argument and the second a '\0' wide character.
365 s The argument from the argument stack is assumed to be a char array (i.e.
366 pointer to char). Characters from that array are printed until a zero
367 byte is encountered or as many bytes as specified by a given precision
369 If the l length modifier is given, the argument from the argument stack
370 is assumed to be a wchar_t array (i.e. pointer to wchar_t). Wide
371 characters from that array are converted to multibyte characters as by
372 calls to wcrtomb() (using a mbstate_t object initialized to zero prior
373 to the first conversion), up to and including the terminating null wide
374 character. The resulting multibyte character sequence is then printed up
375 to but not including the terminating null character. If a precision is
376 given, it specifies the maximum number of bytes to be written (including
377 shift sequences). If the given precision would require access to a wide
378 character one past the end of the array, the array shall contain a '\0'
379 wide character. In no case is a partial multibyte character written.
380 Redundant shift sequences may result if the multibyte characters have a
381 state-dependent encoding.
382 TODO: Clarify these statements regarding %ls.
383 p The argument from the argument stack is assumed to be a void pointer,
384 and converted to a sequence of printing characters in an implementation-
386 This implementation casts the pointer to type intptr_t, and prints the
387 value as if a %#x conversion specifier was given.
388 n The argument from the argument stack is assumed to be a pointer to a
389 signed integer, into which the number of characters written so far by
390 this call to fprintf is stored. The behaviour, should any flags, field
391 widths, or precisions be given is undefined.
392 % A verbatim '%' character is written. No argument is taken from the
395 Returns the number of characters written if successful, a negative value
398 int fprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
400 /* TODO: fscanf() documentation */
402 Write output to the given stream, as defined by the given format string and
403 0..n subsequent arguments (the argument stack).
405 The format string is written to the given stream verbatim, except for any
406 conversion specifiers included, which start with the letter '%' and are
407 documented below. If the given conversion specifiers require more arguments
408 from the argument stack than provided, behaviour is undefined. Additional
409 arguments not required by conversion specifiers are evaluated but otherwise
412 (The standard specifies the format string is allowed to contain multibyte
413 character sequences as long as it starts and ends in initial shift state,
414 but this is not yet supported by this implementation, which interprets the
415 format string as sequence of char.)
416 TODO: Add multibyte support to printf() functions.
418 Read input from the given stream, as defined by the given format string and
419 0..n subsequent arguments (the argument stack).
421 The format string contains a sequence of directives that are expected to
422 match the input. If such a directive fails to match, the function returns
423 (matching error). It also returns if an input error occurs (input error).
426 - one or more whitespaces, matching any number of whitespaces in the input;
427 - printing characters, matching the input verbatim;
428 - conversion specifications, which convert an input sequence into a value as
429 defined by the individual specifier, and store that value in a memory
430 location pointed to by the next pointer on the argument stack. Details are
431 documented below. If there is an insufficient number of pointers on the
432 argument stack, behaviour is undefined. Additional arguments not required
433 by any conversion specifications are evaluated, but otherwise ignored.
435 The format shall be a multibyte character sequence, beginning and ending in its initial
436 shift state. The format is composed of zero or more directives: one or more white-space
437 characters, an ordinary multibyte character (neither % nor a white-space character), or a
438 conversion speci?cation. Each conversion speci?cation is introduced by the character %.
439 After the %, the following appear in sequence:
440 ? An optional assignment-suppressing character *.
441 ? An optional nonzero decimal integer that speci?es the maximum ?eld width (in
443 ? An optional length modi?er that speci?es the size of the receiving object.
444 ? A conversion speci?er character that speci?es the type of conversion to be applied.
445 The fscanf function executes each directive of the format in turn. If a directive fails, as
446 detailed below, the function returns. Failures are described as input failures (due to the
447 occurrence of an encoding error or the unavailability of input characters), or matching
448 failures (due to inappropriate input).
449 A directive composed of white-space character(s) is executed by reading input up to the
450 ?rst non-white-space character (which remains unread), or until no more characters can
452 A directive that is an ordinary multibyte character is executed by reading the next
453 characters of the stream. If any of those characters differ from the ones composing the
454 directive, the directive fails and the differing and subsequent characters remain unread.
455 Similarly, if end-of-?le, an encoding error, or a read error prevents a character from being
456 read, the directive fails.
457 A directive that is a conversion speci?cation de?nes a set of matching input sequences, as
458 described below for each speci?er. A conversion speci?cation is executed in the
460 Input white-space characters (as speci?ed by the isspace function) are skipped, unless
461 the speci?cation includes a [, c, or n speci?er.241)
462 These white-space characters are not counted against a speci?ed ?eld width.
463 An input item is read from the stream, unless the speci?cation includes an n speci?er. An
464 input item is de?ned as the longest sequence of input characters which does not exceed
465 any speci?ed ?eld width and which is, or is a pre?x of, a matching input sequence.242)
466 fscanf pushes back at most one input character onto the input stream. Therefore, some sequences
467 that are acceptable to strtod, strtol, etc., are unacceptable to fscanf.
468 The ?rst character, if any, after the input item remains unread. If the length of the input
469 item is zero, the execution of the directive fails; this condition is a matching failure unless
470 end-of-?le, an encoding error, or a read error prevented input from the stream, in which
471 case it is an input failure.
472 Except in the case of a % speci?er, the input item (or, in the case of a %n directive, the
473 count of input characters) is converted to a type appropriate to the conversion speci?er. If
474 the input item is not a matching sequence, the execution of the directive fails: this
475 condition is a matching failure. Unless assignment suppression was indicated by a *, the
476 result of the conversion is placed in the object pointed to by the ?rst argument following
477 the format argument that has not already received a conversion result. If this object
478 does not have an appropriate type, or if the result of the conversion cannot be represented
479 in the object, the behavior is unde?ned.
480 The length modi?ers and their meanings are:
483 hh For "diouxXn" conversions, the next pointer from the argument stack is
484 assumed to point to a variable of of char width.
485 h For "diouxXn" conversions, the next pointer from the argument stack is
486 assumed to point to a variable of short int width.
487 l For "diouxXn" conversions, the next pointer from the argument stack is
488 assumed to point to a variable of long int width.
489 For "aAeEfFgG" conversions, it is assumed to point to a variable of type
491 For "cs[" conversions, it is assumed to point to a variable of type
493 ll For "diouxXn" conversions, the next pointer from the argument stack is
494 assumed to point to a variable of long long int width.
495 j For "diouxXn" conversions, the next pointer from the argument stack is
496 assumed to point to a variable of intmax_t width.
497 z For "diouxXn" conversions, the next pointer from the argument stack is
498 assumed to point to a variable of size_t width.
499 t For "diouxXn" conversions, the next pointer from the argument stack is
500 assumed to point to a variable of ptrdiff_t width.
501 L For "aAeEfFgG" conversions, the next pointer from the argument stack is
502 assumed to point to a variable of type long double.
503 Length modifiers appearing for any conversions not mentioned above will have
505 If a length modifier appears with any conversion specifier other than as
506 specified above, the behavior is undefined.
508 CONVERSION SPECIFIERS
509 d Matches an (optionally signed) decimal integer of the format expected
510 by strtol() with base 10. The next pointer from the argument stack is
511 assumed to point to a signed integer.
512 i Matches an (optionally signed) integer of the format expected by
513 strtol() with base 0. The next pointer from the argument stack is
514 assumed to point to a signed integer.
515 o Matches an (optionally signed) octal integer of the format expected by
516 strtoul() with base 8. The next pointer from the argument stack is
517 assumed to point to an unsigned integer.
518 u Matches an (optionally signed) decimal integer of the format expected
519 by strtoul() with base 10. The next pointer from the argument stack is
520 assumed to point to an unsigned integer.
521 x Matches an (optionally signed) hexadecimal integer of the format
522 expected by strtoul() with base 16. The next pointer from the argument
523 stack is assumed to point to an unsigned integer.
524 aefg Matches an (optionally signed) floating point number, infinity, or not-
525 a-number-value of the format expected by strtod(). The next pointer
526 from the argument stack is assumed to point to a float.
527 c Matches a number of characters as specified by the field width (default
528 1). The next pointer from the argument stack is assumed to point to a
529 character array large enough to hold that many characters.
530 If the 'l' length modifier is given, the input is assumed to match a
531 sequence of multibyte characters (starting in the initial shift state),
532 which will be converted to a wide character sequence as by successive
533 calls to mbrtowc() with a mbstate_t object initialized to zero prior to
534 the first conversion. The next pointer from the argument stack is
535 assumed to point to a wchar_t array large enough to hold that many
537 In either case, note that no '\0' character is added to terminate the
539 s Matches a sequence of non-white-space characters. The next pointer from
540 the argument stack is assumed to point to a character array large
541 enough to hold the sequence including terminating '\0' character.
542 If the 'l' length modifier is given, the input is assumed to match a
543 sequence of multibyte characters (starting in the initial shift state),
544 which will be converted to a wide character sequence as by a call to
545 mbrtowc() with a mbstate_t object initialized to zero prior to the
546 first conversion. The next pointer from the argument stack is assumed
547 to point to a wchar_t array large enough to hold the sequence including
548 terminating '\0' character.
549 [ Matches a nonempty sequence consisting of any of those characters
550 specified between itself and a corresponding closing bracket (']').
551 If the first character in the list is a circumflex ('^'), this matches
552 a nonempty sequence consisting of any characters NOT specified. If the
553 closing bracket appears as the first character in the scanset ("[]" or
554 "[^]", it is assumed to belong to the scanset, which then ends with the
555 NEXT closing bracket.
556 If there is a '-' character in the scanset which is not the first after
557 the opening bracket (or the circumflex, see above) or the last in the
558 scanset, behaviour is implementation-defined. This implementation
559 handles this character like any other.
561 The extend of the input field is determined byte-by-byte for the above
562 conversions ('c', 's', '['), with no special provisions being made for
563 multibyte characters. The resulting field is nevertheless a multibyte
564 sequence begining in intial shift state.
566 p Matches a sequence of characters as produced by the printf() "%p"
567 conversion. The next pointer from the argument stack is assumed to
568 point to a void pointer, which will be filled with the same location
569 as the pointer used in the printf() statement. Note that behaviour is
570 undefined if the input value is not the result of an earlier printf()
572 n Does not read input. The next pointer from the argument stack is
573 assumed to point to a signed integer, into which the number of
574 characters read from input so far by this call to fscanf() is stored.
575 This does not affect the return value of fscanf(). The behaviour,
576 should an assignment-supressing character of field width be given,
578 This can be used to test the success of literal matches and suppressed
580 % Matches a single, verbatim '%' character.
582 A, E, F, G and X are valid, and equivalent to their lowercase counterparts.
584 Returns the number of input items successfully assigned. This can be zero if
585 an early mismatch occurs. Returns EOF if an input failure occurs before the
588 int fscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
590 /* Equivalent to fprintf( stdout, format, ... ). */
591 int printf( const char * _PDCLIB_restrict format, ... );
593 /* Equivalent to fscanf( stdin, format, ... ). */
594 int scanf( const char * _PDCLIB_restrict format, ... );
596 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
597 written into the buffer pointed to by s, instead of stdout, and that any
598 characters beyond the (n-1)th are discarded. The (n)th character is
599 replaced by a '\0' character in this case.
600 Returns the number of characters that would have been written (not counting
601 the terminating '\0' character) if n had been sufficiently large, if
602 successful, and a negative number if an encoding error ocurred.
604 int snprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, ... );
606 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
607 written into the buffer pointed to by s, instead of stdout.
609 int sprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
611 /* Equivalent to fscanf( stdin, format, ... ), except that the input is read
612 from the buffer pointed to by s, instead of stdin.
614 int sscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
616 /* Equivalent to fprintf( stream, format, ... ), except that the argument stack
617 is passed as va_list parameter. Note that va_list is not declared by
620 int vfprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
622 /* Equivalent to fscanf( stream, format, ... ), except that the argument stack
623 is passed as va_list parameter. Note that va_list is not declared by
626 int vfscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
628 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
629 is passed as va_list parameter. Note that va_list is not declared by
632 int vprintf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
634 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
635 is passed as va_list parameter. Note that va_list is not declared by
638 int vscanf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
640 /* Equivalent to snprintf( s, n, format, ... ), except that the argument stack
641 is passed as va_list parameter. Note that va_list is not declared by
644 int vsnprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
646 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
647 is passed as va_list parameter, and the result is written to the buffer
648 pointed to by s, instead of stdout. Note that va_list is not declared by
651 int vsprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
653 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
654 is passed as va_list parameter, and the input is read from the buffer
655 pointed to by s, instead of stdin. Note that va_list is not declared by
658 int vsscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
660 /* Character input/output functions */
662 /* Retrieve the next character from given stream.
663 Returns the character, EOF otherwise.
664 If end-of-file is reached, the EOF indicator of the stream is set.
665 If a read error occurs, the error indicator of the stream is set.
667 int fgetc( FILE * stream );
669 /* Read at most n-1 characters from given stream into the array s, stopping at
670 \n or EOF. Terminate the read string with \n. If EOF is encountered before
671 any characters are read, leave the contents of s unchanged.
672 Returns s if successful, NULL otherwise.
673 If a read error occurs, the error indicator of the stream is set. In this
674 case, the contents of s are indeterminate.
676 char * fgets( char * _PDCLIB_restrict s, int n, FILE * _PDCLIB_restrict stream );
678 /* Write the value c (cast to unsigned char) to the given stream.
679 Returns c if successful, EOF otherwise.
680 If a write error occurs, sets the error indicator of the stream is set.
682 int fputc( int c, FILE * stream );
684 /* Write the string s (not including the terminating \0) to the given stream.
685 Returns a value >=0 if successful, EOF otherwise.
686 This implementation does set the error indicator of the stream if a write
689 int fputs( const char * _PDCLIB_restrict s, FILE * _PDCLIB_restrict stream );
691 /* Equivalent to fgetc( stream ), but may be implemented as a macro that
692 evaluates its parameter more than once.
694 #define getc( stream ) fgetc( stream )
696 /* Equivalent to fgetc( stdin ), but may be implemented as a macro. */
697 #define getchar() fgetc( stdin )
699 /* Read characters from given stream into the array s, stopping at \n or EOF.
700 The string read is terminated with \0. Returns s if successful. If EOF is
701 encountered before any characters are read, the contents of s are unchanged,
702 and NULL is returned. If a read error occurs, the contents of s are indeter-
703 minate, and NULL is returned.
705 char * gets( char * s );
707 /* Equivalent to fputc( c, stream ), but may be implemented as a macro that
708 evaluates its parameter more than once.
710 #define putc( c, stream ) fputc( c, stream )
712 /* Equivalent to fputc( c, stdout ), but may be implemented as a macro that
713 evaluates its parameter more than once.
715 int putchar( int c );
717 /* Write the string s (not including the terminating \0) to stdout, and append
718 a newline to the output. Returns a value >= 0 when successful, EOF if a
719 write error occurred.
721 int puts( const char * s );
723 /* Push the value c (cast to unsigned char) back onto the given (input) stream.
724 A character pushed back in this way will be delivered by subsequent read
725 operations (and skipped by subsequent file positioning operations) as if it
726 has not been read. The external representation of the stream is unaffected
727 by this pushback (it is a buffer operation). One character of pushback is
728 guaranteed, further pushbacks may fail. EOF as value for c does not change
729 the input stream and results in failure of the function.
730 For text files, the file position indicator is indeterminate until all
731 pushed-back characters are read. For binary files, the file position
732 indicator is decremented by each successful call of ungetc(). If the file
733 position indicator for a binary file was zero before the call of ungetc(),
734 behaviour is undefined. (Older versions of the library allowed such a call.)
735 Returns the pushed-back character if successful, EOF if it fails.
737 int ungetc( int c, FILE * stream );
739 /* Direct input/output functions */
741 /* Read up to nmemb elements of given size from given stream into the buffer
742 pointed to by ptr. Returns the number of elements successfully read, which
743 may be less than nmemb if a read error or EOF is encountered. If a read
744 error is encountered, the value of the file position indicator is
745 indeterminate. If a partial element is read, its value is indeterminate.
746 If size or nmemb are zero, the function does nothing and returns zero.
748 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
750 /* Write up to nmemb elements of given size from buffer pointed to by ptr to
751 the given stream. Returns the number of elements successfully written, which
752 will be less than nmemb only if a write error is encountered. If a write
753 error is encountered, the value of the file position indicator is
754 indeterminate. If size or nmemb are zero, the function does nothing and
757 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
759 /* File positioning functions */
761 /* Store the current position indicator (and, where appropriate, the current
762 mbstate_t status object) for the given stream into the given pos object. The
763 actual contents of the object are unspecified, but it can be used as second
764 parameter to fsetpos() to reposition the stream to the exact position and
765 parse state at the time fgetpos() was called.
766 Returns zero if successful, nonzero otherwise.
767 TODO: Implementation-defined errno setting for fgetpos().
769 int fgetpos( FILE * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
771 /* Set the position indicator for the given stream to the given offset from:
772 - the beginning of the file if whence is SEEK_SET,
773 - the current value of the position indicator if whence is SEEK_CUR,
774 - end-of-file if whence is SEEK_END.
775 On text streams, non-zero offsets are only allowed with SEEK_SET, and must
776 have been returned by ftell() for the same file.
777 Any characters buffered by ungetc() are dropped, the end-of-file indicator
778 for the stream is cleared. If the given stream is an update stream, the next
779 operation after a successful fseek() may be either input or output.
780 Returns zero if successful, nonzero otherwise. If a read/write error occurs,
781 the error indicator for the given stream is set.
783 int fseek( FILE * stream, long int offset, int whence );
785 /* Set the position indicator (and, where appropriate the mbstate_t status
786 object) for the given stream to the given pos object (created by an earlier
787 call to fgetpos() on the same file).
788 Any characters buffered by ungetc() are dropped, the end-of-file indicator
789 for the stream is cleared. If the given stream is an update stream, the next
790 operation after a successful fsetpos() may be either input or output.
791 Returns zero if successful, nonzero otherwise. If a read/write error occurs,
792 the error indicator for the given stream is set.
793 TODO: Implementation-defined errno setting for fsetpos().
795 int fsetpos( FILE * stream, const fpos_t * pos );
797 /* Return the current offset of the given stream from the beginning of the
798 associated file. For text streams, the exact value returned is unspecified
799 (and may not be equal to the number of characters), but may be used in
800 subsequent calls to fseek().
801 Returns -1L if unsuccessful.
802 TODO: Implementation-defined errno setting for ftell().
804 long int ftell( FILE * stream );
806 /* Equivalent to (void)fseek( stream, 0L, SEEK_SET ), except that the error
807 indicator for the stream is also cleared.
809 void rewind( FILE * stream );
811 /* Error-handling functions */
813 /* Clear the end-of-file and error indicators for the given stream. */
814 void clearerr( FILE * stream );
816 /* Return zero if the end-of-file indicator for the given stream is not set,
819 int feof( FILE * stream );
821 /* Return zero if the error indicator for the given stream is not set, nonzero
824 int ferror( FILE * stream );
826 /* If s is neither a NULL pointer nor an empty string, print the string to
827 stderr (with appended colon (':') and a space) first. In any case, print an
828 error message depending on the current value of errno (being the same as if
829 strerror( errno ) had been called).
831 void perror( const char * s );