pd.if.org Git - pdclib/blob - includes/stdio.h

   1 // ----------------------------------------------------------------------------
   2 // $Id$
   3 // ----------------------------------------------------------------------------
   4 // Public Domain C Library - http://pdclib.sourceforge.net
   5 // This code is Public Domain. Use, modify, and redistribute at will.
   6 // ----------------------------------------------------------------------------
   7 // Input/output
   8 // ----------------------------------------------------------------------------
   9
  10 #ifndef __STDIO_H
  11 #define __STDIO_H __STDIO_H
  12
  13 // ----------------------------------------------------------------------------
  14 // MACROS
  15
  16 // personality: FILENAME_MAX, FOPEN_MAX, L_tmpnam, TMP_MAX, stderr, stdin,
  17 //              stdout
  18
  19 #include "__NULL.h"
  20
  21 #define _IOFBF    0   // @see setvbuf()
  22 #define _IOLBF    1   // @see setvbuf()
  23 #define _IONBF    2   // @see setvbuf()
  24
  25 #define SEEK_SET  0   // @see fseek()
  26 #define SEEK_CUR  1   // @see fseek()
  27 #define SEEK_END  2   // @see fseek()
  28
  29 #define EOF      -1
  30
  31 // ----------------------------------------------------------------------------
  32 // TYPEDEFS
  33
  34 #include "__size_t.h"
  35
  36 typedef FILE;   // object holding all stream information, including file pos,
  37                 // buffer (optional), error indicator, EOF indicator
  38 typedef fpos_t; // position indicator type, other than array - personality?
  39                 // (see mbstate_t)
  40
  41 // ----------------------------------------------------------------------------
  42 // FUNCTIONS
  43
  44 /* TABLE OF CONTENTS (in order of appearance)
  45  *
  46  * General File Handling
  47  * * fopen()
  48  * * freopen()
  49  * * fflush()
  50  * * feof()
  51  * * ferror()
  52  * * clearerr()
  53  * * fclose()
  54  *
  55  * Rename / Remove
  56  * * rename()
  57  * * remove()
  58  *
  59  * Temporary Files
  60  * * tmpfile()
  61  * * tmpnam()
  62  *
  63  * File Positioning
  64  * * fseek()
  65  * * rewind()
  66  * * ftell()
  67  * * fgetpos()
  68  * * fsetpos()
  69  *
  70  * Reading
  71  * * fgetc()
  72  * * getc()
  73  * * getchar()
  74  * * ungetc()
  75  * * fgets()
  76  * * gets()
  77  *
  78  * Writing
  79  * * fputc()
  80  * * putc()
  81  * * putchar()
  82  * * fputs()
  83  * * puts()
  84  *
  85  * Formatted Reading
  86  * * fscanf()
  87  * * scanf()
  88  * * sscanf()
  89  * * vfscanf()
  90  * * vscanf()
  91  * * vsscanf()
  92  *
  93  * Formatted Writing
  94  * * fprintf()
  95  * * printf()
  96  * * sprintf()
  97  * * snprintf()
  98  * * vfprintf()
  99  * * vprintf()
 100  * * vsprintf()
 101  * * vsnprintf()
 102  *
 103  * Special
 104  * * perror()
 105  *
 106  * Binary Read / Write
 107  * * fread()
 108  * * fwrite()
 109  *
 110  * Buffer Handling
 111  * * setvbuf()
 112  * * setbuf()
 113  *
 114  */
 115
 116 /** File OPEN. Opens the file specified by the given name.
 117     @param filename Name of the file to be opened.
 118     @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+,
 119            specifying which mode to open the file in.
 120     @return A file handle associated with the opened file, NULL if failed.
 121  */
 122 FILE * fopen( const char * restrict filename, const char * restrict mode );
 123
 124 /** File REOPEN. Opens the file specified by the given name, associating it
 125     with the given file handle. If filename is NULL, it is attempted to change
 126     the mode of the already opened file associated with the given file handle.
 127     (This function can e.g. be used to reassociate stdin / stdout / stderr with
 128     a filename.)
 129     @param filename Name of the file to be opened.
 130     @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+,
 131            specifying which mode to open the file in.
 132     @param fh The file handle to associate with the opened file.
 133     @return fh if successful, NULL if failed.
 134  */
 135 FILE * freopen( const char * restrict filename, const char * restrict mode, FILE * fh );
 136
 137 /** File FLUSH. Flushes output buffers (if any) for given file handle. If
 138     parameter is NULL, flushes output buffers for all file handles.
 139     @param fh The file handle.
 140     @return 0 if successful, EOF if failed (setting error indicators).
 141  */
 142 int fflush( FILE * fh );
 143
 144 /** File EOF. Tests whether EOF is set for a given file.
 145     @param fh The file handle.
 146     @return 0 if EOF is not set, non-zero if EOF is set.
 147  */
 148 int feof( FILE * stream );
 149
 150 /** File ERROR. Tests whether error indicators are set for a given file.
 151     @param fh The file handle.
 152     @return 0 if no error indicators are set, non-zero otherwise.
 153  */
 154 int ferror( FILE * stream );
 155
 156 /** CLEAR ERRor. Clears EOF and error indicator of a FILE handle.
 157     @param fh The file handle.
 158  */
 159 void clearerr( FILE * fh );
 160
 161 /** File CLOSE. Flush output buffers (if any) and closes the FILE handle.
 162     @param stream The file handle.
 163     @return 0 if successful, non-zero if failed. (In any case, the FILE handle
 164             is invalid afterwards.)
 165  */
 166 int fclose( FILE * fh );
 167
 168 // ----------------------------------------------------------------------------
 169
 170 /** RENAME file. Causes a file to be no longer accessible under a given name,
 171     but a new name instead. If a file with the intended new name already
 172     exists, this implementation of rename() fails, returning INT_MAX.
 173     @param old Name of the file to be renamed.
 174     @param new Name to rename the file to.
 175     @return 0 if successful, non-zero if failed. (Implementation defined:
 176             INT_MAX if target file name already exists.)
 177  */
 178 int rename( const char * old, const char * new );
 179
 180 /** REMOVE file. Causes a file to be no longer accessible under a given name.
 181     If the file is currently open, this implementation of remove() fails,
 182     returning INT_MAX.
 183     @param filename Name of the file to be removed.
 184     @return 0 if successful, non-zero if failed. (Implementation defined:
 185             INT_MAX if the file is currently open.)
 186  */
 187 int remove( const char * filename );
 188
 189 // ----------------------------------------------------------------------------
 190
 191 /** TeMPorary FILE. Opens a file in "wb+" mode that will be automatically
 192     deleted when closed, or when the program terminates.
 193     @return A file handle for the temporary file. (NULL if opening failed.)
 194  */
 195 FILE * tmpfile( void )
 196
 197 /** TeMPorary NAMe. Generates a random file name that does not yet exist in the
 198     file system. Note that a file generated with this name is not "temporary",
 199     and must be remove()d normally.
 200     @param dest NULL, or a char[ L_tmpnam ] array.
 201     @return A pointer to a static internal buffer containing the file name,
 202             or NULL if no file name could be generated. If 'dest' is not NULL,
 203             writes the file name to and returns 'dest'.
 204  */
 205 char * tmpnam( char * dest );
 206
 207 // ----------------------------------------------------------------------------
 208
 209 /** File SEEK. Sets the current position in a file to the values specified by
 210     start and offset.
 211     @param fh The file handle.
 212     @param offset The offset from 'start' to position to.
 213     @param start The starting point from which to calculate the offset. May be
 214            one of SEEK_SET, SEEK_CUR, SEEK_END.
 215     @return 0 if successful, non-zero if error encountered.
 216  */
 217 int fseek( FILE * fh, long offset, int start );
 218
 219 /** REWIND file. Equivalent to (void) fseek( fh, 0, SEEK_SET ).
 220     @param fh The file handle.
 221  */
 222 void rewind( FILE * stream );
 223
 224 /** File TELL position. Tells the current offset into a given file.
 225     @param fh The file handle.
 226     @return The offset into the file.
 227  */
 228 long ftell( FILE * fh );
 229
 230 /** File GET POSition. Stores the current state and position in a file.
 231     @param fh The file handle.
 232     @param pos The object to store the current state in.
 233     @return 0 if successful, non-zero if error encountered.
 234  */
 235 int fgetpos( FILE * restrict fh, fpos_t * restrict pos );
 236
 237 /** File SET POSition. Sets the current file position to the value stored in a
 238     given fpos_t object.
 239     @param fh The file handle.
 240     @param pos The fpos_t object.
 241     @return 0 if successful, non-zero if error encountered.
 242  */
 243 int fsetpos( FILE * stream, const fpos_t * pos );
 244
 245 // ----------------------------------------------------------------------------
 246
 247 /** File GET Character. Reads a character from file.
 248     @param fh The file handle.
 249     @return The next character in the file, as unsigned char converted to int,
 250             or EOF if end of file is reached.
 251  */
 252 int fgetc( FILE * fh );
 253
 254 /** GET Character. Equivalent to fgetc(), but may be implemented as macro, and
 255     is allowed to evaluate its parameter more than once.
 256     @param fh The file handle.
 257     @return The character read, or EOF if end of file / error encountered.
 258  */
 259 int getc( FILE * fh );
 260
 261 /** GET CHARacter. Equivalent to getc( stdin ).
 262     @return The character read, or EOF if end of file / error encountered.
 263  */
 264 int getchar( void );
 265
 266 /** UN-GET Character. Puts a character back into an input stream.
 267     @param c The character to put back.
 268     @param fh The file handle.
 269     @return The character put back, EOF if error encountered.
 270  */
 271 int ungetc( int c, FILE * fh );
 272
 273 /** File GET String. Reads a line (terminated by newline character) from file,
 274     but reading no more than n characters.
 275     @param dest The char array to write into.
 276     @param n The maximum number of characters to read.
 277     @param fh The file handle.
 278     @return 'dest', or NULL if an error occurred.
 279  */
 280 char * fgets( char * restrict dest, int n, FILE * restrict fh );
 281
 282 /** GET String. Equivalent to fgets( dest, stdin ).
 283     @param dest The character array to write to.
 284     @return 'dest', or NULL if an error occurred.
 285  */
 286 char * gets( char * dest );
 287
 288 // ----------------------------------------------------------------------------
 289
 290 /** File PUT Character. Writes a character to file.
 291     @param c The character (when converted to unsigned char) to write.
 292     @param fh The file handle.
 293     @return 'c', or EOF if an error occurred.
 294  */
 295 int fputc( int c, FILE * stream );
 296
 297 /** PUT Character. Equivalent to fputc( c, stdout ), but may be implemented as
 298     a macro, and may evaluate the file handle more than once.
 299     @param c The character to write.
 300     @param fh The file handle.
 301     @return The character written, or EOF if error encountered.
 302  */
 303 int putc( int c, FILE * fh );
 304
 305 /** PUT CHARacter. Equivalent to putc( c, stdout ).
 306     @param c The character to write.
 307     @return The character written, or EOF if error encountered.
 308  */
 309 int putchar( int c );
 310
 311 /** File PUT String. Writes a C string to file.
 312     @param src The string to write.
 313     @param fh The file handle.
 314     @return >= 0 if successful, or EOF if an error occurred.
 315  */
 316 int fputs( const char * restrict s, FILE * restrict stream );
 317
 318 /** PUT String. Write a C string to stdout.
 319     @param src The C string to write.
 320     @return >= 0 if successful, EOF if error encountered.
 321  */
 322 int puts( const char * src );
 323
 324 // ----------------------------------------------------------------------------
 325
 326 /** File SCAN Formatted. Reads from given file handle, under control of a
 327     formatting string, the values of variables pointed to by 0..n pointers.
 328     @param fh The file handle.
 329     @param format The formatting string.
 330     @param ... A list of 0..n pointers corresponding to placeholders in
 331            'format'.
 332     @return EOF if failed, number of values successfully assigned otherwise.
 333  */
 334 int fscanf( FILE * restrict fh, const char * restrict format, ... );
 335
 336 /** SCAN Formatted. Equivalent to fscanf( stdin, format, ... )
 337     @param format The formatting string.
 338     @param ... A list of 0..n pointers corresponding to placeholders in
 339            'format'.
 340     @return EOF if failed, number of values successfully assigned otherwise.
 341  */
 342 int scanf( const char * restrict format, ... );
 343
 344 /** String SCAN Formatted. Equivalent to scanf( format, ... ), but using a C
 345     string instead of a file handle for input.
 346     @param src The input string.
 347     @param format The formatting string.
 348     @param ... A list of 0..n pointers corresponding to placeholders in
 349            'format'.
 350     @return EOF if failed, number of values successfully assigned otherwise.
 351  */
 352 int sscanf( const char * restrict src, const char * restrict format, ... );
 353
 354 /** Variable File SCAN Formatted. Equivalent to fscanf( fh, format, ... ),
 355     with the variable-length parameter list replaced by a va_list, created by
 356     the va_start macro.
 357     @param fh The file handle.
 358     @param format The formatting string.
 359     @param args The argument list created by the va_start macro.
 360     @return Number of characters printed.
 361  */
 362 int vfscanf( FILE * restrict stream, const char * restrict format, va_list args );
 363
 364 /** Variable SCAN Formatted. Equivalent to vfscanf( stdin, format, args ).
 365     @param format The formatting string.
 366     @param args The argument list created by the va_start macro.
 367     @return Number of characters printed.
 368  */
 369 int vscanf( const char * restrict format, va_list args );
 370
 371 /** Variable String SCAN Formatted. Equivalent to vscanf( format, args ), but
 372     reading from a C string instead of stdin.
 373     @param src The C string to read from.
 374     @param format The formatting string.
 375     @param args The argument list created by the va_start macro.
 376     @return Number of characters printed.
 377  */
 378 int vsscanf( const char * restrict src, const char * restrict format, va_list ap );
 379
 380 // ----------------------------------------------------------------------------
 381
 382 /** File PRINT Formatted. Prints to given file handle, under control of a
 383     formatting string, the values of 0..n variables.
 384     @param fh The file handle.
 385     @param format The formatting string.
 386     @param ... A list of 0..n variables corresponding to placeholders in
 387            'format'.
 388     @return Number of characters printed, negative value if error occurred.
 389  */
 390 int fprintf( FILE * restrict stream, const char * restrict format, ... );
 391
 392 /** PRINT Formatted. Equivalent to fprintf( stdout, format, ... ).
 393     @param format The formatting string.
 394     @param ... A list of 0..n variables corresponding to placeholders in
 395            'format'.
 396     @return Number of characters printed.
 397  */
 398 int printf( const char * restrict format, ... );
 399
 400 /** String PRINT Formatted. Equivalent to printf( format, ... ), but writing
 401     to a char array instead of stdout.
 402     @param dest The char array to write to.
 403     @param format The formatting string.
 404     @param ... A list of 0..n variables corresponding to placeholders in
 405            'format'.
 406     @return Number of characters printed.
 407  */
 408 int sprintf( char * restrict dest, const char * restrict format, ... );
 409
 410 /** String N PRINT Formatted. Equivalent to sprintf( dest, format, ... ), but
 411     will not write more than n characters.
 412     @param dest The char array to write to.
 413     @param n The maximum number of characters to write.
 414     @param format The formatting string.
 415     @param ... A list of 0..n variables corresponding to placeholders in
 416            'format'.
 417     @return Number of characters printed.
 418  */
 419 int snprintf( char * restrict s, size_t n, const char * restrict format, ... );
 420
 421 /** Variable File PRINT Formatted. Equivalent to fprintf( fh, format, ... ),
 422     with the variable-length parameter list replaced by a va_list, created by
 423     the va_start macro.
 424     @param fh The file handle.
 425     @param format The formatting string.
 426     @param args The argument list created by the va_start macro.
 427     @return Number of characters printed.
 428  */
 429 int vfprintf( FILE * restrict fh, const char * restrict format, va_list args );
 430
 431 /** Variable PRINT Formatted. Equivalent to vfprintf( stdout, format, args ).
 432     @param format The formatting string.
 433     @param args The argument list created by the va_start macro.
 434     @return Number of characters printed.
 435  */
 436 int vprintf( const char * restrict format, va_list args );
 437
 438 /** Variable String PRINT Formatted. Equivalent to vprintf( format, args ), but
 439     writing to a char array instead to stdout.
 440     @param dest The char array to write to.
 441     @param format The formatting string.
 442     @param args The argument list created by the va_start macro.
 443     @return Number of characters printed.
 444  */
 445 int vsprintf( char * restrict s, const char * restrict format, va_list ap);
 446
 447 /** Variable String N PRINT Formatted. Equivalent to vsprintf( dest, format,
 448     args ), but will not write more than n characters.
 449     @param dest The char array to write to.
 450     @param n Maximum number of characters to write.
 451     @param format The formatting string.
 452     @param args The argument list created by the va_start macro.
 453     @return Number of characters printed.
 454  */
 455 int vsnprintf( char * restrict dest, size_t n, const char * restrict format, va_list ap );
 456
 457 // ----------------------------------------------------------------------------
 458
 459 /** Print ERROR.
 460     Equivalent to fprintf( stderr, "%s: %s\n", text, strerror( errno ) ).
 461     @param test Text to prepend the error message with.
 462  */
 463 void perror( const char * text );
 464
 465 // ----------------------------------------------------------------------------
 466
 467 /** File READ. Reads a number of objects of a given size from file, and into
 468     a memory area.
 469     @param dest The memory area to write into.
 470     @param size The size of one object.
 471     @param n The number of objects to read.
 472     @param fh The file handle.
 473     @return The number of objects successfully read.
 474  */
 475 size_t fread( void * restrict dest, size_t size, size_t n, FILE * restrict fh );
 476
 477 /** File WRITE. Writes a number of objects from a memory area to file.
 478     @param src The memory area to write from.
 479     @param size The size of a single object.
 480     @param n The number of objects to write.
 481     @param fh The file handle.
 482     @return The number of objects successfully written.
 483  */
 484 size_t fwrite( const void * restrict src, size_t size, size_t n, FILE * restrict fh );
 485
 486 // ----------------------------------------------------------------------------
 487
 488 /** SET Virtual BUFfer. Sets buffering mode and (optionally) the memory used
 489     for buffering, for a given file handle.
 490     This function must only be called immediately after associating the file
 491     handle with a file, before any operations are called on the file handle.
 492     @param fh The file handle.
 493     @param buf A pointer to the memory area to use for buffering, or NULL to
 494            use internally assigned buffer memory.
 495     @param mode One of _IOFBF, _IOLBF, _IONBF.
 496     @param size Size of the memory area to be used for buffering.
 497  */
 498 int setvbuf( FILE * restrict fh, char * restrict buf, int mode, size_t size );
 499
 500 /** SET BUFfer. Equivalent to (void) setvbuf( fh, buf, _IOFBF, BUFSIZ ), or
 501     (void) setvbuf( fh, NULL, _IONBF, BUFSIZ ) if buf == NULL.
 502     @param fh The file handle to be passed to setvbuf().
 503     @param buf The buffer pointer to be passed to setvbuf().
 504  */
 505 void setbuf( FILE * restrict fh, char * restrict buf );
 506
 507 // ----------------------------------------------------------------------------
 508
 509 /* PDPC code - unreviewed
 510 /*
 511     What we have is an internal buffer, which is 8 characters
 512     longer than the actually used buffer.  E.g. say BUFSIZ is
 513     512 bytes, then we actually allocate 520 bytes.  The first
 514     2 characters will be junk, the next 2 characters set to NUL,
 515     for protection against some backward-compares.  The fourth-last
 516     character is set to '\n', to protect against overscan.  The
 517     last 3 characters will be junk, to protect against memory
 518     violation.  intBuffer is the internal buffer, but everyone refers
 519     to fbuf, which is actually set to the &intBuffer[4].  Also,
 520     szfbuf is the size of the "visible" buffer, not the internal
 521     buffer.  The reason for the 2 junk characters at the beginning
 522     is to align the buffer on a 4-byte boundary.
 523 */
 524
 525 typedef struct
 526 {
 527 #if (defined(__OS2__) || defined(__32BIT__))
 528     unsigned long hfile;  /* OS/2 file handle */
 529 #endif
 530 #if (defined(__MSDOS__) || defined(__DOS__) || defined(__POWERC))
 531     int hfile; /* dos file handle */
 532 #endif
 533 #if (defined(__MVS__))
 534     void *hfile;
 535     int recfm;
 536     int style;
 537     int lrecl;
 538     char ddname[9];
 539 #endif
 540     int quickBin;  /* 1 = do DosRead NOW!!!! */
 541     int quickText; /* 1 = quick text mode */
 542     int textMode; /* 1 = text mode, 0 = binary mode */
 543     int intFno;   /* internal file number */
 544     unsigned long bufStartR; /* buffer start represents, e.g. if we
 545         have read in 3 buffers, each of 512 bytes, and we are
 546         currently reading from the 3rd buffer, then the first
 547         character in the buffer would be 1024, so that is what is
 548         put in bufStartR. */
 549     char *fbuf;     /* file buffer - this is what all the routines
 550                        look at. */
 551     size_t szfbuf;  /* size of file buffer (the one that the routines
 552                        see, and the user allocates, and what is actually
 553                        read in from disk) */
 554     char *upto;     /* what character is next to read from buffer */
 555     char *endbuf;   /* pointer PAST last character in buffer, ie it
 556                        points to the '\n' in the internal buffer */
 557     int errorInd;   /* whether an error has occurred on this file */
 558     int eofInd;     /* whether EOF has been reached on this file */
 559     int ungetCh;    /* character pushed back, -1 if none */
 560     int bufTech;    /* buffering technique, _IOFBF etc */
 561     char *intBuffer; /* internal buffer */
 562     int noNl;       /* When doing gets, we don't copy NL */
 563     int mode;       /* __WRITE_MODE or __READ_MODE */
 564     int update;     /* Is file update (read + write)? */
 565     int theirBuffer; /* Is the buffer supplied by them? */
 566 } FILE;
 567
 568 typedef unsigned long fpos_t;
 569
 570 #define NULL ((void *)0)
 571 #define FILENAME_MAX 260
 572 #define FOPEN_MAX 40
 573 #define _IOFBF 1
 574 #define _IOLBF 2
 575 #define _IONBF 3
 576 /*#define BUFSIZ 409600*/
 577 /* #define BUFSIZ 8192 */
 578 /*#define BUFSIZ 5120*/
 579 #define BUFSIZ 6144
 580 /* #define BUFSIZ 10 */
 581 /* #define BUFSIZ 512 */
 582 #define EOF -1
 583 #define L_tmpnam FILENAME_MAX
 584 #define TMP_MAX 25
 585 #define SEEK_SET 0
 586 #define SEEK_CUR 1
 587 #define SEEK_END 2
 588 #define __NFILE (FOPEN_MAX - 3)
 589 #define __WRITE_MODE 1
 590 #define __READ_MODE 2
 591
 592 extern FILE *stdin;
 593 extern FILE *stdout;
 594 extern FILE *stderr;
 595
 596 extern FILE *__userFiles[__NFILE];
 597 */
 598
 599 #endif // __STDIO_H