Table of Contents
STDIO.H
| Include | #include <stdio.h> |
|---|---|
| Header | {z88dk}/include/_DEVELOPMENT/sccz80/stdio.h |
| {z88dk}/include/_DEVELOPMENT/sdcc/stdio.h | |
| Source | {z88dk}/libsrc/_DEVELOPMENT/stdio |
All functions are re-entrant.
Some text taken from these references:
- The C Programming Language, 2nd Editon (Kernighan and Ritchie)
OPERATIONS ON FILES
Not available until disk i/o is added.
FILE ACCESS
Open and close are present but not complete until disk i/o is added.
int fclose(FILE *stream)
int fflush(FILE *stream)
FILE *fopen(const char *filename, const char *mode)
FILE *freopen(const char *filename, const char *mode, FILE *stream)
MEMORY STREAMS
FILE *_fmemopen_(char **bufp, size_t *sizep, const char *mode)
FILE *fmemopen(void *buf, size_t size, const char *mode)
FILE *open_memstream(char **bufp, size_t *sizep)
FILE DESCRIPTORS
FILE *fdopen(int fd, const char *mode)
Associate a stream with the low-level file descriptor. Closing the returned FILE will also close the underlying fd.
mode is a character string indicating how the file will be used. Its meaning is exactly as specified in fopen() except that modes containing “w” will not cause file truncation.
If an error occurs, 0 will be returned with the carry flag set and errno will be set to one of:
- [EBADF] fd is out of range or there is no open file with descriptor fd
- [EINVAL] the mode string is not understood or the underlying fd does not support the mode
- [ENOMEM] insufficient memory to create a new FILE struct
int fileno(FILE *stream)
Return the integer file descriptor associated with stream.
If an error occurs, -1 will be returned with the carry flag set and errno will be set to one of:
- [EBADF] stream is not valid
FORMATTED INPUT
int fscanf(FILE *stream, const char *format, ...)
Reads from stream under the control of the format string and assigns converted values to subsequent arguments, each of which must be a pointer. It returns when format is exhausted or an error occurs. fscanf returns -1 if no characters could be read from the stream. Otherwise it returns the number of conversions performed and assigned.
The format string usually contains conversion specifications which are used to direct interpretation of input. The format string may contain:
- Blanks, tabs or other whitespace which cause any leading whitespace to be consumed from stream
- Ordinary characters (not %) which are expected to match the subsequent characters read from stream
- Conversion specifications consisting of a %, an optional assignment suppression character *, an optional number indicating a maximum field width (>0), an optional length modifier, and a conversion character.
A conversion specification determines how the next bytes on the stream are interpreted. Normally the result is placed in the variable pointed to by the next argument in the argument list. If assignment suppression is indicated by *, as in %*s, the input field is read from the stream but no assignment is made. An input field is defined as a string of non-whitespace characters; it extends until the next whitespace character or until the field width, if specified, is exhausted. This implies that scanf will read across line boundaries to find its input since newlines are considered whitespace.
The following length modifiers are accepted: hh, h, l, ll, j, z, t, L but only “l” has meaning for converters “Bdinopux” and (sdcc only) “ll” for converters “dioux”.
The conversion character indicates how the input field is interpreted. The conversion characters are listed below:
| CHARACTER | STREAM CHARACTERS | ASSIGNED TO |
|---|---|---|
| B | binary number | uint16_t * |
| c | characters 4 | char * |
| d | decimal number | int16_t * |
| i | number 1 | int16_t * |
| I | IPv4 Address in dotted form 1 | uint32_t * |
| n | (no stream chars) number of chars read thus far | uint16_t * |
| o | octal number 2 | uint16_t * |
| p | pointer | void * * |
| s | characters 8 | char * |
| [..] | characters 5 | char * |
| [^..] | characters 6 | char * |
| u | unsigned decimal number | uint16_t * |
| x | hexadecimal number 3 | uint16_t * |
| lB | binary number | uint32_t * |
| ld | decimal number | int32_t * |
| li | number 1 | int32_t * |
| ln | (no stream chars) number of chars read thus far | uint32_t * |
| lo | octal number 2 | uint32_t * |
| lp | pointer | uint32_t * |
| lu | unsigned decimal number | uint32_t * |
| lx | hexadecimal number 3 | uint32_t * |
| lld | decimal number | int64_t * |
| lli | number 1 | int64_t * |
| llo | octal number 2 | uint64_t * |
| llu | unsigned decimal number | uint64_t * |
| llx | hexadecimal number 3 | uint64_t * |
| % | match % from stream | no assignment made |
1 may be in octal (leading 0), decimal or hexadecimal (leading 0x)
2 with or without leading 0
3 with or without leading 0x
4 chars are written to the array up to the width (default=1) specified, whitespace is not skipped
5 matches longest non-empty string of chars from stream in the set, terminating '\0' is added
6 matches longest non-empty string of chars from stream not in the set, terminating '\0' is added
8 leading whitespace is skipped then characters are read until the next whitespace char
NOTE: Some or all of these converters may be disabled by the target's library config file. Floating point converters “aefg” have not been added yet but string to float conversion can also be done with strtod and atof. One method to read floats would be to first scan them as a string using %[ and then using one of the aforementioned functions to convert the string to a float.
If an error occurs, the carry flag is set and errno will be set to:
- [EACCES] the stream is not open for input or the stream is in an error state
- [EINVAL] unknown conversion specifier or error during stream conversion
- [ERANGE] width out of range
The device driver may set other errors. errno is not set if there is a character mismatch with the format string.
int scanf(const char *format, ...)
int sscanf(const char *s, const char *format, ...)
int vfscanf(FILE *stream, const char *format, va_list arg)
int vscanf(const char *format, va_list arg)
int vsscanf(const char *s, const char *format, va_list arg)
FORMATTED OUTPUT
int asprintf(char **ptr, const char *format, ...)
int fprintf(FILE *stream, const char *format, ...)
Writes formatted output to stream under the control of the format string using data from arguments following format. Returns the number of characters written or -1 if an error occurs.
The format string contains two types of objects: ordinary characters, which are copied to the output stream, and conversion specifiers, each of which causes the next argument of fprintf to be output to the stream in the manner specified. Each conversion specifier begins with % and ends with a conversion character. Between the % and the conversion character there may be optional modifiers, in order:
- flags (any order) which modify the conversion:
- -, specifies that the result of the conversion be left justified within the field; the default is right justification
- +, specifies that a number will always be printed with a leading sign (+-); by default only a minus sign is printed if the number is negative
- space, specifies that a positive number be prefixed with a space; this overrides the '+' flag
- 0, for numbers causes the left side of the field to be padded with leading zeroes. If the '0' and '-' flags both appear, '0' is ignored. For the converters bdiouxX, if a precision is specified, '0' is ignored.
- #, the result is converted to an “alternative form”. For o conversion, it increases the precision, if and only if necessary, to force the first digit of the result to be a zero (if the value and precision are both 0, a single 0 is printed). For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g, and G conversions, the result of converting a floating-point number always contains a decimal-point character, even if no digits follow it, and trailing zeros are not removed from the result.
- a minimum field width. If the converted value has fewer characters than the field width, it is padded with spaces (by default) on the left (or right, if the '-' flag is present) to the field width. The field width can be either an unsigned decimal integer with max value 32767 or a '*' (below).
- a precision that gives the minimum number of digits to appear for the B, d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point character for a, A, e, E, f, and F conversions, the maximum number of significant digits for the g and G conversions, or the maximum number of bytes to be written for s conversions. The precision takes the form of a period (.) followed either by a '*' (below) or an unsigned decimal integer with max value 32767; if only the period is specified, the precision is taken as zero.
If the width or precision is '*', their value is taken from an int argument in the parameter list. A negative field width argument is taken as a '-' flag followed by a positive field width. A negative precision argument is taken as if the precision were omitted.
- a length modifier. hh, h, l, ll, j, z, t, L are all accepted but only 'l' has meaning for converters “BdiouxX” and (sdcc only) 'll' has meaning for “diouxX”.
Finally, the conversion characters and their meanings are shown below. If the character after % is not listed below, EINVAL is returned.
| CHARACTER | ARGUMENT TYPE | CONVERTED TO |
|---|---|---|
| B | uint16_t | unsigned binary |
| c | char | single character |
| d,i | int16_t | signed decimal |
| I | uint32_t | IPv4 address in dotted decimal form |
| n | uint16_t * | number of characters output so far is written into the argument |
| o | int16_t | unsigned octal |
| p,P | void * | pointer, P uses capitals |
| s | char * | string of characters up to \0 or until precision exhausted |
| u | uint16_t | unsigned decimal |
| x,X | uint16_t | unsigned hexadecimal, X uses capitals |
| lB | uint32_t | unsigned binary |
| ld,li | int32_t | signed decimal |
| lo | uint32_t | unsigned octal |
| lu | uint32_t | unsigned decimal |
| lx,lX | uint32_t | unsigned hexadecimal, X uses capitals |
| lp,lP | uint32_t | pointer, P uses capitals |
| lld,lli | int64_t | signed decimal |
| llo | uint64_t | unsigned octal |
| llu | uint64_t | unsigned decimal |
| llx,llX | uint64_t | unsigned hexadecimal, X uses capitals |
| a,A | double/float | double in hex format +-h.hhhp+-d |
| e,E | double/float | double in exp format +-d.ddde+-d |
| f,F | double/float | double in format +-ddd.ddd |
| g,G | double/float | chooses either e or f for best looking result |
| % | none | output a % |
NOTE: Some or all of these converters may be disabled by the target's library config file. Float to text conversion can also be performed by dtoa and family.
If an error occurs, -(# chars output + 1) is returned with the carry flag set and errno set to:
- [EACCES] the stream is not open for output, the stream is in an error state
- [ERANGE] width or precision is out of range
- [EINVAL] unknown converter
The underlying device driver may set errno to other values.
int obstack_printf(struct obstack *ob, const char *format, ...)
int obstack_vprintf(struct obstack *ob, const char *format, va_list arg)
int printf(const char *format, ...)
int snprintf(char *s, size_t n, const char *format, ...)
int sprintf(char *s, const char *format, ...)
int vasprintf(char **ptr, const char *format, va_list arg)
int vfprintf(FILE *stream, const char *format, va_list arg)
int vprintf(const char *format, va_list arg)
int vsnprintf(char *s, size_t n, const char *format, va_list arg)
int vsprintf(char *s, const char *format, va_list arg)
CHARACTER INPUT
int fgetc(FILE *stream)
char *fgets(char *s, int n, FILE *stream)
int getc(FILE *stream)
int getchar(void)
ssize_t getdelim(char **lineptr, size_t *n, int delimiter, FILE *stream)
ssize_t getline(char **lineptr, size_t *n, FILE *stream)
int ungetc(int c, FILE *stream)
CHARACTER OUTPUT
int fputc(int c, FILE *stream)
int fputs(const char *s, FILE *stream)
int putc(int c, FILE *stream)
int putchar(int c)
int puts(const char *s)
DIRECT INPUT AND OUTPUT
size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream)
size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream)
FILE POSITIONING
int fgetpos(FILE *stream, fpos_t *pos)
int fseek(FILE *stream, long int offset, int whence)
int fsetpos(FILE *stream, const fpos_t *pos)
long ftell(FILE *stream)
void rewind(FILE *stream)
FILE LOCKING
void flockfile(FILE *stream)
int ftrylockfile(FILE *stream)
void funlockfile(FILE *stream)
ERROR HANDLING
void clearerr(FILE *stream)
int feof(FILE *stream)
int ferror(FILE *stream)
void perror(const char *s)
Page Tools
