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 extern struct _PDCLIB_file_t * stdin;
48 extern struct _PDCLIB_file_t * stdout;
49 extern struct _PDCLIB_file_t * stderr;
51 /* Operations on files */
53 /* Remove the given file.
54 Returns zero if successful, non-zero otherwise.
55 This implementation does detect if the filename corresponds to an open file,
56 and closes it before attempting the rename.
58 int remove( const char * filename );
60 /* Rename the given old file to the given new name.
61 Returns zero if successful, non-zero otherwise.
62 This implementation does detect if the old filename corresponds to an open
63 file, and closes it before attempting the rename.
64 If the already is a file with the new filename, behaviour is defined by the
67 int rename( const char * old, const char * new );
69 /* Open a temporary file with mode "wb+", i.e. binary-update. Remove the file
70 automatically if it is closed or the program exits normally (by returning
71 from main() or calling exit()).
72 Returns a pointer to a FILE handle for this file.
73 This implementation does not remove temporary files if the process aborts
74 abnormally (e.g. abort()).
76 struct _PDCLIB_file_t * tmpfile( void );
78 /* Generate a file name that is not equal to any existing filename AT THE TIME
79 OF GENERATION. Generate a different name each time it is called.
80 Returns a pointer to an internal static buffer containing the filename if s
81 is a NULL pointer. (This is not thread-safe!)
82 Returns s if it is not a NULL pointer (s is then assumed to point to an array
83 of at least L_tmpnam characters).
84 Returns NULL if unable to generate a suitable name (because all possible
85 names already exist, or the function has been called TMP_MAX times already).
86 Note that this implementation cannot guarantee a file of the name generated
87 is not generated between the call to this function and a subsequent fopen().
89 char * tmpnam( char * s );
91 /* File access functions */
93 /* Close the file associated with the given stream (after flushing its buffers).
94 Returns zero if successful, EOF if any errors occur.
96 int fclose( struct _PDCLIB_file_t * stream );
98 /* Flush the buffers of the given output stream. If the stream is an input
99 stream, or an update stream with the last operation being an input operation,
100 behaviour is undefined.
101 If stream is a NULL pointer, perform the buffer flushing for all applicable
103 Returns zero if successful, EOF if a write error occurs.
104 Sets the error indicator of the stream if a write error occurs.
106 int fflush( struct _PDCLIB_file_t * stream );
108 /* Open the file with the given filename in the given mode, and return a stream
109 handle for it in which error and end-of-file indicator are cleared. Defined
113 text files binary files
114 without update "r" "rb"
115 with update "r+" "rb+" or "r+b"
117 Opening in read mode fails if no file with the given filename exists, or if
121 text files binary files
122 without update "w" "wb"
123 with update "w+" "wb+" or "w+b"
125 With write modes, if a file with the given filename already exists, it is
126 truncated to zero length.
129 text files binary files
130 without update "a" "ab"
131 with update "a+" "ab+" or "a+b"
133 With update modes, if a file with the given filename already exists, it is
134 not truncated to zero length, but all writes are forced to end-of-file (this
135 regardless to fseek() calls). Note that binary files opened in append mode
136 might have their end-of-file padded with '\0' characters.
138 Update modes mean that both input and output functions can be performed on
139 the stream, but output must be terminated with a call to either fflush(),
140 fseek(), fsetpos(), or rewind() before input is performed, and input must
141 be terminated with a call to either fseek(), fsetpos(), or rewind() before
142 output is performed, unless input encountered end-of-file.
144 If a text file is opened with update mode, the implementation is at liberty
145 to open a binary stream instead. This implementation honors the exact mode
148 The stream is fully buffered if and only if it can be determined not to
149 refer to an interactive device.
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 struct _PDCLIB_file_t * 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 struct _PDCLIB_file_t * freopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode, struct _PDCLIB_file_t * _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( struct _PDCLIB_file_t * _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( struct _PDCLIB_file_t * _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 edd). "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 pd)
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( struct _PDCLIB_file_t * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
400 /* TODO: fscanf() documentation */
402 Read input from a given stream, as defined by the given format string, and
403 store converted input in the objects pointed to by 0..n subsequent arguments
404 (the argument stack).
406 The format string contains a sequence of directives that are expected to
407 match the input. If such a directive fails to match, the function returns
408 (matching error). It also returns if an input error occurs (input error).
411 - one or more whitespaces, matching any number of whitespaces in the input;
412 - printing characters, matching the input verbatim;
413 - conversion specifications, which convert an input sequence into a value as
414 defined by the individual specifier, and store that value in a memory
415 location pointed to by the next pointer on the argument stack. Details are
416 documented below. If there is an insufficient number of pointers on the
417 argument stack, behaviour is undefined. Additional arguments not required
418 by any conversion specifications are evaluated, but otherwise ignored.
420 (The standard specifies the format string is allowed to contain multibyte
421 character sequences as long as it starts and ends in initial shift state,
422 but this is not yet supported by this implementation, which interprets the
423 format string as sequence of char.)
424 TODO: Add multibyte support to scanf() functions.
426 A conversion specifier consists of:
427 - Optional assignment-suppressing character ('*') that makes the conversion
428 read input as usual, but does not assign the conversion result.
429 - Optional maximum field width as decimal integer.
430 - Optional length modifier specifying the size of the argument (one of "hh",
431 "ll", or one of the characters "hljztL").
432 - Conversion specifier character specifying the type of conversion to be
433 applied (and the type of the next argument from the argument stack). One
434 of the characters "diouxXaAeEfFgGcs[pn%".
437 hh For "diouxXn" conversions, the next pointer from the argument stack is
438 assumed to point to a variable of of char width.
439 h For "diouxXn" conversions, the next pointer from the argument stack is
440 assumed to point to a variable of short int width.
441 l For "diouxXn" conversions, the next pointer from the argument stack is
442 assumed to point to a variable of long int width.
443 For "aAeEfFgG" conversions, it is assumed to point to a variable of type
445 For "cs[" conversions, it is assumed to point to a variable of type
447 ll For "diouxXn" conversions, the next pointer from the argument stack is
448 assumed to point to a variable of long long int width.
449 j For "diouxXn" conversions, the next pointer from the argument stack is
450 assumed to point to a variable of intmax_t width.
451 z For "diouxXn" conversions, the next pointer from the argument stack is
452 assumed to point to a variable of size_t width.
453 t For "diouxXn" conversions, the next pointer from the argument stack is
454 assumed to point to a variable of ptrdiff_t width.
455 L For "aAeEfFgG" conversions, the next pointer from the argument stack is
456 assumed to point to a variable of type long double.
457 Length modifiers appearing for any conversions not mentioned above will have
459 If a length modifier appears with any conversion specifier other than as
460 specified above, the behavior is undefined.
462 CONVERSION SPECIFIERS
463 d Matches an (optionally signed) decimal integer of the format expected
464 by strtol() with base 10. The next pointer from the argument stack is
465 assumed to point to a signed integer.
466 i Matches an (optionally signed) integer of the format expected by
467 strtol() with base 0. The next pointer from the argument stack is
468 assumed to point to a signed integer.
469 o Matches an (optionally signed) octal integer of the format expected by
470 strtoul() with base 8. The next pointer from the argument stack is
471 assumed to point to an unsigned integer.
472 u Matches an (optionally signed) decimal integer of the format expected
473 by strtoul() with base 10. The next pointer from the argument stack is
474 assumed to point to an unsigned integer.
475 x Matches an (optionally signed) hexadecimal integer of the format
476 expected by strtoul() with base 16. The next pointer from the argument
477 stack is assumed to point to an unsigned integer.
478 aefg Matches an (optionally signed) floating point number, infinity, or not-
479 a-number-value of the format expected by strtod(). The next pointer
480 from the argument stack is assumed to point to a float.
481 c Matches a number of characters as specified by the field width (default
482 1). The next pointer from the argument stack is assumed to point to a
483 character array large enough to hold that many characters.
484 If the 'l' length modifier is given, the input is assumed to match a
485 sequence of multibyte characters (starting in the initial shift state),
486 which will be converted to a wide character sequence as by successive
487 calls to mbrtowc() with a mbstate_t object initialized to zero prior to
488 the first conversion. The next pointer from the argument stack is
489 assumed to point to a wchar_t array large enough to hold that many
491 In either case, note that no '\0' character is added to terminate the
493 s Matches a sequence of non-white-space characters. The next pointer from
494 the argument stack is assumed to point to a character array large
495 enough to hold the sequence including terminating '\0' character.
496 If the 'l' length modifier is given, the input is assumed to match a
497 sequence of multibyte characters (starting in the initial shift state),
498 which will be converted to a wide character sequence as by a call to
499 mbrtowc() with a mbstate_t object initialized to zero prior to the
500 first conversion. The next pointer from the argument stack is assumed
501 to point to a wchar_t array large enough to hold the sequence including
502 terminating '\0' character.
503 [ Matches a nonempty sequence consisting of any of those characters
504 specified between itself and a corresponding closing bracket (']').
505 If the first character in the list is a circumflex ('^'), this matches
506 a nonempty sequence consisting of any characters NOT specified. If the
507 closing bracket appears as the first character in the scanset ("[]" or
508 "[^]", it is assumed to belong to the scanset, which then ends with the
509 NEXT closing bracket.
510 If there is a '-' character in the scanset which is not the first after
511 the opening bracket (or the circumflex, see above) or the last in the
512 scanset, behaviour is implementation-defined. This implementation
513 handles this character like any other.
515 The extend of the input field is determined byte-by-byte for the above
516 conversions ('c', 's', '['), with no special provisions being made for
517 multibyte characters. The resulting field is nevertheless a multibyte
518 sequence begining in intial shift state.
520 p Matches a sequence of characters as produced by the printf() "%p"
521 conversion. The next pointer from the argument stack is assumed to
522 point to a void pointer, which will be filled with the same location
523 as the pointer used in the printf() statement. Note that behaviour is
524 undefined if the input value is not the result of an earlier printf()
526 n Does not read input. The next pointer from the argument stack is
527 assumed to point to a signed integer, into which the number of
528 characters read from input so far by this call to fscanf() is stored.
529 This does not affect the return value of fscanf(). The behaviour,
530 should an assignment-supressing character of field width be given,
532 This can be used to test the success of literal matches and suppressed
534 % Matches a single, verbatim '%' character.
536 A, E, F, G and X are valid, and equivalent to their lowercase counterparts.
538 All conversions except [, c, or n imply that whitespace characters from the
539 input stream are consumed until a non-whitespace character is encountered.
540 Such whitespaces do not count against a maximum field width.
542 Conversions push at most one character back into the input stream. That
543 implies that some character sequences converted by the strtol() and strtod()
544 function families are not converted identically by the scnaf() function
547 Returns the number of input items successfully assigned. This can be zero if
548 an early mismatch occurs. Returns EOF if an input failure occurs before the
551 int fscanf( struct _PDCLIB_file_t * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
553 /* Equivalent to fprintf( stdout, format, ... ). */
554 int printf( const char * _PDCLIB_restrict format, ... );
556 /* Equivalent to fscanf( stdin, format, ... ). */
557 int scanf( const char * _PDCLIB_restrict format, ... );
559 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
560 written into the buffer pointed to by s, instead of stdout, and that any
561 characters beyond the (n-1)th are discarded. The (n)th character is
562 replaced by a '\0' character in this case.
563 Returns the number of characters that would have been written (not counting
564 the terminating '\0' character) if n had been sufficiently large, if
565 successful, and a negative number if an encoding error ocurred.
567 int snprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, ... );
569 /* Equivalent to fprintf( stdout, format, ... ), except that the result is
570 written into the buffer pointed to by s, instead of stdout.
572 int sprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
574 /* Equivalent to fscanf( stdin, format, ... ), except that the input is read
575 from the buffer pointed to by s, instead of stdin.
577 int sscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
579 /* Equivalent to fprintf( stream, format, ... ), except that the argument stack
580 is passed as va_list parameter. Note that va_list is not declared by
583 int vfprintf( struct _PDCLIB_file_t * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
585 /* Equivalent to fscanf( stream, format, ... ), except that the argument stack
586 is passed as va_list parameter. Note that va_list is not declared by
589 int vfscanf( struct _PDCLIB_file_t * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
591 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
592 is passed as va_list parameter. Note that va_list is not declared by
595 int vprintf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
597 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
598 is passed as va_list parameter. Note that va_list is not declared by
601 int vscanf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
603 /* Equivalent to snprintf( s, n, format, ... ), except that the argument stack
604 is passed as va_list parameter. Note that va_list is not declared by
607 int vsnprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
609 /* Equivalent to fprintf( stdout, format, ... ), except that the argument stack
610 is passed as va_list parameter, and the result is written to the buffer
611 pointed to by s, instead of stdout. Note that va_list is not declared by
614 int vsprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
616 /* Equivalent to fscanf( stdin, format, ... ), except that the argument stack
617 is passed as va_list parameter, and the input is read from the buffer
618 pointed to by s, instead of stdin. Note that va_list is not declared by
621 int vsscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
623 /* Character input/output functions */
625 /* Retrieve the next character from given stream.
626 Returns the character, EOF otherwise.
627 If end-of-file is reached, the EOF indicator of the stream is set.
628 If a read error occurs, the error indicator of the stream is set.
630 int fgetc( struct _PDCLIB_file_t * stream );
632 /* Read at most n-1 characters from given stream into the array s, stopping at
633 \n or EOF. Terminate the read string with \n. If EOF is encountered before
634 any characters are read, leave the contents of s unchanged.
635 Returns s if successful, NULL otherwise.
636 If a read error occurs, the error indicator of the stream is set. In this
637 case, the contents of s are indeterminate.
639 char * fgets( char * _PDCLIB_restrict s, int n, struct _PDCLIB_file_t * _PDCLIB_restrict stream );
641 /* Write the value c (cast to unsigned char) to the given stream.
642 Returns c if successful, EOF otherwise.
643 If a write error occurs, sets the error indicator of the stream is set.
645 int fputc( int c, struct _PDCLIB_file_t * stream );
647 /* Write the string s (not including the terminating \0) to the given stream.
648 Returns a value >=0 if successful, EOF otherwise.
649 This implementation does set the error indicator of the stream if a write
652 int fputs( const char * _PDCLIB_restrict s, struct _PDCLIB_file_t * _PDCLIB_restrict stream );
654 /* Equivalent to fgetc( stream ), but may be implemented as a macro that
655 evaluates its parameter more than once.
657 #define getc( stream ) fgetc( stream )
659 /* Equivalent to fgetc( stdin ), but may be implemented as a macro. */
660 #define getchar() fgetc( stdin )
662 /* Read characters from given stream into the array s, stopping at \n or EOF.
663 The string read is terminated with \0. Returns s if successful. If EOF is
664 encountered before any characters are read, the contents of s are unchanged,
665 and NULL is returned. If a read error occurs, the contents of s are indeter-
666 minate, and NULL is returned.
668 char * gets( char * s );
670 /* Equivalent to fputc( c, stream ), but may be implemented as a macro that
671 evaluates its parameter more than once.
673 #define putc( c, stream ) fputc( c, stream )
675 /* Equivalent to fputc( c, stdout ), but may be implemented as a macro that
676 evaluates its parameter more than once.
678 #define putchar( c ) putc( c, stdout )
680 /* Write the string s (not including the terminating \0) to stdout, and append
681 a newline to the output. Returns a value >= 0 when successful, EOF if a
682 write error occurred.
684 int puts( const char * s );
686 /* Push the value c (cast to unsigned char) back onto the given (input) stream.
687 A character pushed back in this way will be delivered by subsequent read
688 operations (and skipped by subsequent file positioning operations) as if it
689 has not been read. The external representation of the stream is unaffected
690 by this pushback (it is a buffer operation). One character of pushback is
691 guaranteed, further pushbacks may fail. EOF as value for c does not change
692 the input stream and results in failure of the function.
693 For text files, the file position indicator is indeterminate until all
694 pushed-back characters are read. For binary files, the file position
695 indicator is decremented by each successful call of ungetc(). If the file
696 position indicator for a binary file was zero before the call of ungetc(),
697 behaviour is undefined. (Older versions of the library allowed such a call.)
698 Returns the pushed-back character if successful, EOF if it fails.
700 int ungetc( int c, struct _PDCLIB_file_t * stream );
702 /* Direct input/output functions */
704 /* Read up to nmemb elements of given size from given stream into the buffer
705 pointed to by ptr. Returns the number of elements successfully read, which
706 may be less than nmemb if a read error or EOF is encountered. If a read
707 error is encountered, the value of the file position indicator is
708 indeterminate. If a partial element is read, its value is indeterminate.
709 If size or nmemb are zero, the function does nothing and returns zero.
711 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, struct _PDCLIB_file_t * _PDCLIB_restrict stream );
713 /* Write up to nmemb elements of given size from buffer pointed to by ptr to
714 the given stream. Returns the number of elements successfully written, which
715 will be less than nmemb only if a write error is encountered. If a write
716 error is encountered, the value of the file position indicator is
717 indeterminate. If size or nmemb are zero, the function does nothing and
720 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, struct _PDCLIB_file_t * _PDCLIB_restrict stream );
722 /* File positioning functions */
724 /* Store the current position indicator (and, where appropriate, the current
725 mbstate_t status object) for the given stream into the given pos object. The
726 actual contents of the object are unspecified, but it can be used as second
727 parameter to fsetpos() to reposition the stream to the exact position and
728 parse state at the time fgetpos() was called.
729 Returns zero if successful, nonzero otherwise.
730 TODO: Implementation-defined errno setting for fgetpos().
732 int fgetpos( struct _PDCLIB_file_t * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
734 /* Set the position indicator for the given stream to the given offset from:
735 - the beginning of the file if whence is SEEK_SET,
736 - the current value of the position indicator if whence is SEEK_CUR,
737 - end-of-file if whence is SEEK_END.
738 On text streams, non-zero offsets are only allowed with SEEK_SET, and must
739 have been returned by ftell() for the same file.
740 Any characters buffered by ungetc() are dropped, the end-of-file indicator
741 for the stream is cleared. If the given stream is an update stream, the next
742 operation after a successful fseek() may be either input or output.
743 Returns zero if successful, nonzero otherwise. If a read/write error occurs,
744 the error indicator for the given stream is set.
746 int fseek( struct _PDCLIB_file_t * stream, long int offset, int whence );
748 /* Set the position indicator (and, where appropriate the mbstate_t status
749 object) for the given stream to the given pos object (created by an earlier
750 call to fgetpos() on the same file).
751 Any characters buffered by ungetc() are dropped, the end-of-file indicator
752 for the stream is cleared. If the given stream is an update stream, the next
753 operation after a successful fsetpos() may be either input or output.
754 Returns zero if successful, nonzero otherwise. If a read/write error occurs,
755 the error indicator for the given stream is set.
756 TODO: Implementation-defined errno setting for fsetpos().
758 int fsetpos( struct _PDCLIB_file_t * stream, const fpos_t * pos );
760 /* Return the current offset of the given stream from the beginning of the
761 associated file. For text streams, the exact value returned is unspecified
762 (and may not be equal to the number of characters), but may be used in
763 subsequent calls to fseek().
764 Returns -1L if unsuccessful.
765 TODO: Implementation-defined errno setting for ftell().
767 long int ftell( struct _PDCLIB_file_t * stream );
769 /* Equivalent to (void)fseek( stream, 0L, SEEK_SET ), except that the error
770 indicator for the stream is also cleared.
772 void rewind( struct _PDCLIB_file_t * stream );
774 /* Error-handling functions */
776 /* Clear the end-of-file and error indicators for the given stream. */
777 void clearerr( struct _PDCLIB_file_t * stream );
779 /* Return zero if the end-of-file indicator for the given stream is not set,
782 int feof( struct _PDCLIB_file_t * stream );
784 /* Return zero if the error indicator for the given stream is not set, nonzero
787 int ferror( struct _PDCLIB_file_t * stream );
789 /* If s is neither a NULL pointer nor an empty string, print the string to
790 stderr (with appended colon (':') and a space) first. In any case, print an
791 error message depending on the current value of errno (being the same as if
792 strerror( errno ) had been called).
794 void perror( const char * s );