From: solar Date: Mon, 19 Jan 2004 19:36:00 +0000 (+0000) Subject: Partially documented. X-Git-Tag: OLD~8 X-Git-Url: https://pd.if.org/git/?p=pdclib;a=commitdiff_plain;h=b18c386cb4b41de41afdb52de98b46b82f00f0ca Partially documented. --- diff --git a/includes/stdio.h b/includes/stdio.h index e9d323c..6d54496 100644 --- a/includes/stdio.h +++ b/includes/stdio.h @@ -10,58 +10,141 @@ #ifndef __STDIO_H #define __STDIO_H __STDIO_H -// TODO: Documentation, checking macros for personality - // ---------------------------------------------------------------------------- // MACROS #include "__NULL.h" -#define _IOFBF // TODO -#define _IOLBF // TODO -#define _IONBF // TODO -#define BUFSIZ // TODO +#define _IOFBF // integer constant suitable as 3rd argument to setvbuf() +#define _IOLBF // integer constant suitable as 3rd argument to setvbuf() +#define _IONBF // integer constant suitable as 3rd argument to setvbuf() +#define BUFSIZ // integer constant, size of the buffer used by setbuf(), + // >= 256 #define EOF // TODO -#define FILENAME_MAX // TODO -#define FOPEN_MAX // TODO -#define L_tmpnam // TODO -#define SEEK_CUR // TODO -#define SEEK_END // TODO -#define SEEK_SET // TODO -#define TMP_MAX // TODO - -#define stderr // TODO -#define stdin // TODO -#define stdout // TODO +#define FILENAME_MAX // length of filenames supported +#define FOPEN_MAX // number of simultaneous open files supported, >= 8 +#define L_tmpnam // length of filenames generated by tmpnam() +#define SEEK_CUR // integer constant suitable as 3rd argument to fseek() +#define SEEK_END // integer constant suitable as 3rd argument to fseek() +#define SEEK_SET // integer constant suitable as 3rd argument to fseek() +#define TMP_MAX // number of unique filenames generateable by tmpnam(), + // >= 25 + +#define stderr // FILE*, not fully buffered +#define stdin // FILE*, fully buffered only when not interactive device +#define stdout // FILE*, fully buffered only when not interactive device // ---------------------------------------------------------------------------- // TYPEDEFS #include "__size_t.h" -typedef FILE; // TODO - personality? -typedef fpos_t; // TODO - personality? -typedef size_t; // TODO - personality? +typedef FILE; // object holding all stream information, including file pos, + // buffer (optional), error indicator, EOF indicator +typedef fpos_t; // position indicator type, other than array - personality? + // (see mbstate_t) // ---------------------------------------------------------------------------- // FUNCTIONS -// TODO: Documentation. +/** CLEAR ERRor. Clears EOF and error indicator of a FILE handle. + @param fh The file handle. + */ +void clearerr( FILE * fh ); + +/** File CLOSE. Flush output buffers (if any) and closes the FILE handle. + @param stream The file handle. + @return 0 if successful, non-zero if failed. (In any case, the FILE handle + is invalid afterwards.) + */ +int fclose( FILE * fh ); -void clearerr( FILE * stream ); -int fclose( FILE * stream ); int feof( FILE * stream ); int ferror( FILE * stream ); -int fflush( FILE * stream ); + +/** File FLUSH. Flushes output buffers (if any) for given file handle. If + parameter is NULL, flushes output buffers for all file handles. + @param fh The file handle. + @return 0 if successful, EOF if failed (setting error indicators). + */ +int fflush( FILE * fh ); + +/** File OPEN. Opens the file specified by the given name. + @param filename Name of the file to be opened. + @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+, + specifying which mode to open the file in. + @return A file handle associated with the opened file, NULL if failed. + */ FILE * fopen( const char * restrict filename, const char * restrict mode ); -FILE * freopen( const char * restrict filename, const char * restrict mode, FILE * stream ); + +/** File REOPEN. Opens the file specified by the given name, associating it + with the given file handle. If filename is NULL, it is attempted to change + the mode of the already opened file associated with the given file handle. + (This function can e.g. be used to reassociate stdin / stdout / stderr with + a filename.) + @param filename Name of the file to be opened. + @param mode One of r, w, a, rb, wb, ab, r+, w+, a+, rb+, wb+, ab+, + specifying which mode to open the file in. + @param fh The file handle to associate with the opened file. + @return fh if successful, NULL if failed. + */ +FILE * freopen( const char * restrict filename, const char * restrict mode, FILE * fh ); + +/** REMOVE file. Causes a file to be no longer accessible under a given name. + If the file is currently open, this implementation of remove() fails, + returning INT_MAX. + @param filename Name of the file to be removed. + @return 0 if successful, non-zero if failed. (Implementation defined: + INT_MAX if the file is currently open.) + */ int remove( const char * filename ); + +/** RENAME file. Causes a file to be no longer accessible under a given name, + but a new name instead. If a file with the intended new name already + exists, this implementation of rename() fails, returning INT_MAX. + @param old Name of the file to be renamed. + @param new Name to rename the file to. + @return 0 if successful, non-zero if failed. (Implementation defined: + INT_MAX if target file name already exists.) + */ int rename( const char * old, const char * new ); + void rewind( FILE * stream ); -void setbuf( FILE * restrict stream, char * restrict buf ); -int setvbuf( FILE * restrict stream, char * restrict buf, int mode, size_t size ); + +/** SET Virtual BUFfer. Sets buffering mode and (optionally) the memory used + for buffering, for a given file handle. + This function must only be called immediately after associating the file + handle with a file, before any operations are called on the file handle. + @param fh The file handle. + @param buf A pointer to the memory area to use for buffering, or NULL to + use internally assigned buffer memory. + @param mode One of _IOFBF, _IOLBF, _IONBF. + @param size Size of the memory area to be used for buffering. + */ +int setvbuf( FILE * restrict fh, char * restrict buf, int mode, size_t size ); + +/** SET BUFfer. Equivalent to (void) setvbuf( fh, buf, _IOFBF, BUFSIZ ), or + (void) setvbuf( fh, NULL, _IONBF, BUFSIZ ) if buf == NULL. + @param fh The file handle to be passed to setvbuf(). + @param buf The buffer pointer to be passed to setvbuf(). + */ +void setbuf( FILE * restrict fh, char * restrict buf ); + +/** TeMPorary FILE. Opens a file in "wb+" mode that will be automatically + deleted when closed, or when the program terminates. + @return A file handle for the temporary file. (NULL if opening failed.) + */ FILE * tmpfile( void ) -char * tmpnam( char * s ); + +/** TeMPorary NAMe. Generates a random file name that does not yet exist in the + file system. Note that a file generated with this name is not "temporary", + and must be remove()d normally. + @param dest NULL, or a char[ L_tmpnam ] array. + @return A pointer to a static internal buffer containing the file name, + or NULL if no file name could be generated. If 'dest' is not NULL, + writes the file name to and returns 'dest'. + */ +char * tmpnam( char * dest ); int fseek( FILE * stream, long offset, int mode ); int fsetpos( FILE * stream, const fpos_t * pos ); @@ -84,20 +167,133 @@ int putc( int c, FILE * stream ); int putchar( int c ); int puts( const char * s ); -int fscanf( FILE * restrict stream, const char * restrict format, ... ); +/** File SCAN Formatted. Reads from given file handle, under control of a + formatting string, the values of variables pointed to by 0..n pointers. + @param fh The file handle. + @param format The formatting string. + @param ... A list of 0..n pointers corresponding to placeholders in + 'format'. + @return EOF if failed, number of values successfully assigned otherwise. + */ +int fscanf( FILE * restrict fh, const char * restrict format, ... ); + +/** SCAN Formatted. Equivalent to fscanf( stdin, format, ... ) + @param format The formatting string. + @param ... A list of 0..n pointers corresponding to placeholders in + 'format'. + @return EOF if failed, number of values successfully assigned otherwise. + */ int scanf( const char * restrict format, ... ); -int sscanf( const char * restrict s, const char * restrict format, ... ); -int vfscanf( FILE * restrict stream, const char * restrict format, va_list ap ); -int vscanf( const char * restrict format, va_list ap ); -int vsscanf( const char * restrict s, const char * restrict format, va_list ap ); +/** String SCAN Formatted. Equivalent to scanf( format, ... ), but using a C + string instead of a file handle for input. + @param src The input string. + @param format The formatting string. + @param ... A list of 0..n pointers corresponding to placeholders in + 'format'. + @return EOF if failed, number of values successfully assigned otherwise. + */ +int sscanf( const char * restrict src, const char * restrict format, ... ); + +/** Variable File SCAN Formatted. Equivalent to fscanf( fh, format, ... ), + with the variable-length parameter list replaced by a va_list, created by + the va_start macro. + @param fh The file handle. + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vfscanf( FILE * restrict stream, const char * restrict format, va_list args ); + +/** Variable SCAN Formatted. Equivalent to vfscanf( stdin, format, args ). + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vscanf( const char * restrict format, va_list args ); + +/** Variable String SCAN Formatted. Equivalent to vscanf( format, args ), but + reading from a C string instead of stdin. + @param src The C string to read from. + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vsscanf( const char * restrict src, const char * restrict format, va_list ap ); + +/** File PRINT Formatted. Prints to given file handle, under control of a + formatting string, the values of 0..n variables. + @param fh The file handle. + @param format The formatting string. + @param ... A list of 0..n variables corresponding to placeholders in + 'format'. + @return Number of characters printed, negative value if error occurred. + */ int fprintf( FILE * restrict stream, const char * restrict format, ... ); + +/** PRINT Formatted. Equivalent to fprintf( stdout, format, ... ). + @param format The formatting string. + @param ... A list of 0..n variables corresponding to placeholders in + 'format'. + @return Number of characters printed. + */ int printf( const char * restrict format, ... ); + +/** String N PRINT Formatted. Equivalent to sprintf( dest, format, ... ), but + will not write more than n characters. + @param dest The char array to write to. + @param n The maximum number of characters to write. + @param format The formatting string. + @param ... A list of 0..n variables corresponding to placeholders in + 'format'. + @return Number of characters printed. + */ int snprintf( char * restrict s, size_t n, const char * restrict format, ... ); -int sprintf( char * restrict s, const char * restrict format, ... ); -int vfprintf( FILE * restrict stream, const char * restrict format, va_list ap ); -int vprintf( const char * restrict format, va_list ap ); -int vsnprintf( char * restrict s, size_t n, const char * restrict format, va_list ap ); + +/** String PRINT Formatted. Equivalent to printf( format, ... ), but writing + to a char array instead of stdout. + @param dest The char array to write to. + @param format The formatting string. + @param ... A list of 0..n variables corresponding to placeholders in + 'format'. + @return Number of characters printed. + */ +int sprintf( char * restrict dest, const char * restrict format, ... ); + +/** Variable File PRINT Formatted. Equivalent to fprintf( fh, format, ... ), + with the variable-length parameter list replaced by a va_list, created by + the va_start macro. + @param fh The file handle. + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vfprintf( FILE * restrict fh, const char * restrict format, va_list args ); + +/** Variable PRINT Formatted. Equivalent to vfprintf( stdout, format, args ). + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vprintf( const char * restrict format, va_list args ); + +/** Variable String N PRINT Formatted. Equivalent to vsprintf( dest, format, + args ), but will not write more than n characters. + @param dest The char array to write to. + @param n Maximum number of characters to write. + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ +int vsnprintf( char * restrict dest, size_t n, const char * restrict format, va_list ap ); + +/** Variable String PRINT Formatted. Equivalent to vprintf( format, args ), but + writing to a char array instead to stdout. + @param dest The char array to write to. + @param format The formatting string. + @param args The argument list created by the va_start macro. + @return Number of characters printed. + */ int vsprintf( char * restrict s, const char * restrict format, va_list ap); /* PDPC code - unreviewed