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