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 /* Fully buffered - transmit block-wise */
  29 #define _IOFBF 2
  30 /* Line buffered - transmit line-wise */
  31 #define _IOLBF 1
  32 /* Not buffered - transmit immediately */
  33 #define _IONBF 0
  34
  35 /* The following are platform-dependant, and defined in _PDCLIB_config.h. */
  36 typedef _PDCLIB_fpos_t        fpos_t;
  37 typedef struct _PDCLIB_file_t FILE;
  38 #define EOF -1
  39 #define BUFSIZ _PDCLIB_BUFSIZ
  40 #define FOPEN_MAX _PDCLIB_FOPEN_MAX
  41 #define FILENAME_MAX _PDCLIB_FILENAME_MAX
  42 #define L_tmpnam _PDCLIB_L_tmpnam
  43 #define TMP_MAX _PDCLIB_TMP_MAX
  44
  45 /* See fseek(), third argument */
  46 #define SEEK_CUR 1
  47 #define SEEK_END 2
  48 #define SEEK_SET 4
  49
  50 /* Text-mode I/O is at liberty to skip non-printing characters and trailing spaces.
  51    Binary I/O is at liberty to add trailing zero bytes.
  52    First operation decides "orientation" of the stream (wide / byte).
  53    freopen() removes orientation; see also fwide().
  54    Binary wide-oriented streams have the file-positioning restrictions ascribed to both text and binary streams.
  55    For wide-oriented streams, after a successful call to a file-positioning function that leaves the file position indicator prior to the end-of-file, a wide character output function can overwrite a partial multibyte character; any file contents beyond the byte(s) written are henceforth indeterminate.
  56    Whether a file of zero length (unwritten-to) actually exists is implementation-defined.
  57    Wide text input from file: fgetwc() / mbrtowc()
  58    Wide text output to file: wcrtomb() / fputwc()
  59    Multibyte encoding in file may contain embedded null bytes
  60    Multibyte encoding in file need not begin / end in initial shift state.
  61    Conversion may trigger EILSEQ.
  62 */
  63
  64 /* Operations on files */
  65
  66 /* Remove the given file. Returns zero if successful, non-zero otherwise. If
  67    the file is open, this implementation does flush its buffer and closes the
  68    file before removing it. (It might be still accessible by another hard link
  69    etc.
  70 */
  71 int remove( const char * filename );
  72
  73 /* Rename the given old file to the given new name. Returns zero if successful,
  74    non-zero otherwise. If successful, the file can no longer be accessed under
  75    its old name. If the file is open, this implementation does flush its buffer
  76    and closes the file before renaming it.
  77 */
  78 int rename( const char * old, const char * new );
  79
  80 /* Opens a temporary file with mode "wb+", i.e. binary, update. The file will
  81    be removed when it is closed or the process exits normally. Returns a pointer
  82    to a FILE handle for this file. This implementation does not remove temporary
  83    files if the process aborts abnormally (e.g. abort()).
  84 */
  85 FILE * tmpfile( void );
  86
  87 /* Generates a file name that is not equal to any existing filename AT THE TIME
  88    OF GENERATION. It generates a different name each time it is called. If s is
  89    a NULL pointer, the name is stored in an internal static array, and a pointer
  90    to that array is returned. (This is not thread-safe!) If s is not a NULL
  91    pointer, it is assumed to point to an array of at least L_tmpnam characters.
  92    The generated name is then stored in s, and s is returned. If tmpnam() is
  93    unable to generate a suitable name (because all possible variations do exist
  94    already or the function has been called TMP_MAX times already), NULL is
  95    returned.
  96    Note that this implementation cannot guarantee a file of this name is not
  97    generated between the call to tmpnam() and a subsequent fopen().
  98 */
  99 char * tmpnam( char * s );
 100
 101 /* File access functions */
 102 int fclose( FILE * stream );
 103 int fflush( FILE * stream );
 104 FILE * fopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode );
 105 FILE * freopen( const char * _PDCLIB_restrict filename, const char * _PDCLIB_restrict mode, FILE * _PDCLIB_restrict stream );
 106 void setbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf );
 107 int setvbuf( FILE * _PDCLIB_restrict stream, char * _PDCLIB_restrict buf, int mode, size_t size );
 108
 109 /* Formatted input/output functions */
 110 int fprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 111 int fscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, ... );
 112 int printf( const char * _PDCLIB_restrict format, ... );
 113 int scanf( const char * _PDCLIB_restrict format, ... );
 114 int snprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, ... );
 115 int sprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 116 int sscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, ... );
 117 int vfprintf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 118 int vfscanf( FILE * _PDCLIB_restrict stream, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 119 int vprintf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 120 int vscanf( const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 121 int vsnprintf( char * _PDCLIB_restrict s, size_t n, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 122 int vsprintf( char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 123 int vsscanf( const char * _PDCLIB_restrict s, const char * _PDCLIB_restrict format, _PDCLIB_va_list arg );
 124
 125 /* Character input/output functions */
 126
 127 /* Retrieve the next character from given stream. Returns the character, cast
 128    to int, if successful. If EOF is reached, the EOF indicator of the stream
 129    is set and EOF returned. If a read error occurs, the error indicator of the
 130    stream is set and EOF returned.
 131 */
 132 int fgetc( FILE * stream );
 133
 134 /* Reads at most n-1 characters from given stream into the array s, stopping at
 135    \n or EOF. The string read is terminated with \n. Returns s if successful.
 136    If EOF is encountered before any characters are read, the contents of s are
 137    unchanged, and NULL is returned. If a read error occurs, the contents of s
 138    are indeterminate, and NULL is returned.
 139 */
 140 char * fgets( char * _PDCLIB_restrict s, int n, FILE * _PDCLIB_restrict stream );
 141
 142 /* Write the value c (cast to unsigned char) to the given stream. Returns c if
 143    successful. If a write error occurs, sets the error indicator of the stream
 144    and returns EOF.
 145 */
 146 int fputc( int c, FILE * stream );
 147
 148 fputs( s, stream ) - write s to stream (not including terminating \0). Return >0 if
 149                      successful, EOF on write error. (No mention of err!)
 150
 151 /* Write the string s (not including the terminating \0) to the given stream.
 152    Returns a value >=0 if successful, EOF if a write error occurs. (The
 153    standard does not mention the error indicator; this implementation does set
 154    it in such a case.)
 155 */
 156 int fputs( const char * _PDCLIB_restrict s, FILE * _PDCLIB_restrict stream );
 157
 158 /* Equivalent to fgetc( stream ), but may be implemented as a macro that
 159    evaluates its parameter more than once.
 160 */
 161 #define getc( stream ) fgetc( stream )
 162
 163 /* Equivalent to fgetc( stdin ), but may be implemented as a macro. */
 164 #define getchar() fgetc( stdin )
 165
 166 /* Read characters from given stream into the array s, stopping at \n or EOF.
 167    The string read is terminated with \0. Returns s if successful. If EOF is
 168    encountered before any characters are read, the contents of s are unchanged,
 169    and NULL is returned. If a read error occurs, the contents of s are indeter-
 170    minate, and NULL is returned.
 171 */
 172 char * gets( char * s );
 173
 174 /* Equivalent to fputc( c, stream ), but may be implemented as a macro that
 175    evaluates its parameter more than once.
 176 */
 177 #define putc( c, stream ) fputc( c, stream )
 178
 179 /* Equivalent to fputc( c, stdout ), but may be implemented as a macro that
 180    evaluates its parameter more than once.
 181 */
 182 int putchar( int c );
 183
 184 /* Write the string s (not including the terminating \0) to stdout, and append
 185    a newline to the output. Returns a value >= 0 when successful, EOF if a
 186    write error occurred.
 187 */
 188 int puts( const char * s );
 189
 190 /* Push the value c (cast to unsigned char) back onto the given (input) stream.
 191    A character pushed back in this way will be delivered by subsequent read
 192    operations (and skipped by subsequent file positioning operations) as if it
 193    has not been read. The external representation of the stream is unaffected
 194    by this pushback (it is a buffer operation). One character of pushback is
 195    guaranteed, further pushbacks may fail. EOF as value for c does not change
 196    the input stream and results in failure of the function.
 197    For text files, the file position indicator is indeterminate until all
 198    pushed-back characters are read. For binary files, the file position
 199    indicator is decremented by each successful call of ungetc(). If the file
 200    position indicator for a binary file was zero before the call of ungetc(),
 201    behaviour is undefined. (Older versions of the library allowed such a call.)
 202    Returns the pushed-back character if successful, EOF if it fails.
 203 */
 204 int ungetc( int c, FILE * stream );
 205
 206 /* Direct input/output functions */
 207 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 208 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
 209
 210 /* File positioning functions */
 211 int fgetpos( FILE * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
 212 int fseek( FILE * stream, long int offset, int whence );
 213 int fsetpos( FILE * stream, const fpos_t * pos );
 214 long int ftell( FILE * stream );
 215 void rewind( FILE * stream );
 216
 217 /* Error-handling functions */
 218 void clearerr( FILE * stream );
 219 int feof( FILE * stream );
 220 int ferror( FILE * stream );
 221 void perror( const char * s );
 222
 223 #endif