Write text in specified format to stream

[Classification]

Standard library

[Syntax]

#include <stdio.h>

int vfprintf(FILE *stream, const char *format, va_list arg);

[Return value]

The number of characters that were output is returned.

[Description]

This function applies the format specified by the string pointed to by format to argument string pointed to by arg, and outputs the formatted data that was output as a result to stream. Only the standard input/output stdout or stderr can be specified for stream. The method of specifying format is the same as described for the sprintf function. The vfprintf function is equivalent to sprintf with the list of a variable number of real arguments replaced by arg. arg must be initialized by the va_start macro before the vfprintf function is called.

[Caution]

Stdout (standard output) and stderr (standard error) are specified for the argument stream. 1 memory addresses such as an I/O address is allocated for the I/O destination of stream. To use these streams in combination with a debugger, the initial values of the stream structure defined in stdio.h must be set. Be sure to set the initial values prior to calling the function.

[Definition of stream structure in stdio.h]

typedef struct {

        int         mode;   /*with error descriptions*/

        unsigend    handle;

        int         unget_c;

} FILE;

typedef int     fpos_t;

extern  FILE*   _REL_stdin();

extern  FILE*   _REL_stdout();

extern  FILE*   _REL_stderr();

#define stdin   (_REL_stdin())

#define stdout  (_REL_stdout())

#define stderr  (_REL_stderr())

The first structure member, mode, indicates the I/O status and is internally defined as ACCSD_OUT/ADDSD_IN. The third member, unget_c, indicates the pushed-back character (stdin only) setting and is internally defined as -1.

When the definition is -1, it indicates that there is no pushed-back character. The second member, handle, indicates the I/O address. Set the value according to the debugger to be used.

[I/O address setting]

stdout->handle = 0xfffff000;

stderr->handle = 0x00fff000;

stdin->handle  = 0xfffff002;

[Example]

#include    <stdio.h>

void func(int val) {

        fprintf(stdout, "%-10.5x\n", val);

}

/*example using vfprintf in a general error reporting routine*/

void error(char *function_name, char *format, ...) {

        va_list arg;

        va_start(arg, format);

        fprintf(stderr, "ERROR in %s:", function_name); /*output function name for 

                                                          which error occurred*/

        vfprintf(stderr, format, arg);                  /*output remaining messages*/

        va_end(arg);

}