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