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:

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)

 
libnew/stdio.txt · Last modified: 2016/05/20 03:37 by aralbrec
 
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki