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