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

   1 /* $Id$ */
   2
   3 /* Input/output <stdio.h>
   4
   5    This file is part of the Public Domain C Library (PDCLib).
   6    Permission is granted to use, modify, and / or redistribute at will.
   7 */
   8
   9 #ifndef _PDCLIB_STDIO_H
  10 #define _PDCLIB_STDIO_H _PDCLIB_STDIO_H
  11
  12 #ifndef _PDCLIB_INT_H
  13 #define _PDCLIB_INT_H _PDCLIB_INT_H
  14 #include <_PDCLIB_int.h>
  15 #endif
  16
  17 #ifndef _PDCLIB_SIZE_T_DEFINED
  18 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
  19 typedef _PDCLIB_size_t size_t;
  20 #endif
  21
  22 #ifndef _PDCLIB_NULL_DEFINED
  23 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
  24 #define NULL _PDCLIB_NULL
  25 #endif
  26
  27 /* See setvbuf(), third argument */
  28 #define _IOFBF 2
  29 #define _IOLBF 1
  30 #define _IONBF 0
  31
  32 /* The following are platform-dependant, and defined in _PDCLIB_config.h. */
  33 typedef _PDCLIB_fpos_t        fpos_t;
  34 typedef struct _PDCLIB_file_t FILE;
  35 #define EOF -1
  36 #define BUFSIZ _PDCLIB_BUFSIZ
  37 #define FOPEN_MAX _PDCLIB_FOPEN_MAX
  38 #define FILENAME_MAX _PDCLIB_FILENAME_MAX
  39 #define L_tmpnam _PDCLIB_L_tmpnam
  40 #define TMP_MAX _PDCLIB_TMP_MAX
  41
  42 /* See fseek(), third argument */
  43 #define SEEK_CUR 1
  44 #define SEEK_END 2
  45 #define SEEK_SET 4
  46
  47 /* Operations on files */
  48
  49 /* Remove the given file.
  50    Returns zero if successful, non-zero otherwise.
  51    This implementation does detect if the filename corresponds to an open file,
  52    and closes it before attempting the rename.
  53 */
  54 int remove( const char * filename );
  55
  56 /* Rename the given old file to the given new name.
  57    Returns zero if successful, non-zero otherwise.
  58    This implementation does detect if the old filename corresponds to an open
  59    file, and closes it before attempting the rename.
  60    If the already is a file with the new filename, behaviour is defined by the
  61    OS.
  62 */
  63 int rename( const char * old, const char * new );
  64
  65 /* Open a temporary file with mode "wb+", i.e. binary-update. Remove the file
  66    automatically if it is closed or the program exits normally (by returning
  67    from main() or calling exit()).
  68    Returns a pointer to a FILE handle for this file.
  69    This implementation does not remove temporary files if the process aborts
  70    abnormally (e.g. abort()).
  71 */
  72 FILE * tmpfile( void );
  73
  74 /* Generate a file name that is not equal to any existing filename AT THE TIME
  75    OF GENERATION. Generate a different name each time it is called.
  76    Returns a pointer to an internal static buffer containing the filename if s
  77    is a NULL pointer. (This is not thread-safe!)
  78    Returns s if it is not a NULL pointer (s is then assumed to point to an array
  79    of at least L_tmpnam characters).
  80    Returns NULL if unable to generate a suitable name (because all possible
  81    names already exist, or the function has been called TMP_MAX times already).
  82    Note that this implementation cannot guarantee a file of the name generated
  83    is not generated between the call to this function and a subsequent fopen().
  84 */
  85 char * tmpnam( char * s );
  86
  87 /* File access functions */
  88
  89 /* Close the file associated with the given stream (after flushing its buffers).
  90    Returns zero if successful, EOF if any errors occur.
  91 */
  92 int fclose( FILE * stream );
  93
  94 /* Flush the buffers of the given output stream. If the stream is an input
  95    stream, or an update stream with the last operation being an input operation,
  96    behaviour is undefined.
  97    If stream is a NULL pointer, perform the buffer flushing for all applicable
  98    streams.
  99    Returns zero if successful, EOF if a write error occurs.
 100    Sets the error indicator of the stream if a write error occurs.
 101 */
 102 int fflush( FILE * stream );
 103
 104 /* Open the file with the given filename in the given mode, and return a stream
 105    handle for it in which error and end-of-file indicator are cleared. Defined
 106    values for mode are:
 107
 108    READ MODES
 109                       text files        binary files
 110    without update     "r"               "rb"
 111    with update        "r+"              "rb+" or "r+b"
 112
 113    Opening in read mode fails if no file with the given filename exists, or if
 114    cannot be read.
 115
 116    WRITE MODES
 117                       text files        binary files
 118    without update     "w"               "wb"
 119    with update        "w+"              "wb+" or "w+b"
 120
 121    With write modes, if a file with the given filename already exists, it is
 122    truncated to zero length.
 123
 124    APPEND MODES
 125                       text files        binary files
 126    without update     "a"               "ab"
 127    with update        "a+"              "ab+" or "a+b"
 128
 129    With update modes, if a file with the given filename already exists, it is
 130    not truncated to zero length, but all writes are forced to end-of-file (this
 131    regardless to fseek() calls). Note that binary files opened in append mode
 132    might have their end-of-file padded with '\0' characters.
 133
 134    Update modes mean that both input and output functions can be performed on
 135    the stream, but output must be terminated with a call to either fflush(),
 136    fseek(), fsetpos(), or rewind() before input is performed, and input must
 137    be terminated with a call to either fseek(), fsetpos(), or rewind() before
 138    output is performed, unless input encountered end-of-file.
 139
 140    If a text file is opened with update mode, the implementation is at liberty
 141    to open a binary stream instead. This implementation honors the exact mode
 142    given.
 143
 144    The stream is fully buffered if and only if it can be determined not to
 145    refer to an interactive device. As the generic code of this implementation
 146    cannot determine this, _IOLBF (line buffering) is used for all streams.
 147
 148    If the mode string begins with but is longer than one of the above sequences
 149    the implementation is at liberty to ignore the additional characters, or do
 150    implementation-defined things. This implementation only accepts the exact
 151    modes above.
 152
 153    Returns a pointer to the stream handle if successfull, NULL otherwise.
 154 */
 155 FILE * fopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode );
 156
 157 /* Close any file currently associated with the given stream. Open the file
 158    identified by the given filename with the given mode (equivalent to fopen()),
 159    and associate it with the given stream. If filename is a NULL pointer,
 160    attempt to change the mode of the given stream.
 161    This implementation allows the following mode changes: TODO
 162    (Primary use of this function is to redirect stdin, stdout, and stderr.)
 163 */
 164 FILE * freopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode, FILE * _PDCLIB_restrict stream );
 165
 166 /* If buf is a NULL pointer, call setvbuf( stream, NULL, _IONBF, BUFSIZ ).
 167    If buf is not a NULL pointer, call setvbuf( stream, buf, _IOFBF, BUFSIZ ).
 168 */
 169 void setbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf );
 170
 171 /* Set the given stream to the given buffering mode. If buf is not a NULL
 172    pointer, use buf as file buffer (of given size). If buf is a NULL pointer,
 173    use a buffer of given size allocated internally. _IONBF causes unbuffered
 174    behaviour, _IOLBF causes line-buffered behaviour, _IOFBF causes fully
 175    buffered behaviour. Calling this function is only valid right after a file is
 176    opened, and before any other operation (except for any unsuccessful calls to
 177    setvbuf()) has been performed.
 178    Returns zero if successful, nonzero otherwise.
 179 */
 180 int setvbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf, int mode, size_t size );
 181
 182 /* Formatted input/output functions */
 183 int fprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 184 int fscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 185 int printf( const char * _PDCLIB_restrict format, ... );
 186 int scanf( const char * _PDCLIB_restrict format, ... );
 187 int snprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, ... );
 188 int sprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 189 int sscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 190 int vfprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 191 int vfscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 192 int vprintf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 193 int vscanf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 194 int vsnprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 195 int vsprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 196 int vsscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 197
 198 /* Character input/output functions */
 199
 200 /* Retrieve the next character from given stream.
 201    Returns the character, EOF otherwise.
 202    If end-of-file is reached, the EOF indicator of the stream is set.
 203    If a read error occurs, the error indicator of the stream is set.
 204 */
 205 int fgetc( FILE * stream );
 206
 207 /* Read at most n-1 characters from given stream into the array s, stopping at
 208    \n or EOF. Terminate the read string with \n. If EOF is encountered before
 209    any characters are read, leave the contents of s unchanged.
 210    Returns s if successful, NULL otherwise.
 211    If a read error occurs, the error indicator of the stream is set. In this
 212    case, the contents of s are indeterminate.
 213 */
 214 char * fgets( char * _PDCLIB_restrict s, int n, FILE * _PDCLIB_restrict stream );
 215
 216 /* Write the value c (cast to unsigned char) to the given stream.
 217    Returns c if successful, EOF otherwise.
 218    If a write error occurs, sets the error indicator of the stream is set.
 219 */
 220 int fputc( int c, FILE * stream );
 221
 222 /* Write the string s (not including the terminating \0) to the given stream.
 223    Returns a value >=0 if successful, EOF otherwise.
 224    This implementation does set the error indicator of the stream if a write
 225    error occurs.
 226 */
 227 int fputs( const char * _PDCLIB_restrict s, FILE * _PDCLIB_restrict stream );
 228
 229 /* Equivalent to fgetc( stream ), but may be implemented as a macro that
 230    evaluates its parameter more than once.
 231 */
 232 #define getc( stream ) fgetc( stream )
 233
 234 /* Equivalent to fgetc( stdin ), but may be implemented as a macro. */
 235 #define getchar() fgetc( stdin )
 236
 237 /* Read characters from given stream into the array s, stopping at \n or EOF.
 238    The string read is terminated with \0. Returns s if successful. If EOF is
 239    encountered before any characters are read, the contents of s are unchanged,
 240    and NULL is returned. If a read error occurs, the contents of s are indeter-
 241    minate, and NULL is returned.
 242 */
 243 char * gets( char * s );
 244
 245 /* Equivalent to fputc( c, stream ), but may be implemented as a macro that
 246    evaluates its parameter more than once.
 247 */
 248 #define putc( c, stream ) fputc( c, stream )
 249
 250 /* Equivalent to fputc( c, stdout ), but may be implemented as a macro that
 251    evaluates its parameter more than once.
 252 */
 253 int putchar( int c );
 254
 255 /* Write the string s (not including the terminating \0) to stdout, and append
 256    a newline to the output. Returns a value >= 0 when successful, EOF if a
 257    write error occurred.
 258 */
 259 int puts( const char * s );
 260
 261 /* Push the value c (cast to unsigned char) back onto the given (input) stream.
 262    A character pushed back in this way will be delivered by subsequent read
 263    operations (and skipped by subsequent file positioning operations) as if it
 264    has not been read. The external representation of the stream is unaffected
 265    by this pushback (it is a buffer operation). One character of pushback is
 266    guaranteed, further pushbacks may fail. EOF as value for c does not change
 267    the input stream and results in failure of the function.
 268    For text files, the file position indicator is indeterminate until all
 269    pushed-back characters are read. For binary files, the file position
 270    indicator is decremented by each successful call of ungetc(). If the file
 271    position indicator for a binary file was zero before the call of ungetc(),
 272    behaviour is undefined. (Older versions of the library allowed such a call.)
 273    Returns the pushed-back character if successful, EOF if it fails.
 274 */
 275 int ungetc( int c, FILE * stream );
 276
 277 /* Direct input/output functions */
 278
 279 /* Read up to nmemb elements of given size from given stream into the buffer
 280    pointed to by ptr. Returns the number of elements successfully read, which
 281    may be less than nmemb if a read error or EOF is encountered. If a read
 282    error is encountered, the value of the file position indicator is
 283    indeterminate. If a partial element is read, its value is indeterminate.
 284    If size or nmemb are zero, the function does nothing and returns zero.
 285 */
 286 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 287
 288 /* Write up to nmemb elements of given size from buffer pointed to by ptr to
 289    the given stream. Returns the number of elements successfully written, which
 290    will be less than nmemb only if a write error is encountered. If a write
 291    error is encountered, the value of the file position indicator is
 292    indeterminate. If size or nmemb are zero, the function does nothing and
 293    returns zero.
 294 */
 295 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 296
 297 /* File positioning functions */
 298
 299 /* Store the current position indicator (and, where appropriate, the current
 300    mbstate_t status object) for the given stream into the given pos object. The
 301    actual contents of the object are unspecified, but it can be used as second
 302    parameter to fsetpos() to reposition the stream to the exact position and
 303    parse state at the time fgetpos() was called.
 304    Returns zero if successful, nonzero otherwise.
 305    TODO: Implementation-defined errno setting for fgetpos().
 306 */
 307 int fgetpos( FILE * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
 308
 309 /* Set the position indicator for the given stream to the given offset from:
 310    - the beginning of the file if whence is SEEK_SET,
 311    - the current value of the position indicator if whence is SEEK_CUR,
 312    - end-of-file if whence is SEEK_END.
 313    On text streams, non-zero offsets are only allowed with SEEK_SET, and must
 314    have been returned by ftell() for the same file.
 315    Any characters buffered by ungetc() are dropped, the end-of-file indicator
 316    for the stream is cleared. If the given stream is an update stream, the next
 317    operation after a successful fseek() may be either input or output.
 318    Returns zero if successful, nonzero otherwise. If a read/write error occurs,
 319    the error indicator for the given stream is set.
 320 */
 321 int fseek( FILE * stream, long int offset, int whence );
 322
 323 /* Set the position indicator (and, where appropriate the mbstate_t status
 324    object) for the given stream to the given pos object (created by an earlier
 325    call to fgetpos() on the same file).
 326    Any characters buffered by ungetc() are dropped, the end-of-file indicator
 327    for the stream is cleared. If the given stream is an update stream, the next
 328    operation after a successful fsetpos() may be either input or output.
 329    Returns zero if successful, nonzero otherwise. If a read/write error occurs,
 330    the error indicator for the given stream is set.
 331    TODO: Implementation-defined errno setting for fsetpos().
 332 */
 333 int fsetpos( FILE * stream, const fpos_t * pos );
 334
 335 /* Return the current offset of the given stream from the beginning of the
 336    associated file. For text streams, the exact value returned is unspecified
 337    (and may not be equal to the number of characters), but may be used in
 338    subsequent calls to fseek().
 339    Returns -1L if unsuccessful.
 340    TODO: Implementation-defined errno setting for ftell().
 341 */
 342 long int ftell( FILE * stream );
 343
 344 /* Equivalent to (void)fseek( stream, 0L, SEEK_SET ), except that the error
 345    indicator for the stream is also cleared.
 346 */
 347 void rewind( FILE * stream );
 348
 349 /* Error-handling functions */
 350
 351 /* Clear the end-of-file and error indicators for the given stream. */
 352 void clearerr( FILE * stream );
 353
 354 /* Return zero if the end-of-file indicator for the given stream is not set,
 355    nonzero otherwise.
 356 */
 357 int feof( FILE * stream );
 358
 359 /* Return zero if the error indicator for the given stream is not set, nonzero
 360    otherwise.
 361 */
 362 int ferror( FILE * stream );
 363
 364 /* If s is neither a NULL pointer nor an empty string, print the string to
 365    stderr (with appended colon (':') and a space) first. In any case, print an
 366    error message depending on the current value of errno (being the same as if
 367    strerror( errno ) had been called).
 368 */
 369 void perror( const char * s );
 370
 371 #endif