1 /** @file 2 Macros, types, and functions for performing I/O. 3 4 The following functions are declared in this file:<BR> 5 @verbatim 6 ################### Operations on files. #### 7 int remove (const char *FileName); 8 int rename (const char *, const char *); 9 FILE *tmpfile (void); 10 char *tmpnam (char *); 11 12 ################### File access functions. #### 13 int fclose (FILE *); 14 int fflush (FILE *); 15 FILE *fopen (const char * __restrict , 16 const char * __restrict); 17 FILE *freopen (const char * __restrict, 18 const char * __restrict, FILE * __restrict); 19 void setbuf (FILE * __restrict, char * __restrict); 20 int setvbuf (FILE * __restrict, char * __restrict, 21 int, size_t); 22 23 ################### Formatted Input/Output Functions. #### 24 int fprintf (FILE * __restrict stream, 25 const char * __restrict format, ...); 26 int fscanf (FILE * __restrict, const char * __restrict, ...); 27 int printf (const char * __restrict, ...); 28 int scanf (const char * __restrict, ...); 29 int sprintf (char * __restrict, const char * __restrict, ...); 30 int sscanf (const char * __restrict, 31 const char * __restrict, ...); 32 int vfprintf (FILE * __restrict, 33 const char * __restrict, va_list); 34 int vprintf (const char * __restrict, va_list); 35 int vsprintf (char * __restrict, 36 const char * __restrict, va_list); 37 38 ################### Character Input/Output Functions. #### 39 int fgetc (FILE *); 40 char *fgets (char * __restrict, int, FILE * __restrict); 41 int fputc (int, FILE *); 42 int fputs (const char * __restrict, FILE * __restrict); 43 int getc (FILE *); 44 int getchar (void); 45 char *gets (char *); 46 int putc (int, FILE *); 47 int putchar (int); 48 int puts (const char *); 49 int ungetc (int, FILE *); 50 51 ################### Direct Input/Output Functions. #### 52 size_t fread (void * __restrict, size_t, size_t, 53 FILE * __restrict); 54 size_t fwrite (const void * __restrict, size_t, size_t, 55 FILE * __restrict); 56 57 ################### File Positioning Functions. #### 58 int fgetpos (FILE * __restrict, fpos_t * __restrict); 59 int fseek (FILE *, long, int); 60 int fsetpos (FILE *, const fpos_t *); 61 long ftell (FILE *); 62 void rewind (FILE *); 63 64 ################### Error-handling Functions. #### 65 void clearerr (FILE *); 66 int feof (FILE *); 67 int ferror (FILE *); 68 void perror (const char *); 69 70 ################### Functions NOT specified by C95 #### 71 72 FILE *fdopen (int, const char *); 73 void flockfile (FILE *); 74 int ftrylockfile (FILE *); 75 void funlockfile (FILE *); 76 int getc_unlocked (FILE *); 77 int getchar_unlocked(void); 78 int putc_unlocked (int, FILE *); 79 int putchar_unlocked(int); 80 int pclose (FILE *); 81 FILE *popen (const char *, const char *); 82 int snprintf (char * __restrict, size_t, 83 const char * __restrict, ...); 84 int vsnprintf (char * __restrict, size_t, 85 const char * __restrict, va_list); 86 char *mkdtemp (char *); 87 int mkstemp (char *); 88 char *mktemp (char *); 89 char *tempnam (const char *, const char *); 90 int fseeko (FILE *, off_t, int); 91 char *fgetln (FILE * __restrict, size_t * __restrict); 92 char *fparseln (FILE *, size_t *, size_t *, const char[3], int); 93 int fpurge (FILE *); 94 void setbuffer (FILE *, char *, int); 95 int setlinebuf (FILE *); 96 int vasprintf (char ** __restrict, const char * __restrict, 97 va_list); 98 int vscanf (const char * __restrict, va_list); 99 int vsscanf (const char * __restrict, 100 const char * __restrict, va_list); 101 @endverbatim 102 103 @note To fit things in six character monocase externals, the stdio 104 code uses the prefix `__s' for stdio objects, typically followed 105 by a three-character attempt at a mnemonic. 106 107 108 Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR> 109 This program and the accompanying materials are licensed and made available under 110 the terms and conditions of the BSD License that accompanies this distribution. 111 The full text of the license may be found at 112 http://opensource.org/licenses/bsd-license. 113 114 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 115 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 116 117 * Copyright (c) 1990, 1993 118 * The Regents of the University of California. All rights reserved. 119 * 120 * This code is derived from software contributed to Berkeley by 121 * Chris Torek. 122 * 123 * Redistribution and use in source and binary forms, with or without 124 * modification, are permitted provided that the following conditions 125 * are met: 126 * 1. Redistributions of source code must retain the above copyright 127 * notice, this list of conditions and the following disclaimer. 128 * 2. Redistributions in binary form must reproduce the above copyright 129 * notice, this list of conditions and the following disclaimer in the 130 * documentation and/or other materials provided with the distribution. 131 * 3. Neither the name of the University nor the names of its contributors 132 * may be used to endorse or promote products derived from this software 133 * without specific prior written permission. 134 * 135 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 136 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 137 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 138 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 139 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 140 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 141 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 142 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 143 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 144 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 145 * SUCH DAMAGE. 146 * 147 * @(#)stdio.h 8.5 (Berkeley) 4/29/95 148 NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp 149 */ 150 #ifndef _STDIO_H_ 151 #define _STDIO_H_ 152 153 #include <stdarg.h> 154 #include <limits.h> 155 #include <sys/ansi.h> 156 #include <machine/ansi.h> 157 158 #ifdef _EFI_SIZE_T_ 159 /** size_t is the unsigned integer type of the result of the sizeof operator. **/ 160 typedef _EFI_SIZE_T_ size_t; 161 #undef _EFI_SIZE_T_ 162 #undef _BSD_SIZE_T_ 163 #endif 164 165 /** @{ 166 An object type capable of holding all information necessary to specify any 167 position within a file. 168 169 Each wide-oriented stream has an associated mbstate_t object that stores the 170 current parse state of the stream. A successful call to fgetpos stores a 171 representation of the value of this mbstate_t object as part of the value 172 of the fpos_t object. A later successful call to fsetpos using the same 173 stored fpos_t value restores the value of the associated mbstate_t object 174 as well as the position within the controlled stream. 175 176 This is fairly grotesque, but pure ANSI code must not inspect the 177 innards of an fpos_t anyway. The library internally uses off_t, 178 which we assume is exactly as big as eight chars. 179 **/ 180 #if (!defined(_ANSI_SOURCE) && !defined(__STRICT_ANSI__)) || defined(_LIBC) 181 typedef __off_t fpos_t; 182 #else 183 typedef struct __sfpos { 184 __off_t _pos; 185 } fpos_t; 186 #endif 187 /*@}*/ 188 189 /* stdio buffers */ 190 struct __sbuf { 191 unsigned char *_base; 192 int _size; 193 }; 194 195 /** Structure which holds all the information needed to control a stream or file. 196 * 197 * The following always hold:<BR> 198 * 199 * - if (_flags&(__SLBF|__SWR)) == (__SLBF|__SWR), 200 * - _lbfsize is -_bf._size, else _lbfsize is 0 201 * - if _flags&__SRD, _w is 0 202 * - if _flags&__SWR, _r is 0 203 * 204 * This ensures that the getc and putc macros (or inline functions) never 205 * try to write or read from a file that is in `read' or `write' mode. 206 * (Moreover, they can, and do, automatically switch from read mode to 207 * write mode, and back, on "r+" and "w+" files.) 208 * 209 * _lbfsize is used only to make the inline line-buffered output stream 210 * code as compact as possible. 211 * 212 * _ub, _up, and _ur are used when ungetc() pushes back more characters 213 * than fit in the current _bf, or when ungetc() pushes back a character 214 * that does not match the previous one in _bf. When this happens, 215 * _ub._base becomes non-nil (i.e., a stream has ungetc() data iff 216 * _ub._base!=NULL) and _up and _ur save the current values of _p and _r. 217 * 218 */ 219 typedef struct __sFILE { 220 unsigned char *_p; /**< current position in (some) buffer */ 221 int _r; /**< read space left for getc() */ 222 int _w; /**< write space left for putc() */ 223 unsigned short _flags; /**< flags, below; this FILE is free if 0 */ 224 short _file; /**< fileno, if Unix descriptor, else -1 */ 225 struct __sbuf _bf; /**< the buffer (at least 1 byte, if !NULL) */ 226 int _lbfsize; /**< 0 or -_bf._size, for inline putc */ 227 228 /* operations */ 229 void *_cookie; /**< cookie passed to io functions */ 230 int (*_close)(void *); 231 int (*_read) (void *, char *, int); 232 fpos_t (*_seek) (void *, fpos_t, int); 233 int (*_write)(void *, const char *, int); 234 235 /** file extension */ 236 struct __sbuf _ext; 237 238 /** @{ 239 Separate buffer for long sequences of ungetc(). 240 **/ 241 unsigned char *_up; /**< saved _p when _p is doing ungetc data */ 242 int _ur; /**< saved _r when _r is counting ungetc data */ 243 /*@}*/ 244 245 /* tricks to meet minimum requirements even when malloc() fails */ 246 unsigned char _ubuf[3 * MB_LEN_MAX]; /**< guarantee an ungetc() buffer */ 247 unsigned char _nbuf[1 * MB_LEN_MAX]; /**< guarantee a getc() buffer */ 248 249 /** separate buffer for fgetln() when line crosses buffer boundary */ 250 struct __sbuf _lb; /* buffer for fgetln() */ 251 252 /* Unix stdio files get aligned to block boundaries on fseek() */ 253 int _blksize; /**< stat.st_blksize (may be != _bf._size) */ 254 fpos_t _offset; /**< current lseek offset */ 255 } FILE; 256 257 __BEGIN_DECLS 258 extern FILE __sF[]; 259 __END_DECLS 260 261 #define __SLBF 0x0001 /**< line buffered */ 262 #define __SNBF 0x0002 /**< unbuffered */ 263 #define __SRD 0x0004 /**< OK to read */ 264 #define __SWR 0x0008 /**< OK to write */ 265 /* RD and WR are never simultaneously asserted */ 266 #define __SRW 0x0010 /**< open for reading & writing */ 267 #define __SEOF 0x0020 /**< found EOF */ 268 #define __SERR 0x0040 /**< found error */ 269 #define __SMBF 0x0080 /**< _buf is from malloc */ 270 #define __SAPP 0x0100 /**< fdopen()ed in append mode */ 271 #define __SSTR 0x0200 /**< this is an sprintf/snprintf string */ 272 #define __SOPT 0x0400 /**< do fseek() optimization */ 273 #define __SNPT 0x0800 /**< do not do fseek() optimization */ 274 #define __SOFF 0x1000 /**< set iff _offset is in fact correct */ 275 #define __SMOD 0x2000 /**< true => fgetln modified _p text */ 276 #define __SALC 0x4000 /**< allocate string space dynamically */ 277 278 /* The following three definitions are for ANSI C, which took them 279 from System V, which brilliantly took internal interface macros and 280 made them official arguments to setvbuf(), without renaming them. 281 Hence, these ugly _IOxxx names are *supposed* to appear in user code. 282 283 Although numbered as their counterparts above, the implementation 284 does not rely on this. 285 */ 286 #define _IOFBF 0 /**< setvbuf should set fully buffered */ 287 #define _IOLBF 1 /**< setvbuf should set line buffered */ 288 #define _IONBF 2 /**< setvbuf should set unbuffered */ 289 290 #define BUFSIZ 1024 /**< size of buffer used by setbuf */ 291 #define EOF (-1) /**< A constant integer expression indicating end-of-file. */ 292 293 /** FOPEN_MAX is a minimum maximum, and is the number of streams that 294 stdio can provide without attempting to allocate further resources 295 (which could fail). Do not use this for anything. 296 */ 297 #define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */ 298 299 /** Size needed for an array of char large enough to hold the longest file name string. */ 300 #define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */ 301 302 /** Size needed for an array of char large enough to hold the file name string 303 generated by the tmpname() function. 304 **/ 305 #define L_tmpnam PATH_MAX /* must be == PATH_MAX */ 306 307 #ifndef TMP_MAX 308 #define TMP_MAX 308915776 /**< The maximum number of unique file names 309 that can be generated by tmpnam(). **/ 310 #endif 311 312 /* Always ensure that these are consistent with <fcntl.h>! */ 313 #ifndef SEEK_SET 314 #define SEEK_SET 0 /**< set file offset to offset */ 315 #endif 316 #ifndef SEEK_CUR 317 #define SEEK_CUR 1 /**< set file offset to current plus offset */ 318 #endif 319 #ifndef SEEK_END 320 #define SEEK_END 2 /**< set file offset to EOF plus offset */ 321 #endif 322 323 #define stdin (&__sF[0]) /**< FILE reference for the STanDard INput stream. */ 324 #define stdout (&__sF[1]) /**< FILE reference for the STanDard OUTput stream. */ 325 #define stderr (&__sF[2]) /**< FILE reference for the STanDard ERRor stream. */ 326 327 __BEGIN_DECLS 328 /* Functions defined in C95 standard. ###################################### */ 329 330 /* ################ Operations on files. */ 331 332 /** Remove (delete) a file. 333 334 @param[in] FileName The path to the file to be removed. 335 336 @retval Zero The operation succeeded. 337 @retval Non-zero The operation failed. 338 **/ 339 int remove (const char *FileName); 340 341 /** Rename the file named OldName to NewName. 342 343 @param[in] OldName The name of the existing file to be renamed. 344 @param[in] NewName The new name of the file. 345 346 @retval Zero The operation succeeded. 347 @retval Non-zero The operation failed. OldName still exists and has been unmodified. 348 If OldName does not exist, or a file named NewName already exists, 349 rename() will fail are return a non-zero value. 350 **/ 351 int rename (const char *OldName, const char *NewName); 352 353 /** Create a guaranteed unique temporary file. 354 A binary file is created in the _PATH_TMP directory that is guaranteed to 355 have a unique name. The file will be open for update with mode "wb+" and 356 its FILE pointer returned upon successfull completion. When the file is 357 closed, or when the creating program terminates, the file will be removed. 358 359 @retval NULL The temporary file could not be created. 360 @retval non-NULL The returned value is a pointer to the FILE object 361 associated with the newly created and open temporary file. 362 **/ 363 FILE *tmpfile (void); 364 365 /** Generate a string that is a valid file name, in the _PATH_TMP directory, that 366 is not the same as the name of an existing file. The function can potentially 367 generate up to TMP_MAX different strings. 368 369 @param[out] Buffer A pointer to an array of at least L_tmpnam char elements. 370 or NULL. If non-NULL, the tmpnam function writes its 371 result into that array and returns the argument 372 as its value. 373 374 @return If no suitable string can be generated a NULL pointer is returned. 375 Otherwise, if Buffer is NULL, the result is produced in an internal 376 static object and a pointer to that object is returned. If Buffer 377 is non-null, the results are written into the array pointed to by 378 Buffer and Buffer is returned. 379 **/ 380 char *tmpnam (char *Buffer); 381 382 /* ################ File access functions. */ 383 384 /** Close the open stream, specified by fp, and de-associate it from any file or device. 385 386 @param[in] fp Pointer to a stream object, of type FILE, associated with a 387 file or device. 388 389 @retval Zero The stream was successfully closed. 390 @retval Non-zero There was an error closing the stream. 391 **/ 392 int fclose (FILE *fp); 393 394 /** Empties any buffers associated with the stream specified by fp. 395 396 @param[in] fp Pointer to a stream object, of type FILE, associated with a 397 file or device. 398 399 @retval Zero The stream's buffers were successfully emptied. 400 @retval EOF There was an error writing to the stream. 401 **/ 402 int fflush (FILE *fp); 403 404 /** Associates a file, named by Path, with a stream and prepares it for subsequent 405 operations. 406 407 The parameter Mode points to a string specifying behavior characteristics for 408 the opened file. The recognized Mode strings are: 409 - r Open text file for reading. 410 - w Truncate file to zero length or create text file for writing. 411 - a Open or create a text file for writing at end-of-file (append). 412 - rb Open binary file for reading. 413 - wb Truncate file to zero length or create binary file for writing. 414 - ab Open or create a binary file for writing at end-of-file (append). 415 - r+ Open text file for update (reading and writing). 416 - w+ Truncate file to zero length or create text file for update. 417 - a+ Open or create a text file for update, writing at end-of-file. 418 - r+b or rb+ Open binary file for update (reading and writing). 419 - w+b or wb+ Truncate file to zero length or create binary file for update. 420 - a+b or ab+ Open or create a binary file for update, writing at end-of-file. 421 422 Opening a file with read mode fails if the file does not exist. 423 424 Opening a file with append mode causes all writes to the file to be forced to 425 the current end-of-file, regardless of any intervening calls to fseek. 426 427 @param[in] Path The path or name of the file or device to open. 428 @param[in] Mode The mode in which the file is to be opened. 429 430 @return A pointer to a FILE object associated with the opened file is returned 431 if the file was opened successfully. Otherwise, NULL is returned. 432 **/ 433 FILE *fopen (const char * __restrict Path, const char * __restrict Mode); 434 435 /** Closes the file associated with Ofp then opens the file specified by Path and associates it with 436 stream Ofp. 437 438 Any errors that occur when closing Ofp are ignored. The file specified by Path is opened with mode Mode 439 and associated with stream Ofp instead of producing a new stream object. 440 441 If Path is NULL, the mode of the file associated with Ofp is changed to Mode. 442 443 @param[in] Path The path or name of the file or device to open. 444 @param[in] Mode The mode in which the file is to be opened. 445 @param[in] Ofp Pointer to the FILE object to be closed and associated with the new file. 446 447 @return If Path was not able to be opened, or the mode changed, NULL is returned; 448 otherwise Ofp is returned. 449 **/ 450 FILE *freopen (const char * __restrict Path, const char * __restrict Mode, FILE * __restrict Ofp); 451 452 /** Establishes Fully Buffered or Non-buffered mode for a stream, fp, using Buff as the buffer. 453 454 The file associated with fp must have been successfully opened with no operations, other than 455 possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf. 456 457 If Buff is non-NULL, the stream associated with fp is set to Fully Buffered mode using the 458 array pointed to by Buff as the buffer. The buffer is assumed to be BUFSIZ char long. 459 This is equivalent to calling setvbuf(fp, Buff, _IOFBF, BUFSIZ); 460 461 If Buff is NULL, stream fp is set to Non-buffered mode. 462 This is equivalent to calling setvbuf(fp, NULL, _IONBF, 0); 463 464 @param[in] fp Pointer to the FILE object which will have its buffer set. 465 @param[in] Buff The buffer to use for fp, or NULL. 466 **/ 467 void setbuf (FILE * __restrict fp, char * __restrict Buff); 468 469 /** Establishes a buffering mode and buffer for use by operations performed on the file associated with fp. 470 471 The file associated with fp must have been successfully opened with no operations, other than 472 possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf. 473 474 Parameter BufMode determines how stream fp will be buffered: 475 - _IOFBF causes I/O to be fully buffered. 476 - _IOLBF causes I/O to be line buffered. 477 - _IONBF causes I/O to be unbuffered. 478 479 If Buff is not NULL, it points to an array to be used as an I/O buffer for stream fp. The 480 buffer is set to BufSize char in length. Otherwise, an array of BufSize char is allocated 481 by the setvbuf function if BufMode is not _IONBF. 482 483 It is an error for BufSize to be zero unless BufMode is _IONBF, in which case BufSize is ignored. 484 485 @param[in] fp Pointer to the FILE object which will have its buffer set. 486 @param[in] Buff The buffer to use for fp, or NULL. 487 @param[in] BufMode The buffering mode to use. 488 @param[in] BufSize The size of the buffer to use, specified in char. 489 490 @retval Zero The buffer and mode were established successfully. 491 @retval Non-zero The request can not be honored, or an invalid value for BufMode was given. 492 **/ 493 int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, size_t BufSize); 494 495 /* ################ Formatted Input/Output Functions. */ 496 497 /** The fprintf function writes output to the stream pointed to by stream, 498 under control of the string pointed to by format that specifies how 499 subsequent arguments are converted for output. If there are insufficient 500 arguments for the format, the behavior is indeterminate. If the format is 501 exhausted while arguments remain, the excess arguments are evaluated 502 (as always) but are otherwise ignored. The fprintf function returns when 503 the end of the format string is encountered. 504 505 The format is interpreted as a multibyte character sequence, beginning and ending 506 in its initial shift state. The format is composed of zero or more directives: 507 ordinary multibyte characters (not %), which are copied unchanged to the 508 output stream; and conversion specifications, each of which results in 509 fetching zero or more subsequent arguments, converting them, if applicable, 510 according to the corresponding conversion specifier, and then writing the 511 result to the output stream. 512 513 Each conversion specification is introduced by the character %. After 514 the %, the following appear in sequence: 515 - Zero or more flags (in any order) that modify the meaning of the 516 conversion specification. 517 - An optional minimum field width. If the converted value has fewer 518 characters than the field width, it is padded with spaces (by default) 519 on the left (or right, if the left adjustment flag, described later, 520 has been given) to the field width. The field width takes the form of 521 an asterisk * (described later) or a nonnegative decimal integer. 522 - An optional precision that gives the minimum number of digits to appear 523 for the d, i, o, u, x, and X conversions, the number of digits to 524 appear after the decimal-point character for e, E, f, and F 525 conversions, the maximum number of significant digits for the g and G 526 conversions, or the maximum number of bytes to be written for s 527 conversions. The precision takes the form of a period (.) followed 528 either by an asterisk * (described later) or by an optional decimal 529 integer; if only the period is specified, the precision is taken as 530 zero. If a precision appears with any other conversion specifier, it 531 is ignored. 532 - An optional length modifier that specifies the size of the argument. 533 - A conversion specifier character that specifies the type of conversion 534 to be applied. 535 536 As noted above, a field width, or precision, or both, may be indicated by 537 an asterisk. In this case, an int argument supplies the field width or 538 precision. The arguments specifying field width, or precision, or both, shall 539 appear (in that order) before the argument (if any) to be converted. A negative 540 field width argument is taken as a - flag followed by a positive field width. 541 A negative precision argument is interpreted as if the precision were omitted. 542 543 The flag characters and their meanings are: 544 - The result of the conversion is left-justified within the field. 545 (It is right-justified if this flag is not specified.) 546 + The result of a signed conversion always begins with a plus or 547 minus sign. (It begins with a sign only when a negative value is 548 converted if this flag is not specified.) 549 space If the first character of a signed conversion is not a sign, or 550 if a signed conversion results in no characters, a space is 551 prefixed to the result. If the space and + flags both appear, the 552 space flag is ignored. 553 # The result is converted to an "alternative form". 554 - For o conversion, it increases the precision, if and only if necessary, 555 to force the first digit of the result to be a zero (if the value 556 and precision are both 0, a single 0 is printed). 557 - For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it. 558 - For e, E, f, F, g, and G conversions, the result of converting a 559 floating-point number always contains a decimal-point character, 560 even if no digits follow it. (Normally, a decimal-point character 561 appears in the result of these conversions only if a digit follows 562 it.) 563 - For g and G conversions, trailing zeros are not removed from 564 the result. For other conversions, it is ignored. 565 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading 566 zeros (following any indication of sign or base) are used to pad to 567 the field width rather than performing space padding, except when 568 converting an infinity or NaN. If the 0 and - flags both appear, 569 the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a 570 precision is specified, the 0 flag is ignored. 571 572 The length modifiers and their meanings are: 573 hh Specifies that a following d, i, o, u, x, or X conversion specifier 574 applies to a signed char or unsigned char argument (the argument 575 will have been promoted according to the integer promotions, but 576 its value shall be converted to signed char or unsigned char before 577 printing); or that a following n conversion specifier applies to a 578 pointer to a signed char argument. 579 h Specifies that a following d, i, o, u, x, or X conversion specifier 580 applies to a short int or unsigned short int argument (the argument 581 will have been promoted according to the integer promotions, but 582 its value shall be converted to short int or unsigned short int 583 before printing); or that a following n conversion specifier 584 applies to a pointer to a short int argument. 585 l (ell) Specifies that a following d, i, o, u, x, or X conversion 586 specifier applies to a long int or unsigned long int argument; that 587 a following n conversion specifier applies to a pointer to a long 588 int argument; that a following c conversion specifier applies to a 589 wint_t argument; that a following s conversion specifier applies to 590 a pointer to a wchar_t argument; or has no effect on a following e, 591 E, f, F, g, or G conversion specifier. 592 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion 593 specifier applies to a long long int or unsigned long long int 594 argument; or that a following n conversion specifier applies to a 595 pointer to a long long int argument. 596 j Specifies that a following d, i, o, u, x, or X conversion specifier 597 applies to an intmax_t or uintmax_t argument; or that a following n 598 conversion specifier applies to a pointer to an intmax_t argument. 599 z Specifies that a following d, i, o, u, x, or X conversion specifier 600 applies to a size_t or the corresponding signed integer type 601 argument; or that a following n conversion specifier applies to a 602 pointer to a signed integer type corresponding to size_t argument. 603 t Specifies that a following d, i, o, u, x, or X conversion specifier 604 applies to a ptrdiff_t or the corresponding unsigned integer type 605 argument; or that a following n conversion specifier applies to a 606 pointer to a ptrdiff_t argument. 607 L Specifies that a following e, E, f, F, g, or G conversion specifier 608 applies to a long double argument. 609 610 If a length modifier appears with any conversion specifier other than as 611 specified above, it is ignored. 612 613 The conversion specifiers and their meanings are: 614 d,i The int argument is converted to signed decimal in the style 615 [-]dddd. The precision specifies the minimum number of digits to 616 appear; if the value being converted can be represented in fewer 617 digits, it is expanded with leading zeros. The default precision 618 is 1. The result of converting a zero value with a precision of 619 zero is no characters. 620 o,u,x,X The unsigned int argument is converted to unsigned octal (o), 621 unsigned decimal (u), or unsigned hexadecimal notation (x or X) in 622 the style dddd; the letters abcdef are used for x conversion and 623 the letters ABCDEF for X conversion. The precision specifies the 624 minimum number of digits to appear; if the value being converted 625 can be represented in fewer digits, it is expanded with leading 626 zeros. The default precision is 1. The result of converting a zero 627 value with a precision of zero is no characters. 628 f,F A double argument representing a floating-point number is 629 converted to decimal notation in the style [-]ddd.ddd, where the 630 number of digits after the decimal-point character is equal to the 631 precision specification. If the precision is missing, it is taken 632 as 6; if the precision is zero and the # flag is not specified, no 633 decimal-point character appears. If a decimal-point character 634 appears, at least one digit appears before it. The value is rounded 635 to the appropriate number of digits. 636 A double argument representing an infinity is converted in 637 the style [-]inf. A double argument representing a NaN is 638 converted in the style [-]nan. The F conversion specifier produces INF, 639 INFINITY, or NAN instead of inf, infinity, or nan, respectively. 640 e,E A double argument representing a floating-point number is 641 converted in the style [-]d.ddd e[+-]dd, where there is one digit 642 (which is nonzero if the argument is nonzero) before the 643 decimal-point character and the number of digits after it is equal 644 to the precision; if the precision is missing, it is taken as 6; if 645 the precision is zero and the # flag is not specified, no 646 decimal-point character appears. The value is rounded to the 647 appropriate number of digits. The E conversion specifier produces a 648 number with E instead of e introducing the exponent. The exponent 649 always contains at least two digits, and only as many more digits 650 as necessary to represent the exponent. If the value is zero, the 651 exponent is zero. 652 A double argument representing an infinity or NaN is converted 653 in the style of an f or F conversion specifier. 654 g,G A double argument representing a floating-point number is 655 converted in style f or e (or in style F or E in the case of a G 656 conversion specifier), depending on the value converted and the 657 precision. Let P equal the precision if nonzero, 6 if the precision 658 is omitted, or 1 if the precision is zero. Then, if a conversion 659 with style E would have an exponent of X: 660 - if P > X = -4, the conversion is with style f (or F) and 661 precision P - (X + 1). 662 - otherwise, the conversion is with style e (or E) and 663 precision P - 1. 664 665 Finally, unless the # flag is used, any trailing zeros are removed 666 from the fractional portion of the result and the decimal-point 667 character is removed if there is no fractional portion remaining. 668 A double argument representing an infinity or NaN is converted in 669 the style of an f or F conversion specifier. 670 c If no l length modifier is present, the int argument is 671 converted to an unsigned char, and the resulting character is 672 written. If an l length modifier is present, the wint_t argument is 673 converted as if by an ls conversion specification with no precision 674 and an argument that points to the initial element of a two-element 675 array of wchar_t, the first element containing the wint_t argument 676 to the lc conversion specification and the second a null wide 677 character. 678 s If no l length modifier is present, the argument is a pointer 679 to the initial element of an array of character type. Characters 680 from the array are written up to (but not including) the 681 terminating null character. If the precision is specified, no more 682 than that many bytes are written. If the precision is not specified 683 or is greater than the size of the array, the array shall contain a 684 null character. 685 If an l length modifier is present, the argument shall be a 686 pointer to the initial element of an array of wchar_t type. Wide 687 characters from the array are converted to multibyte characters 688 (each as if by a call to the wcrtomb function, with the conversion 689 state described by an mbstate_t object initialized to zero before 690 the first wide character is converted) up to and including a 691 terminating null wide character. The resulting multibyte characters 692 are written up to (but not including) the terminating null 693 character (byte). If no precision is specified, the array shall 694 contain a null wide character. If a precision is specified, no more 695 than that many bytes are written (including shift sequences, if 696 any), and the array shall contain a null wide character if, to 697 equal the multibyte character sequence length given by the 698 precision, the function would need to access a wide character one 699 past the end of the array. In no case is a partial multibyte 700 character written. 701 p The argument shall be a pointer to void. The value of the 702 pointer is converted to a sequence of printing characters. 703 n The argument shall be a pointer to signed integer into which is 704 written the number of characters written to the output stream so 705 far by this call to fprintf. No argument is converted, but one is 706 consumed. If the conversion specification includes any flags, a 707 field width, or a precision, they will be ignored. 708 % A % character is written. No argument is converted. The 709 complete conversion specification shall be %%. 710 711 In no case does a nonexistent or small field width cause truncation of a 712 field; if the result of a conversion is wider than the field width, the 713 field is expanded to contain the conversion result. 714 715 @param[in] stream An open File specifier to which the output is sent. 716 @param[in] format A multi-byte character sequence containing characters 717 to be copied unchanged, and conversion specifiers 718 which convert their associated arguments. 719 @param ... Variable number of parameters as required by format. 720 721 @return The fprintf function returns the number of characters 722 transmitted, or a negative value if an output or encoding 723 error occurred. 724 **/ 725 int fprintf (FILE * __restrict stream, const char * __restrict format, ...); 726 727 /** Reads characters from stream, under control of format, storing the converted values 728 in variables pointed to by the variable-length parameter list. 729 730 The format is interpreted as a multibyte character sequence, beginning and ending 731 in its initial shift state. The format is composed of zero or more directives: 732 one or more white-space characters, an ordinary multibyte character 733 (neither % nor a white-space character), or a conversion specification. 734 735 Each conversion specification is introduced by the character %. After 736 the %, the following appear in sequence: 737 - An optional assignment-suppressing character, *. 738 - An optional decimal integer, greater than zero, that specifies the 739 maximum field width (in characters). 740 - An optional length modifier that specifies the size of the receiving object. 741 - A conversion specifier character that specifies the type of conversion 742 to be applied. 743 744 The fscanf function executes each directive of the format in turn. If a directive fails, as 745 detailed below, the function returns. Failures are described as input failures (due to the 746 occurrence of an encoding error or the unavailability of input characters), or matching 747 failures (due to inappropriate input). 748 749 A directive composed of white-space character(s) is executed by reading input up to the 750 first non-white-space character (which remains unread), or until no more characters can 751 be read. 752 753 A directive that is an ordinary multibyte character is executed by reading the next 754 characters of the stream. If any of those characters differ from the ones composing the 755 directive, the directive fails and the differing and subsequent characters remain unread. 756 Similarly, if end-of-file, an encoding error, or a read error prevents a character from being 757 read, the directive fails. 758 759 The length modifiers and their meanings are: 760 - hh Specifies that a following d, i, o, u, x, X, or n conversion 761 specifier applies to an argument with type pointer to signed 762 char or unsigned char. 763 - h Specifies that a following d, i, o, u, x, X, or n conversion 764 specifier applies to an argument with type pointer to short 765 int or unsigned short int. 766 - l (ell) Specifies that a following d, i, o, u, x, X, or n conversion 767 specifier applies to an argument with type pointer to 768 long int or unsigned long int; that a following a, A, e, 769 E, f, F, g, or G conversion specifier applies to an 770 argument with type pointer to double; or that a following 771 c, s, or [ conversion specifier applies to an argument 772 with type pointer to wchar_t. 773 - ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion 774 specifier applies to an argument with type pointer to 775 long long int or unsigned long long int. 776 - j Specifies that a following d, i, o, u, x, X, or n conversion 777 specifier applies to an argument with type pointer to 778 intmax_t or uintmax_t. 779 - z Specifies that a following d, i, o, u, x, X, or n conversion 780 specifier applies to an argument with type pointer to 781 size_t or the corresponding signed integer type. 782 - t Specifies that a following d, i, o, u, x, X, or n conversion 783 specifier applies to an argument with type pointer to 784 ptrdiff_t or the corresponding unsigned integer type. 785 - L Specifies that a following e, E, f, F, g, or G 786 conversion specifier applies to an argument with type 787 pointer to long double. 788 789 If a length modifier appears with any conversion specifier other than as specified above, 790 it will be ignored. 791 792 The conversion specifiers and their meanings are: 793 - d Matches an optionally signed decimal integer, whose format is 794 the same as expected for the subject sequence of the strtol 795 function with the value 10 for the base argument. The 796 corresponding argument shall be a pointer to signed integer. 797 - i Matches an optionally signed integer, whose format is the same 798 as expected for the subject sequence of the strtol function 799 with the value 0 for the base argument. The corresponding 800 argument shall be a pointer to signed integer. 801 - o Matches an optionally signed octal integer, whose format is the 802 same as expected for the subject sequence of the strtoul 803 function with the value 8 for the base argument. The 804 corresponding argument shall be a pointer to unsigned integer. 805 - u Matches an optionally signed decimal integer, whose format is 806 the same as expected for the subject sequence of the strtoul 807 function with the value 10 for the base argument. The 808 corresponding argument shall be a pointer to unsigned integer. 809 - x Matches an optionally signed hexadecimal integer, whose format 810 is the same as expected for the subject sequence of the strtoul 811 function with the value 16 for the base argument. The 812 corresponding argument shall be a pointer to unsigned integer. 813 - e,f,g Matches an optionally signed floating-point number, infinity, 814 or NaN, whose format is the same as expected for the subject 815 sequence of the strtod function. The corresponding argument 816 shall be a pointer to floating. 817 - c Matches a sequence of characters of exactly the number 818 specified by the field width (1 if no field width is present 819 in the directive). If no l length modifier is present, the 820 corresponding argument shall be a pointer to the initial 821 element of a character array large enough to accept the 822 sequence. No null character is added.<BR><BR> 823 If an l length modifier is present, the input shall be a 824 sequence of multibyte characters that begins in the initial 825 shift state. Each multibyte character in the sequence is 826 converted to a wide character as if by a call to the mbrtowc 827 function, with the conversion state described by an mbstate_t 828 object initialized to zero before the first multibyte character 829 is converted. The corresponding argument shall be a pointer to 830 the initial element of an array of wchar_t large enough to 831 accept the resulting sequence of wide characters. No null wide 832 character is added. 833 - s Matches a sequence of non-white-space characters. 834 If no l length modifier is present, the corresponding argument 835 shall be a pointer to the initial element of a character array 836 large enough to accept the sequence and a terminating null 837 character, which will be added automatically. If an l length 838 modifier is present, the input shall be a sequence of multibyte 839 characters that begins in the initial shift state. Each 840 multibyte character is converted to a wide character as if by a 841 call to the mbrtowc function, with the conversion state 842 described by an mbstate_t object initialized to zero before the 843 first multibyte character is converted. The corresponding 844 argument shall be a pointer to the initial element of an array 845 of wchar_t large enough to accept the sequence and the 846 terminating null wide character, which will be added automatically. 847 - [ Matches a nonempty sequence of characters from a set of 848 expected characters (the scanset).<BR><BR> 849 If no l length modifier is present, the corresponding argument 850 shall be a pointer to the initial element of a character array 851 large enough to accept the sequence and a terminating null 852 character, which will be added automatically. If an l length 853 modifier is present, the input shall be a sequence of multibyte 854 characters that begins in the initial shift state. Each 855 multibyte character is converted to a wide character as if by a 856 call to the mbrtowc function, with the conversion state 857 described by an mbstate_t object initialized to zero before the 858 first multibyte character is converted. The corresponding 859 argument shall be a pointer to the initial element of an array 860 of wchar_t large enough to accept the sequence and the 861 terminating null wide character, which will be added 862 automatically.<BR><BR> 863 The conversion specifier includes all subsequent characters in 864 the format string, up to and including the matching right 865 bracket (]). The characters between the brackets (the scanlist) 866 compose the scanset, unless the character after the left 867 bracket is a circumflex (^), in which case the scanset contains 868 all characters that do not appear in the scanlist between the 869 circumflex and the right bracket. If the conversion specifier 870 begins with [] or [^], the right bracket character is in the 871 scanlist and the next following right bracket character is the 872 matching right bracket that ends the specification; otherwise 873 the first following right bracket character is the one that 874 ends the specification. If a - character is in the scanlist and 875 is not the first, nor the second where the first character is 876 a ^, nor the last character, it will be treated as a regular character. 877 - p Matches a set of sequences, which are the same as the set of 878 sequences that are produced by the %p conversion of the fprintf 879 function. The corresponding argument must be a pointer to a 880 pointer to void. The input item is converted to a pointer value. 881 If the input item is a value converted earlier during the same 882 program execution, the pointer that results will compare equal 883 to that value; otherwise the behavior of the %p conversion is 884 indeterminate. 885 - n No input is consumed. The corresponding argument shall be a 886 pointer to signed integer into which is to be written the 887 number of characters read from the input stream so far by this 888 call to the fscanf function. Execution of a %n directive does 889 not increment the assignment count returned at the completion 890 of execution of the fscanf function. No argument is converted, 891 but one is consumed. If the conversion specification includes 892 an assignment suppressing character the conversion specification 893 is ignored. If the conversion specification contains a 894 field width, the field width will be ignored. 895 - % Matches a single % character; no conversion or assignment occurs. 896 897 @param[in] stream An open File specifier from which the input is read. 898 @param[in] format A multi-byte character sequence containing characters 899 to be matched against, and conversion specifiers 900 which convert their associated arguments. Converted 901 items are stored according to their associated arguments. 902 @param ... Variable number of parameters, as required by format, 903 specifying the objects to receive the converted input. 904 905 @return The fscanf function returns EOF if an input failure occurs before 906 any conversion. Otherwise the number of input items assigned 907 is returned; which can be fewer than provided for, or even zero 908 in the event of an early matching failure. 909 **/ 910 int fscanf (FILE * __restrict stream, const char * __restrict format, ...); 911 912 /** Formatted print to stdout. 913 914 The printf function is equivalent to fprintf with stdout used as the output stream. 915 916 @param[in] format A multi-byte character sequence containing characters 917 to be copied unchanged, and conversion specifiers 918 which convert their associated arguments. Copied and 919 converted characters are sent to the output stream. 920 @param ... Variable number of parameters as required by format. 921 922 @return The printf function returns the number of characters 923 transmitted, or a negative value if an output or encoding 924 error occurred. 925 **/ 926 int printf (const char * __restrict format, ...); 927 928 /** Formatted input from stdin. 929 930 The scanf function is equivalent to fscanf with stdin used as the input stream. 931 932 @param[in] format A multi-byte character sequence containing characters 933 to be matched against, and conversion specifiers 934 which convert their associated arguments. Converted 935 items are stored according to their associated arguments. 936 @param[out] ... Variable number of parameters, as required by format, 937 specifying the objects to receive the converted input. 938 939 @return The scanf function returns EOF if an input failure occurs before 940 any conversion. Otherwise the number of input items assigned 941 is returned; which can be fewer than provided for, or even zero 942 in the event of an early matching failure. 943 **/ 944 int scanf (const char * __restrict format, ...); 945 946 /** Formatted output to a buffer. 947 948 The sprintf function is equivalent to fprintf, except that the output is 949 written into array Buff instead of to a stream. A null character is written 950 at the end of the characters written; it is not counted as part of the 951 returned value. 952 953 @param[out] Buff A pointer to the array to receive the formatted output. 954 @param[in] Format A multi-byte character sequence containing characters 955 to be copied unchanged, and conversion specifiers 956 which convert their associated arguments. Copied and 957 converted characters are written to the array pointed 958 to by Buff. 959 @param ... Variable number of parameters as required by format. 960 961 @return The sprintf function returns the number of characters written in 962 the array, not counting the terminating null character, or a 963 negative value if an encoding error occurred. 964 **/ 965 int sprintf (char * __restrict Buff, const char * __restrict Format, ...); 966 967 /** Formatted input from a string. 968 969 The sscanf function is equivalent to fscanf, except that input is obtained 970 from a string rather than from a stream. Reaching the end of the string 971 is equivalent to encountering end-of-file for the fscanf function. 972 973 @param[in] Buff Pointer to the string from which to obtain input. 974 @param[in] Format A multi-byte character sequence containing characters 975 to be matched against, and conversion specifiers 976 which convert their associated arguments. Converted 977 items are stored according to their associated arguments. 978 @param[out] ... Variable number of parameters, as required by format, 979 specifying the objects to receive the converted input. 980 981 @return The scanf function returns EOF if an input failure occurs before 982 any conversion. Otherwise the number of input items assigned 983 is returned; which can be fewer than provided for, or even zero 984 in the event of an early matching failure. 985 **/ 986 int sscanf (const char * __restrict Buff, const char * __restrict Format, ...); 987 988 /** Print formatted values from an argument list. 989 990 The vfprintf function is equivalent to fprintf, with the variable argument 991 list replaced by Args, which must have been initialized by the va_start macro. 992 The vfprintf function does not invoke the va_end macro. 993 994 @param[in] Stream The output stream to receive the formatted output. 995 @param[in] Format A multi-byte character sequence containing characters 996 to be matched against, and conversion specifiers 997 which convert their associated arguments. Converted 998 items are stored according to their associated arguments. 999 @param[in] Args A list of arguments, initialized by the va_start macro 1000 and accessed using the va_arg macro, used to satisfy 1001 the directives in the Format string. 1002 1003 @return The vfprintf function returns the number of characters transmitted, 1004 or a negative value if an output or encoding error occurred. 1005 **/ 1006 int vfprintf(FILE * __restrict Stream, const char * __restrict Format, va_list Args); 1007 1008 /** Formatted print, to stdout, from an argument list. 1009 1010 The vprintf function is equivalent to printf, with the variable argument 1011 list replaced by Args, which must have been initialized by the va_start 1012 macro (and possibly subsequent va_arg calls). The vprintf function does 1013 not invoke the va_end macro. 1014 1015 @param[in] Format A multi-byte character sequence containing characters 1016 to be matched against, and conversion specifiers 1017 which convert their associated arguments. Converted 1018 items are stored according to their associated arguments. 1019 @param[in] Args A list of arguments, initialized by the va_start macro 1020 and accessed using the va_arg macro, used to satisfy 1021 the directives in the Format string. 1022 1023 @return The vprintf function returns the number of characters transmitted, 1024 or a negative value if an output or encoding error occurred. 1025 **/ 1026 int vprintf (const char * __restrict Format, va_list Args); 1027 1028 /** Formatted print, to a buffer, from an argument list. 1029 1030 The vsprintf function is equivalent to sprintf, with the variable argument 1031 list replaced by Args, which must have been initialized by the va_start 1032 macro. The vsprintf function does not invoke the va_end macro. 1033 1034 @param[out] Buff A pointer to the array to receive the formatted output. 1035 @param[in] Format A multi-byte character sequence containing characters 1036 to be copied unchanged, and conversion specifiers 1037 which convert their associated arguments. Copied and 1038 converted characters are written to the array pointed 1039 to by Buff. 1040 @param[in] Args A list of arguments, initialized by the va_start macro 1041 and accessed using the va_arg macro, used to satisfy 1042 the directives in the Format string. 1043 1044 @return The vsprintf function returns the number of characters written in 1045 the array, not counting the terminating null character, or a 1046 negative value if an encoding error occurred. 1047 **/ 1048 int vsprintf(char * __restrict Buff, const char * __restrict Format, va_list Args); 1049 1050 /* ################ Character Input/Output Functions. */ 1051 1052 /** Get a character from an input Stream. 1053 1054 If the end-of-file indicator for the input stream pointed to by Stream is 1055 not set, and a next character is present, the fgetc function obtains that 1056 character as an unsigned char converted to an int and advances the 1057 associated file position indicator for the stream. 1058 1059 @param[in] Stream An input stream from which to obtain a character. 1060 1061 @return If the end-of-file indicator for the stream is set, or if the 1062 stream is at end-of-file, the end-of-file indicator for the 1063 stream is set and the fgetc function returns EOF. Otherwise, 1064 the fgetc function returns the next character from the input 1065 stream pointed to by Stream. If a read error occurs, the 1066 error indicator for the stream is set and the fgetc function 1067 returns EOF. 1068 **/ 1069 int fgetc (FILE *Stream); 1070 1071 /** Read a string from an input stream into a buffer. 1072 1073 The fgets function reads at most one less than the number of characters 1074 specified by Limit from the stream pointed to by Stream into the array 1075 pointed to by Buff. No additional characters are read after a 1076 new-line character (which is retained) or after end-of-file. A null 1077 character is written immediately after the last character read into the array. 1078 1079 @param[out] Buff A pointer to the array to receive the input string. 1080 @param[in] Limit The maximum number of characters to put into Buff, 1081 including the terminating null character. 1082 @param[in] Stream An input stream from which to obtain a character. 1083 1084 @return The fgets function returns Buff if successful. If end-of-file is 1085 encountered and no characters have been read into the array, the 1086 contents of the array remain unchanged and a null pointer is 1087 returned. If a read error occurs during the operation, the array 1088 contents are indeterminate and a null pointer is returned. 1089 **/ 1090 char *fgets (char * __restrict Buff, int Limit, FILE * __restrict Stream); 1091 1092 /** Write a character to an output stream. 1093 1094 The fputc function writes the character specified by C (converted to an 1095 unsigned char) to the output stream pointed to by Stream, at the position 1096 indicated by the associated file position indicator for the stream 1097 (if defined), and advances the indicator appropriately. If the file cannot 1098 support positioning requests, or if the stream was opened with append mode, 1099 the character is appended to the output stream. 1100 1101 @param[in] C The character to be written to Stream. 1102 @param[in] Stream The output stream that C is to be written to. 1103 1104 @return The fputc function returns the character written. If a write 1105 error occurs, the error indicator for the stream is set and 1106 fputc returns EOF. 1107 **/ 1108 int fputc (int C, FILE *Stream); 1109 1110 /** Write a string to an output stream. 1111 1112 The fputs function writes String to the stream pointed to by Stream. The 1113 terminating null character is not written. 1114 1115 @param[in] String The character string to be written to Stream. 1116 @param[in] Stream The output stream that String is to be written to. 1117 1118 @return The fputs function returns EOF if a write error occurs; otherwise 1119 it returns a non-negative value. 1120 **/ 1121 int fputs (const char * __restrict String, FILE * __restrict Stream); 1122 1123 /** Get a character from an input stream. 1124 1125 The getc function is equivalent to fgetc, except that if it is implemented 1126 as a macro, it may evaluate stream more than once, so the argument should 1127 never be an expression with side effects. 1128 1129 @param[in] Stream An input stream from which to obtain a character. 1130 1131 @return If the end-of-file indicator for the stream is set, or if the 1132 stream is at end-of-file, the end-of-file indicator for the 1133 stream is set and getc returns EOF. Otherwise, getc returns 1134 the next character from the input stream pointed to by Stream. 1135 If a read error occurs, the error indicator for the stream is set 1136 and getc returns EOF. 1137 **/ 1138 int getc (FILE *); 1139 1140 /** Get a character from stdin. 1141 1142 The getchar function is equivalent to getc with the argument stdin. 1143 1144 @return If the end-of-file indicator for stdin is set, or if stdin 1145 is at end-of-file, the end-of-file indicator is set and getchar 1146 returns EOF. Otherwise, getchar returns the next character from 1147 stdin. If a read error occurs, the error indicator for stdin is 1148 set and getchar returns EOF. 1149 **/ 1150 int getchar (void); 1151 1152 /** Read a string from stdin into a buffer. 1153 1154 The gets function reads characters from the input stream pointed to by 1155 stdin, into the array pointed to by Buff, until end-of-file is encountered 1156 or a new-line character is read. Any new-line character is discarded, and 1157 a null character is written immediately after the last character read into 1158 the array. 1159 1160 @param[out] Buff A pointer to the array to receive the input string. 1161 1162 @return The gets function returns Buff if successful. If end-of-file is 1163 encountered and no characters have been read into the array, the 1164 contents of the array remain unchanged and a null pointer is 1165 returned. If a read error occurs during the operation, the array 1166 contents are indeterminate and a null pointer is returned. 1167 **/ 1168 char *gets (char *Buff); 1169 1170 /** Write a character to an output stream. 1171 1172 The putc function is equivalent to fputc, except that if it is implemented 1173 as a macro, it may evaluate Stream more than once, so that argument should 1174 never be an expression with side effects. 1175 1176 @param[in] C The character to be written to Stream. 1177 @param[in] Stream The output stream that C is to be written to. 1178 1179 @return The putc function returns the character written. If a write 1180 error occurs, the error indicator for the stream is set and 1181 putc returns EOF. 1182 **/ 1183 int putc (int C, FILE *Stream); 1184 1185 /** Write a character to stdout. 1186 1187 The putchar function is equivalent to putc with stdout as the Stream argument. 1188 1189 @param[in] C The character to be written to stdout. 1190 1191 @return The putchar function returns the character written. If a write 1192 error occurs, the error indicator for stdout is set and putchar 1193 returns EOF. 1194 **/ 1195 int putchar (int C); 1196 1197 /** Write String to stdout. 1198 1199 The puts function writes the string pointed to by String to the stream 1200 pointed to by stdout, and appends a new-line character to the output. The 1201 terminating null character is not written. 1202 1203 @param[in] String A pointer to the character string to write to stdout. 1204 1205 @return The puts function returns EOF if a write error occurs; otherwise 1206 it returns a non-negative value. 1207 **/ 1208 int puts (const char *String); 1209 1210 /** Return a character to the input Stream as if it had not been read. 1211 1212 The ungetc function pushes the character specified by C (converted to an 1213 unsigned char) back onto the input stream pointed to by Stream. Pushed-back 1214 characters will be returned by subsequent reads on that stream in the 1215 reverse order of their being pushed. A successful intervening call 1216 (with the stream pointed to by Stream) to a file positioning function 1217 (fseek, fsetpos, or rewind) discards any pushed-back characters for the 1218 stream. The external storage corresponding to the stream is unchanged. 1219 1220 One character of pushback is guaranteed. If the ungetc function is called 1221 too many times on the same stream without an intervening read or file 1222 positioning operation on that stream, the operation will fail. 1223 1224 If the value of C equals that of the macro EOF, the operation fails and the 1225 input stream is unchanged. 1226 1227 A successful call to the ungetc function clears the end-of-file indicator 1228 for the stream. The value of the file position indicator for the stream 1229 after reading or discarding all pushed-back characters is the same as it 1230 was before the characters were pushed back. For a binary stream, its 1231 file position indicator is decremented by each successful call to the 1232 ungetc function; if its value was zero before a call, it will remain zero 1233 after the call. 1234 1235 @param[in] C The character to push back onto the Stream. 1236 @param[in] Stream The output stream that C is to be pushed back onto. 1237 1238 @return The ungetc function returns the character pushed back, 1239 or EOF if the operation fails. 1240 **/ 1241 int ungetc (int C, FILE *Stream); 1242 1243 /* ################ Direct Input/Output Functions. */ 1244 1245 /** Read Num elements of size Size from a Stream into a Buffer. 1246 1247 The fread function reads, into the array pointed to by Buffer, up to Num 1248 elements, whose size is specified by Size, from the stream pointed to by 1249 Stream. For each object, Size calls are made to the fgetc function and the 1250 results stored, in the order read, in an array of unsigned char exactly 1251 overlaying the Buffer object. The file position indicator for the stream 1252 (if defined) is advanced by the number of characters successfully read. If 1253 an error occurs, the resulting value of the file position indicator for the 1254 stream is indeterminate. 1255 1256 @param[out] Buffer Pointer to an object to receive the read data. 1257 @param[in] Size Size of each element to be read. 1258 @param[in] Num Number of elements to read. 1259 @param[in] Stream Input stream to read the data from. 1260 1261 @return The fread function returns the number of elements successfully 1262 read, which may be less than Num if a read error or end-of-file 1263 is encountered. If Size or Num is zero, fread returns zero and 1264 the contents of the array and the state of the stream remain 1265 unchanged. 1266 **/ 1267 size_t fread (void * __restrict Buffer, 1268 size_t Size, 1269 size_t Num, 1270 FILE * __restrict Stream 1271 ); 1272 1273 /** Write Num elements of size Size from Buffer to Stream. 1274 1275 The fwrite function writes, from the array pointed to by Buffer, up to Num 1276 elements whose size is specified by Size, to the stream pointed to by 1277 Stream. For each object, Size calls are made to the fputc function, taking 1278 the values (in order) from an array of unsigned char exactly overlaying the 1279 Buffer object. The file position indicator for the stream (if defined) is 1280 advanced by the number of characters successfully written. If an error 1281 occurs, the resulting value of the file position indicator for the stream is 1282 indeterminate. 1283 1284 @param[out] Buffer Pointer to an object containing the data to be written. 1285 @param[in] Size Size of each element to be written. 1286 @param[in] Num Number of elements to write. 1287 @param[in] Stream Output stream to write the data to. 1288 1289 @return The fwrite function returns the number of elements successfully 1290 written, which will be less than Num only if a write error is 1291 encountered. If Size or Num is zero, fwrite returns zero and 1292 the state of the stream remains unchanged. 1293 **/ 1294 size_t fwrite (const void * __restrict Buffer, 1295 size_t Size, 1296 size_t Num, 1297 FILE * __restrict Stream 1298 ); 1299 1300 /* ################ File Positioning Functions. */ 1301 1302 /** Get a stream's position and parse state. 1303 1304 The fgetpos function stores the current values of the parse state (if any) 1305 and file position indicator for the stream pointed to by Stream in the 1306 object pointed to by Pos. The values stored contain unspecified 1307 information usable by the fsetpos function for repositioning the stream 1308 to its position at the time of the call to the fgetpos function. 1309 1310 @param[in] Stream Stream to get current position of. 1311 @param[out] Pos Object to receive the stream's state and position information. 1312 1313 @return If successful, the fgetpos function returns zero; if either 1314 parameter is NULL, the fgetpos function returns nonzero and 1315 stores EINVAL in errno. 1316 **/ 1317 int fgetpos (FILE * __restrict Stream, fpos_t * __restrict Pos); 1318 1319 /** Set the file position for a stream. 1320 1321 The fseek function sets the file position indicator for the stream pointed 1322 to by Stream. If a read or write error occurs, the error indicator for the 1323 stream is set and fseek fails. 1324 1325 For a binary stream, the new position, measured in characters from the 1326 beginning of the file, is obtained by adding Offset to the position 1327 specified by Whence. The specified position is the beginning of the file if 1328 Whence is SEEK_SET, the current value of the file position indicator if 1329 SEEK_CUR, or end-of-file if SEEK_END. 1330 1331 For a text stream, Offset must either be zero or a value returned by an 1332 earlier successful call to the ftell function, on a stream associated with 1333 the same file, and Whence must be SEEK_SET. 1334 1335 After determining the new position, a successful call to the fseek function 1336 undoes any effects of the ungetc function on the stream, clears the 1337 end-of-file indicator for the stream, and then establishes the new position. 1338 After a successful fseek call, the next operation on an update stream may 1339 be either input or output. 1340 1341 @param[in] Stream The I/O stream to set the position of. 1342 @param[in] Offset The position, interpreted depending upon the value of 1343 Whence, that the stream is to be positioned to. 1344 @param[in] Whence A value indicating how Offset is to be interpreted: 1345 - SEEK_SET indicates Offset is an absolute position. 1346 - SEEK_END indicates Offset is relative to the end of the file. 1347 - SEEK_CUR indicates Offset is relative to the current position. 1348 1349 @return The fseek function returns nonzero only for a request that cannot be satisfied. 1350 **/ 1351 int fseek (FILE *Stream, long Offset, int Whence); 1352 1353 /** Set a stream's position and parse state. 1354 1355 The fsetpos function sets the mbstate_t object (if any) and file position 1356 indicator for the stream pointed to by Stream according to the value of the 1357 object pointed to by Pos, which is a value that was obtained from an 1358 earlier successful call to the fgetpos function on a stream associated with 1359 the same file. If a read or write error occurs, the error indicator for the 1360 stream is set and fsetpos fails. 1361 1362 A successful call to the fsetpos function undoes any effects of the ungetc 1363 function on the stream, clears the end-of-file indicator for the stream, 1364 and then establishes the new parse state and position. After a successful 1365 fsetpos call, the next operation on an update stream may be either input or output. 1366 1367 @param[in] Stream Stream to set current position of. 1368 @param[in] Pos Object containing the state and position information. 1369 1370 @return If successful, the fsetpos function returns zero; on failure, the 1371 fsetpos function returns nonzero and stores EINVAL, or ESPIPE, 1372 in errno; depending upon whether the error was because of an invalid 1373 parameter, or because Stream is not seekable. 1374 **/ 1375 int fsetpos (FILE *Stream, const fpos_t *Pos); 1376 1377 /** Get Stream's current position. 1378 1379 The ftell function obtains the current value of the file position indicator 1380 for the stream pointed to by Stream. For a binary stream, the value is the 1381 number of characters from the beginning of the file. For a text stream, its 1382 file position indicator contains unspecified information, usable by the 1383 fseek function for returning the file position indicator for the stream to 1384 its position at the time of the ftell call; the difference between two such 1385 return values is not necessarily a meaningful measure of the number of 1386 characters written or read. 1387 1388 @param[in] Stream Pointer to the FILE object to get the current position of. 1389 1390 @return If successful, the ftell function returns the current value of 1391 the file position indicator for the stream. On failure, the 1392 ftell function returns -1L and stores ESPIPE in errno indicating 1393 that the stream is not seekable. 1394 **/ 1395 long ftell (FILE *Stream); 1396 1397 /** Restore a Stream's file position to the beginning of the file. 1398 1399 The rewind function sets the file position indicator for the stream pointed 1400 to by Stream to the beginning of the file and clears the stream's error indicator. 1401 1402 @param[in] Stream Pointer to the stream to be positioned to its beginning. 1403 **/ 1404 void rewind (FILE *Stream); 1405 1406 /* ################ Error-handling Functions. */ 1407 1408 /** Clear a Stream's error and end-of-file indicators. 1409 1410 @param[in] Stream Pointer to the stream to be cleared of errors. 1411 **/ 1412 void clearerr(FILE *Stream); 1413 1414 /** Test the end-of-file indicator for Stream. 1415 1416 @param[in] Stream Pointer to the FILE object to be tested for EOF. 1417 1418 @return The feof function returns non-zero if, and only if, the end-of-file 1419 indicator is set for Stream. 1420 **/ 1421 int feof (FILE *Stream); 1422 1423 /** Test the error indicator for Stream. 1424 1425 @param[in] Stream Pointer to the stream to be tested for error. 1426 1427 @return The ferror function returns non-zero if, and only if, the error 1428 indicator is set for Stream. 1429 **/ 1430 int ferror (FILE *Stream); 1431 1432 /** Print an error message to stderr based upon the value of errno and String. 1433 1434 The perror function maps the error number in the integer expression errno 1435 to an error message. It writes a sequence of characters to the standard 1436 error stream thus: first (if String is not a null pointer and the character 1437 pointed to by String is not the null character), the string pointed to by 1438 String followed by a colon (:) and a space; then an appropriate error 1439 message string followed by a new-line character. The contents of the error 1440 message strings are the same as those returned by the strerror function 1441 with argument errno. 1442 1443 @param[in] String A text string to prefix the output error message with. 1444 1445 @sa strerror in <string.h> 1446 **/ 1447 void perror (const char *String); 1448 1449 __END_DECLS 1450 1451 /* 1452 * IEEE Std 1003.1-90 1453 */ 1454 __BEGIN_DECLS 1455 FILE *fdopen(int, const char *); 1456 __END_DECLS 1457 1458 /* 1459 * IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2 1460 */ 1461 __BEGIN_DECLS 1462 void flockfile (FILE *); 1463 int ftrylockfile (FILE *); 1464 void funlockfile (FILE *); 1465 int getc_unlocked (FILE *); 1466 int getchar_unlocked(void); 1467 int putc_unlocked (int, FILE *); 1468 int putchar_unlocked(int); 1469 __END_DECLS 1470 1471 /* 1472 * Functions defined in POSIX 1003.2 and XPG2 or later. 1473 */ 1474 __BEGIN_DECLS 1475 int pclose (FILE *); 1476 FILE *popen (const char *, const char *); 1477 __END_DECLS 1478 1479 /* 1480 * Functions defined in ISO XPG4.2, ISO C99, POSIX 1003.1-2001 or later. 1481 */ 1482 __BEGIN_DECLS 1483 int snprintf (char * __restrict, size_t, const char * __restrict, ...) 1484 __attribute__((__format__(__printf__, 3, 4))); 1485 int vsnprintf(char * __restrict, size_t, const char * __restrict, va_list) 1486 __attribute__((__format__(__printf__, 3, 0))); 1487 __END_DECLS 1488 1489 /* 1490 * Functions defined in XPG4.2. 1491 */ 1492 __BEGIN_DECLS 1493 //int getw(FILE *); 1494 //int putw(int, FILE *); 1495 char *mkdtemp(char *); 1496 int mkstemp(char *); 1497 char *mktemp(char *); 1498 1499 char *tempnam(const char *, const char *); 1500 __END_DECLS 1501 1502 /* 1503 * X/Open CAE Specification Issue 5 Version 2 1504 */ 1505 #ifndef off_t 1506 typedef __off_t off_t; 1507 #define off_t __off_t 1508 #endif /* off_t */ 1509 1510 __BEGIN_DECLS 1511 int fseeko(FILE *, off_t, int); 1512 off_t ftello(FILE *); 1513 __END_DECLS 1514 1515 /* 1516 * Routines that are purely local. 1517 */ 1518 #define FPARSELN_UNESCESC 0x01 1519 #define FPARSELN_UNESCCONT 0x02 1520 #define FPARSELN_UNESCCOMM 0x04 1521 #define FPARSELN_UNESCREST 0x08 1522 #define FPARSELN_UNESCALL 0x0f 1523 1524 __BEGIN_DECLS 1525 //int asprintf(char ** __restrict, const char * __restrict, ...) 1526 // __attribute__((__format__(__printf__, 2, 3))); 1527 char *fgetln(FILE * __restrict, size_t * __restrict); 1528 char *fparseln(FILE *, size_t *, size_t *, const char[3], int); 1529 int fpurge(FILE *); 1530 void setbuffer(FILE *, char *, int); 1531 int setlinebuf(FILE *); 1532 int vasprintf(char ** __restrict, const char * __restrict, 1533 va_list) 1534 __attribute__((__format__(__printf__, 2, 0))); 1535 int vscanf(const char * __restrict, va_list) 1536 __attribute__((__format__(__scanf__, 1, 0))); 1537 //int vfscanf(FILE * __restrict, const char * __restrict, 1538 // va_list) 1539 // __attribute__((__format__(__scanf__, 2, 0))); 1540 int vsscanf(const char * __restrict, const char * __restrict, 1541 va_list) 1542 __attribute__((__format__(__scanf__, 2, 0))); 1543 //const char *fmtcheck(const char *, const char *) 1544 // __attribute__((__format_arg__(2))); 1545 __END_DECLS 1546 1547 /* 1548 * Stdio function-access interface. 1549 */ 1550 __BEGIN_DECLS 1551 FILE *funopen(const void *, 1552 int (*)(void *, char *, int), 1553 int (*)(void *, const char *, int), 1554 fpos_t (*)(void *, fpos_t, int), 1555 int (*)(void *)); 1556 __END_DECLS 1557 //#define fropen(cookie, fn) funopen(cookie, fn, 0, 0, 0) 1558 //#define fwopen(cookie, fn) funopen(cookie, 0, fn, 0, 0) 1559 1560 /* 1561 * Functions internal to the implementation. 1562 */ 1563 __BEGIN_DECLS 1564 int __srget(FILE *); 1565 int __swbuf(int, FILE *); 1566 __END_DECLS 1567 1568 /* 1569 * The __sfoo macros are here so that we can 1570 * define function versions in the C library. 1571 */ 1572 #define __sgetc(p) (--(p)->_r < 0 ? __srget(p) : (int)(*(p)->_p++)) 1573 1574 #if defined(__GNUC__) && defined(__STDC__) __sputc(int _c,FILE * _p)1575 static __inline int __sputc(int _c, FILE *_p) { 1576 if (--_p->_w >= 0 || (_p->_w >= _p->_lbfsize && (char)_c != '\n')) 1577 return (*_p->_p++ = _c); 1578 else 1579 return (__swbuf(_c, _p)); 1580 } 1581 #else 1582 /* 1583 * This has been tuned to generate reasonable code on the vax using pcc. 1584 */ 1585 #define __sputc(c, p) \ 1586 (--(p)->_w < 0 ? \ 1587 (p)->_w >= (p)->_lbfsize ? \ 1588 (*(p)->_p = (unsigned char)(c)), *(p)->_p != '\n' ? \ 1589 (int)*(p)->_p++ : \ 1590 __swbuf('\n', p) : \ 1591 __swbuf((int)(c), p) : \ 1592 (*(p)->_p = (unsigned char)(c), (int)*(p)->_p++)) 1593 #endif 1594 1595 #define __sfeof(p) (((p)->_flags & __SEOF) != 0) 1596 #define __sferror(p) (((p)->_flags & __SERR) != 0) 1597 #define __sclearerr(p) ((void)((p)->_flags &= ~(__SERR|__SEOF))) 1598 #define __sfileno(p) ((p)->_file) 1599 1600 #ifndef __lint__ 1601 #define feof(p) __sfeof(p) 1602 #define ferror(p) __sferror(p) 1603 #define clearerr(p) __sclearerr(p) 1604 1605 #define getc(fp) __sgetc(fp) 1606 #define putc(x, fp) __sputc(x, fp) 1607 #endif /* __lint__ */ 1608 1609 #define getchar() getc(stdin) 1610 #define putchar(x) putc(x, stdout) 1611 1612 #define fileno(p) __sfileno(p) 1613 1614 #define getc_unlocked(fp) __sgetc(fp) 1615 #define putc_unlocked(x, fp) __sputc(x, fp) 1616 1617 #define getchar_unlocked() getc_unlocked(stdin) 1618 #define putchar_unlocked(x) putc_unlocked(x, stdout) 1619 1620 #endif /* _STDIO_H_ */ 1621