<tt>int fprintf(FILE *stream, char *format, ...)</tt>

Document: The C Standard Library

next int printf(char *format...)
up Input and Output: stdio.h
gif int putchar(int c)

int fprintf(FILE *stream, char *format, ...)

fprintf() is a "print-and-format" function. It provides for transformation of values of any of the native C data types into a corresponding textual or string form; this whole string is written to the open file identified by the file pointer stream. fprintf() is actually just one of a whole family of functions which provide minor variations on the basic idea of formatted output.

fprintf() takes a variable number of arguments. The arguments stream and format are required - they must always be present and must be of the types specified in the prototype; but these may then be followed by an arbitrary number (including zero!) of further arguments of arbitrary types.

format is a string which indirectly specifies how many further arguments are being passed in (if any) and their types.

More precisely, format contains "ordinary" characters interspersed with "conversion specifications". The ordinary characters are simply written to stream. But each time fprintf() encounters a conversion specification, another input argument is converted into a textual or string form, and output on stream instead.

Thus, to simply print a string on the screen (and assuming that stdout has not been redirected) one might use the function call:

        fprintf(stdout, "Helllooo VietNAM!!!!!!")

Conversion specifications are introduced by the character % . Examples of some simple conversion specifications are as follows:

"%d" Convert an int value to a normal (base 10) textual representation.
"%u" Convert an unsigned int value.
"%ld" Convert a long value.
"%c" "Convert" a char value.
"%s" "Convert" a string value (i.e. the argument should be technically of type (char *) and point at a normal nul-terminated array of characters).

In the last two cases, the argument is already essentially textual, so there is strictly no "conversion" to be done as such.

There are many other more complex conversion specifications, but they will not be detailed here.

Examples of the use of fprintf() might be as follows:

        fprintf(stdout, "The answer is: %d.", 42);

It is important to understand that although the int value 42 appears in textual form in the C statement above, when the program is compiled this is converted into an internal, non-textual, representation. This is why, in order to display this value on the screen again, fprintf() must be used to convert back to a textual representation. In this case the nett effect of this call to fprintf() will be that the string:

        The answer is: 42.
will appear on the screen (assuming stdout has not been redirected). Precisely the same display would, of course, result from the statement:
        fprintf(stdout, "The answer is: %d.", 7 * 6);

Again, the same display would result from the sequence of statements:

        x = 7;
        y = x;
        fprintf(stdout, "The answer is: %d.", (y * x) - 6);
where x and y are int variables. Similarly, if a, b and c are variables of type int, long and char respectively, we might encounter the sequence of statements:
        a = 32000;
        b = 32000L * 32000L;
        c = '!';
        fprintf(stdout, "%d times %d is %ld%c", a, a, b, c);
resulting in the following message on the screen:
        32000 times 32000 is 1024000000!

Note carefully, how the extra arguments in the call to fprintf() must pair off exactly with the conversion specifications in the format argument: i.e. for each conversion specification, in sequence, which appears in the format string, there must be one extra argument, of just the right type. For technical reasons, which will not be explored here, it is not possible for the computer to automatically check that conversion specifications do, in fact, match up with arguments correctly. A mismatch between conversion specifications and arguments in a call to fprintf(), or some related function, is one of the most common kinds of errors encountered in C programs - precisely because the computer cannot automatically detect it. The effects of such errors are completely unpredictable, and may not be immediately apparent at all, so that they can be extremely difficult to track down. You have been warned!

Some trivial examples of such mismatching would be as follows:

        fprintf(stream, "The answer is: %d", 42L);

        fprintf(stream, "Or perhaps it is: %l", 42);

        fprintf(stream, "Or there again, maybe its %d");

        fprintf(stream, "My last offer is: %d", 42, 53);

Note that if you want to move onto a new line on the display screen, you must explicitly write the newline character '\n' to the relevant stream. Try to predict the precise effect of this sequence of statements for example:

        fprintf(stdout, "Hello. ");
        fprintf(stdout, "Hello?");
        fprintf(stdout, "\nIs that you?");
        fprintf(stdout, "Yes?\nNo...\n\nMaybe????\n");
        fprintf(stdout, "My number is:\n%d\nnWhat's yours?", 42);

Note that because the % character in the format string is interpreted in a special way by fprintf() (namely as introducing a conversion specification), there is a problem if one actually wants to just output this character. To get around this you just put in two successive % characters, thus: %% . The second one will cause fprintf() to recognise that this is not a conversion specification after all, and it will simply output one % character without further ado (and without attempting to convert any argument).

The return value from fprintf() is the number of characters which have been written out, or EOF if any error has been detected. C programmers commonly neglect to check this return value from fprintf(), presumably because error conditions which it can detect and signal are rather rare. Nonetheless, as a general practice I would recommend that you include code in your programs to check this return value (at least to see if it is EOF), unless the your usage is extremely trivial (e.g. just printing the format string, without having any extra arguments to be converted).

Document: The C Standard Library

next int printf(char *format...)
up Input and Output: stdio.h
gif int putchar(int c)

Fri Mar 29 14:35:38 GMT 1996