3 /* Input/output <stdio.h>
5 This file is part of the Public Domain C Library (PDCLib).
6 Permission is granted to use, modify, and / or redistribute at will.
9 #ifndef _PDCLIB_STDIO_H
10 #define _PDCLIB_STDIO_H _PDCLIB_STDIO_H
13 #define _PDCLIB_INT_H _PDCLIB_INT_H
14 #include <_PDCLIB_int.h>
17 #ifndef _PDCLIB_SIZE_T_DEFINED
18 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
19 typedef _PDCLIB_size_t size_t;
22 #ifndef _PDCLIB_NULL_DEFINED
23 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
24 #define NULL _PDCLIB_NULL
27 /* See setvbuf(), third argument */
28 /* Fully buffered - transmit block-wise */
30 /* Line buffered - transmit line-wise */
32 /* Not buffered - transmit immediately */
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;
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
45 /* See fseek(), third argument */
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.
64 /* Operations on files */
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
71 int remove( const char * filename );
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.
78 int rename( const char * old, const char * new );
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()).
85 FILE * tmpfile( void );
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
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().
99 char * tmpnam( char * s );
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 );
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 );
125 /* Character input/output functions */
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.
132 int fgetc( FILE * stream );
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.
140 char * fgets( char * _PDCLIB_restrict s, int n, FILE * _PDCLIB_restrict stream );
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
146 int fputc( int c, FILE * stream );
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!)
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
156 int fputs( const char * _PDCLIB_restrict s, FILE * _PDCLIB_restrict stream );
158 /* Equivalent to fgetc( stream ), but may be implemented as a macro that
159 evaluates its parameter more than once.
161 #define getc( stream ) fgetc( stream )
163 /* Equivalent to fgetc( stdin ), but may be implemented as a macro. */
164 #define getchar() fgetc( stdin )
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.
172 char * gets( char * s );
174 /* Equivalent to fputc( c, stream ), but may be implemented as a macro that
175 evaluates its parameter more than once.
177 #define putc( c, stream ) fputc( c, stream )
179 /* Equivalent to fputc( c, stdout ), but may be implemented as a macro that
180 evaluates its parameter more than once.
182 int putchar( int c );
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.
188 int puts( const char * s );
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.
204 int ungetc( int c, FILE * stream );
206 /* Direct input/output functions */
208 /* Read up to nmemb elements of given size from given stream into the buffer
209 pointed to by ptr. Returns the number of elements successfully read, which
210 may be less than nmemb if a read error or EOF is encountered. If a read
211 error is encountered, the value of the file position indicator is
212 indeterminate. If a partial element is read, its value is indeterminate.
213 If size or nmemb are zero, the function does nothing and returns zero.
215 size_t fread( void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
217 /* Write up to nmemb elements of given size from buffer pointed to by ptr to
218 the given stream. Returns the number of elements successfully written, which
219 will be less than nmemb only if a write error is encountered. If a write
220 error is encountered, the value of the file position indicator is
221 indeterminate. If size or nmemb are zero, the function does nothing and
224 size_t fwrite( const void * _PDCLIB_restrict ptr, size_t size, size_t nmemb, FILE * _PDCLIB_restrict stream );
226 /* File positioning functions */
227 int fgetpos( FILE * _PDCLIB_restrict stream, fpos_t * _PDCLIB_restrict pos );
228 int fseek( FILE * stream, long int offset, int whence );
229 int fsetpos( FILE * stream, const fpos_t * pos );
230 long int ftell( FILE * stream );
231 void rewind( FILE * stream );
233 /* Error-handling functions */
234 void clearerr( FILE * stream );
235 int feof( FILE * stream );
236 int ferror( FILE * stream );
237 void perror( const char * s );