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
  18 #define _IOFBF       // integer constant suitable as 3rd argument to setvbuf()
  19 #define _IOLBF       // integer constant suitable as 3rd argument to setvbuf()
  20 #define _IONBF       // integer constant suitable as 3rd argument to setvbuf()
  21 #define BUFSIZ       // integer constant, size of the buffer used by setbuf(),
  22                      // >= 256
  23 #define EOF          // TODO
  24 #define FILENAME_MAX // length of filenames supported
  25 #define FOPEN_MAX    // number of simultaneous open files supported, >= 8
  26 #define L_tmpnam     // length of filenames generated by tmpnam()
  27 #define SEEK_CUR     // integer constant suitable as 3rd argument to fseek()
  28 #define SEEK_END     // integer constant suitable as 3rd argument to fseek()
  29 #define SEEK_SET     // integer constant suitable as 3rd argument to fseek()
  30 #define TMP_MAX      // number of unique filenames generateable by tmpnam(),
  31                      // >= 25
  32
  33 #define stderr // FILE*, not fully buffered
  34 #define stdin  // FILE*, fully buffered only when not interactive device
  35 #define stdout // FILE*, fully buffered only when not interactive device
  36
  37 // ----------------------------------------------------------------------------
  38 // TYPEDEFS
  39
  40 #include "__size_t.h"
  41
  42 typedef FILE;   // object holding all stream information, including file pos,
  43                 // buffer (optional), error indicator, EOF indicator
  44 typedef fpos_t; // position indicator type, other than array - personality?
  45                 // (see mbstate_t)
  46
  47 // ----------------------------------------------------------------------------
  48 // FUNCTIONS
  49
  50 /** CLEAR ERRor. Clears EOF and error indicator of a FILE handle.
  51     @param fh The file handle.
  52  */
  53 void clearerr( FILE * fh );
  54
  55 /** File CLOSE. Flush output buffers (if any) and closes the FILE handle.
  56     @param stream The file handle.
  57     @return 0 if successful, non-zero if failed. (In any case, the FILE handle
  58             is invalid afterwards.)
  59  */
  60 int fclose( FILE * fh );
  61
  62 int feof( FILE * stream );
  63 int ferror( FILE * stream );
  64
  65 /** File FLUSH. Flushes output buffers (if any) for given file handle. If
  66     parameter is NULL, flushes output buffers for all file handles.
  67     @param fh The file handle.
  68     @return 0 if successful, EOF if failed (setting error indicators).
  69  */
  70 int fflush( FILE * fh );
  71
  72 /** File OPEN. Opens the file specified by the given name.
  73     @param filename Name of the file to be opened.
  74     @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+,
  75            specifying which mode to open the file in.
  76     @return A file handle associated with the opened file, NULL if failed.
  77  */
  78 FILE * fopen( const char * restrict filename, const char * restrict mode );
  79
  80 /** File REOPEN. Opens the file specified by the given name, associating it
  81     with the given file handle. If filename is NULL, it is attempted to change
  82     the mode of the already opened file associated with the given file handle.
  83     (This function can e.g. be used to reassociate stdin / stdout / stderr with
  84     a filename.)
  85     @param filename Name of the file to be opened.
  86     @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+,
  87            specifying which mode to open the file in.
  88     @param fh The file handle to associate with the opened file.
  89     @return fh if successful, NULL if failed.
  90  */
  91 FILE * freopen( const char * restrict filename, const char * restrict mode, FILE * fh );
  92
  93 /** REMOVE file. Causes a file to be no longer accessible under a given name.
  94     If the file is currently open, this implementation of remove() fails,
  95     returning INT_MAX.
  96     @param filename Name of the file to be removed.
  97     @return 0 if successful, non-zero if failed. (Implementation defined:
  98             INT_MAX if the file is currently open.)
  99  */
 100 int remove( const char * filename );
 101
 102 /** RENAME file. Causes a file to be no longer accessible under a given name,
 103     but a new name instead. If a file with the intended new name already
 104     exists, this implementation of rename() fails, returning INT_MAX.
 105     @param old Name of the file to be renamed.
 106     @param new Name to rename the file to.
 107     @return 0 if successful, non-zero if failed. (Implementation defined:
 108             INT_MAX if target file name already exists.)
 109  */
 110 int rename( const char * old, const char * new );
 111
 112 void rewind( FILE * stream );
 113
 114 /** SET Virtual BUFfer. Sets buffering mode and (optionally) the memory used
 115     for buffering, for a given file handle.
 116     This function must only be called immediately after associating the file
 117     handle with a file, before any operations are called on the file handle.
 118     @param fh The file handle.
 119     @param buf A pointer to the memory area to use for buffering, or NULL to
 120            use internally assigned buffer memory.
 121     @param mode One of _IOFBF, _IOLBF, _IONBF.
 122     @param size Size of the memory area to be used for buffering.
 123  */
 124 int setvbuf( FILE * restrict fh, char * restrict buf, int mode, size_t size );
 125
 126 /** SET BUFfer. Equivalent to (void) setvbuf( fh, buf, _IOFBF, BUFSIZ ), or
 127     (void) setvbuf( fh, NULL, _IONBF, BUFSIZ ) if buf == NULL.
 128     @param fh The file handle to be passed to setvbuf().
 129     @param buf The buffer pointer to be passed to setvbuf().
 130  */
 131 void setbuf( FILE * restrict fh, char * restrict buf );
 132
 133 /** TeMPorary FILE. Opens a file in "wb+" mode that will be automatically
 134     deleted when closed, or when the program terminates.
 135     @return A file handle for the temporary file. (NULL if opening failed.)
 136  */
 137 FILE * tmpfile( void )
 138
 139 /** TeMPorary NAMe. Generates a random file name that does not yet exist in the
 140     file system. Note that a file generated with this name is not "temporary",
 141     and must be remove()d normally.
 142     @param dest NULL, or a char[ L_tmpnam ] array.
 143     @return A pointer to a static internal buffer containing the file name,
 144             or NULL if no file name could be generated. If 'dest' is not NULL,
 145             writes the file name to and returns 'dest'.
 146  */
 147 char * tmpnam( char * dest );
 148
 149 int fseek( FILE * stream, long offset, int mode );
 150 int fsetpos( FILE * stream, const fpos_t * pos );
 151 int fgetpos( FILE * restrict stream, fpos_t * restrict pos );
 152 long ftell( FILE * stream );
 153
 154 int fgetc( FILE * stream );
 155 char *fgets( char * restrict s, int n, FILE * restrict stream );
 156 size_t fread( void * restrict ptr, size_t size, size_t nelem, FILE * restrict stream );
 157 int getc( FILE * stream );
 158 int getchar( void );
 159 char * gets( char * s );
 160 int ungetc( int c, FILE * stream );
 161
 162 int fputc( int c, FILE * stream );
 163 int fputs( const char * restrict s, FILE * restrict stream );
 164 size_t fwrite( const void * restrict ptr, size_t size, size_t nelem, FILE * restrict stream );
 165 void perror( const char * s );
 166 int putc( int c, FILE * stream );
 167 int putchar( int c );
 168 int puts( const char * s );
 169
 170 /** File SCAN Formatted. Reads from given file handle, under control of a
 171     formatting string, the values of variables pointed to by 0..n pointers.
 172     @param fh The file handle.
 173     @param format The formatting string.
 174     @param ... A list of 0..n pointers corresponding to placeholders in
 175            'format'.
 176     @return EOF if failed, number of values successfully assigned otherwise.
 177  */
 178 int fscanf( FILE * restrict fh, const char * restrict format, ... );
 179
 180 /** SCAN Formatted. Equivalent to fscanf( stdin, format, ... )
 181     @param format The formatting string.
 182     @param ... A list of 0..n pointers corresponding to placeholders in
 183            'format'.
 184     @return EOF if failed, number of values successfully assigned otherwise.
 185  */
 186 int scanf( const char * restrict format, ... );
 187
 188 /** String SCAN Formatted. Equivalent to scanf( format, ... ), but using a C
 189     string instead of a file handle for input.
 190     @param src The input string.
 191     @param format The formatting string.
 192     @param ... A list of 0..n pointers corresponding to placeholders in
 193            'format'.
 194     @return EOF if failed, number of values successfully assigned otherwise.
 195  */
 196 int sscanf( const char * restrict src, const char * restrict format, ... );
 197
 198 /** Variable File SCAN Formatted. Equivalent to fscanf( fh, format, ... ),
 199     with the variable-length parameter list replaced by a va_list, created by
 200     the va_start macro.
 201     @param fh The file handle.
 202     @param format The formatting string.
 203     @param args The argument list created by the va_start macro.
 204     @return Number of characters printed.
 205  */
 206 int vfscanf( FILE * restrict stream, const char * restrict format, va_list args );
 207
 208 /** Variable SCAN Formatted. Equivalent to vfscanf( stdin, format, args ).
 209     @param format The formatting string.
 210     @param args The argument list created by the va_start macro.
 211     @return Number of characters printed.
 212  */
 213 int vscanf( const char * restrict format, va_list args );
 214
 215 /** Variable String SCAN Formatted. Equivalent to vscanf( format, args ), but
 216     reading from a C string instead of stdin.
 217     @param src The C string to read from.
 218     @param format The formatting string.
 219     @param args The argument list created by the va_start macro.
 220     @return Number of characters printed.
 221  */
 222 int vsscanf( const char * restrict src, const char * restrict format, va_list ap );
 223
 224 /** File PRINT Formatted. Prints to given file handle, under control of a
 225     formatting string, the values of 0..n variables.
 226     @param fh The file handle.
 227     @param format The formatting string.
 228     @param ... A list of 0..n variables corresponding to placeholders in
 229            'format'.
 230     @return Number of characters printed, negative value if error occurred.
 231  */
 232 int fprintf( FILE * restrict stream, const char * restrict format, ... );
 233
 234 /** PRINT Formatted. Equivalent to fprintf( stdout, format, ... ).
 235     @param format The formatting string.
 236     @param ... A list of 0..n variables corresponding to placeholders in
 237            'format'.
 238     @return Number of characters printed.
 239  */
 240 int printf( const char * restrict format, ... );
 241
 242 /** String N PRINT Formatted. Equivalent to sprintf( dest, format, ... ), but
 243     will not write more than n characters.
 244     @param dest The char array to write to.
 245     @param n The maximum number of characters to write.
 246     @param format The formatting string.
 247     @param ... A list of 0..n variables corresponding to placeholders in
 248            'format'.
 249     @return Number of characters printed.
 250  */
 251 int snprintf( char * restrict s, size_t n, const char * restrict format, ... );
 252
 253 /** String PRINT Formatted. Equivalent to printf( format, ... ), but writing
 254     to a char array instead of stdout.
 255     @param dest The char array to write to.
 256     @param format The formatting string.
 257     @param ... A list of 0..n variables corresponding to placeholders in
 258            'format'.
 259     @return Number of characters printed.
 260  */
 261 int sprintf( char * restrict dest, const char * restrict format, ... );
 262
 263 /** Variable File PRINT Formatted. Equivalent to fprintf( fh, format, ... ),
 264     with the variable-length parameter list replaced by a va_list, created by
 265     the va_start macro.
 266     @param fh The file handle.
 267     @param format The formatting string.
 268     @param args The argument list created by the va_start macro.
 269     @return Number of characters printed.
 270  */
 271 int vfprintf( FILE * restrict fh, const char * restrict format, va_list args );
 272
 273 /** Variable PRINT Formatted. Equivalent to vfprintf( stdout, format, args ).
 274     @param format The formatting string.
 275     @param args The argument list created by the va_start macro.
 276     @return Number of characters printed.
 277  */
 278 int vprintf( const char * restrict format, va_list args );
 279
 280 /** Variable String N PRINT Formatted. Equivalent to vsprintf( dest, format,
 281     args ), but will not write more than n characters.
 282     @param dest The char array to write to.
 283     @param n Maximum number of characters to write.
 284     @param format The formatting string.
 285     @param args The argument list created by the va_start macro.
 286     @return Number of characters printed.
 287  */
 288 int vsnprintf( char * restrict dest, size_t n, const char * restrict format, va_list ap );
 289
 290 /** Variable String PRINT Formatted. Equivalent to vprintf( format, args ), but
 291     writing to a char array instead to stdout.
 292     @param dest The char array to write to.
 293     @param format The formatting string.
 294     @param args The argument list created by the va_start macro.
 295     @return Number of characters printed.
 296  */
 297 int vsprintf( char * restrict s, const char * restrict format, va_list ap);
 298
 299 /* PDPC code - unreviewed
 300 /*
 301     What we have is an internal buffer, which is 8 characters
 302     longer than the actually used buffer.  E.g. say BUFSIZ is
 303     512 bytes, then we actually allocate 520 bytes.  The first
 304     2 characters will be junk, the next 2 characters set to NUL,
 305     for protection against some backward-compares.  The fourth-last
 306     character is set to '\n', to protect against overscan.  The
 307     last 3 characters will be junk, to protect against memory
 308     violation.  intBuffer is the internal buffer, but everyone refers
 309     to fbuf, which is actually set to the &intBuffer[4].  Also,
 310     szfbuf is the size of the "visible" buffer, not the internal
 311     buffer.  The reason for the 2 junk characters at the beginning
 312     is to align the buffer on a 4-byte boundary.
 313 */
 314
 315 typedef struct
 316 {
 317 #if (defined(__OS2__) || defined(__32BIT__))
 318     unsigned long hfile;  /* OS/2 file handle */
 319 #endif
 320 #if (defined(__MSDOS__) || defined(__DOS__) || defined(__POWERC))
 321     int hfile; /* dos file handle */
 322 #endif
 323 #if (defined(__MVS__))
 324     void *hfile;
 325     int recfm;
 326     int style;
 327     int lrecl;
 328     char ddname[9];
 329 #endif
 330     int quickBin;  /* 1 = do DosRead NOW!!!! */
 331     int quickText; /* 1 = quick text mode */
 332     int textMode; /* 1 = text mode, 0 = binary mode */
 333     int intFno;   /* internal file number */
 334     unsigned long bufStartR; /* buffer start represents, e.g. if we
 335         have read in 3 buffers, each of 512 bytes, and we are
 336         currently reading from the 3rd buffer, then the first
 337         character in the buffer would be 1024, so that is what is
 338         put in bufStartR. */
 339     char *fbuf;     /* file buffer - this is what all the routines
 340                        look at. */
 341     size_t szfbuf;  /* size of file buffer (the one that the routines
 342                        see, and the user allocates, and what is actually
 343                        read in from disk) */
 344     char *upto;     /* what character is next to read from buffer */
 345     char *endbuf;   /* pointer PAST last character in buffer, ie it
 346                        points to the '\n' in the internal buffer */
 347     int errorInd;   /* whether an error has occurred on this file */
 348     int eofInd;     /* whether EOF has been reached on this file */
 349     int ungetCh;    /* character pushed back, -1 if none */
 350     int bufTech;    /* buffering technique, _IOFBF etc */
 351     char *intBuffer; /* internal buffer */
 352     int noNl;       /* When doing gets, we don't copy NL */
 353     int mode;       /* __WRITE_MODE or __READ_MODE */
 354     int update;     /* Is file update (read + write)? */
 355     int theirBuffer; /* Is the buffer supplied by them? */
 356 } FILE;
 357
 358 typedef unsigned long fpos_t;
 359
 360 #define NULL ((void *)0)
 361 #define FILENAME_MAX 260
 362 #define FOPEN_MAX 40
 363 #define _IOFBF 1
 364 #define _IOLBF 2
 365 #define _IONBF 3
 366 /*#define BUFSIZ 409600*/
 367 /* #define BUFSIZ 8192 */
 368 /*#define BUFSIZ 5120*/
 369 #define BUFSIZ 6144
 370 /* #define BUFSIZ 10 */
 371 /* #define BUFSIZ 512 */
 372 #define EOF -1
 373 #define L_tmpnam FILENAME_MAX
 374 #define TMP_MAX 25
 375 #define SEEK_SET 0
 376 #define SEEK_CUR 1
 377 #define SEEK_END 2
 378 #define __NFILE (FOPEN_MAX - 3)
 379 #define __WRITE_MODE 1
 380 #define __READ_MODE 2
 381
 382 extern FILE *stdin;
 383 extern FILE *stdout;
 384 extern FILE *stderr;
 385
 386 extern FILE *__userFiles[__NFILE];
 387 */
 388
 389 #endif // __STDIO_H