Dependencies on low‑level functions

The printf family consists of _printf(), printf(), _fprintf(), fprintf(), vprintf(), and vfprintf(). All these functions use __FILE opaquely and depend only on the functions fputc() and ferror(). The functions _printf() and _fprintf() are identical to printf() and fprintf() except that they cannot format floating‑point values.

The standard output functions of the form _printf(...) are equivalent to:

fprintf(& __stdout, ...)

where __stdout has type __FILE.

The scanf() family consists of scanf() and fscanf(). These functions depend only on the functions fgetc(), __FILE, and __backspace(). See Re‑implementing __backspace().

The standard input function of the form scanf(...) is equivalent to:

fscanf(& __stdin, ...)

where __stdin has type __FILE.

If you define your own version of __FILE, and your own fputc() and ferror() functions and the __stdout object, you can use all of the printf() family, fwrite(), fputs(), puts() and the C++ object std::cout unchanged from the library. Example 2.24 shows how to do this. Consider modifying the system routines if you require real file handling.

#include <stdio.h>
struct __FILE
{
    int handle;
    /* Whatever you need here (if the only file you are using
       is the stdoutput using printf for debugging, no file
       handling is required) */
};

FILE __stdout;
int fputc(int ch, FILE *f)
{
    /* Your implementation of fputc */
    return ch;
}
int ferror(FILE *f)
{
    /* Your implementation of ferror */
    return EOF;
}
void test(void)
{
    printf("Hello world\n");  /* This works ... */
}

By default, fread() and fwrite() call fast block input/output functions that are part of the ARM stream implementation. If you define your own __FILE structure instead of using the ARM stream implementation, fread() and fwrite() call fgetc() instead of calling the block input/output functions.

The functions fread(), fgets(), and gets() are implemented as a loop over fgetc() and ferror(). Each uses the FILE argument opaquely.

If you provide your own implementation of __FILE, __stdin (for gets()), fgetc(), and ferror(), you can use these functions, and the C++ object std::cin directly from the library.

The function __backspace() is used by the scanf family of functions. It must never be called directly, but re‑implemented if you are retargeting the stdio arrangements at the fgetc() level.

The semantics are:

int __backspace(FILE *stream);

__backspace(stream) must be called after reading a character from the stream. It returns to the stream the last character that was read from the stream, so that the same character is read from the stream again. This means that a character that was read from the stream by scanf but which is not required (that is, it terminates the scanf operation) is read correctly by the next function that reads from the stream.

__backspace is separate from ungetc(). This is to guarantee that a single character can be pushed back after the scanf family of functions has finished.

The value returned by __backspace() is either 0 (success) or EOF (failure). It returns EOF only if used incorrectly, for example, if no characters have been read from the stream. When used correctly, __backspace() must always return 0, because the scanf family of functions do not check the error return.

The interaction between __backspace() and ungetc() is: