APPENDIX D
Input and Output Format Specifications
This appendix summarizes all the format specifications you have available for stream input and output. You use these with the standard streams stdin, stdout, and stderr, as well as text file streams.
Output Format Specifications
There are three standard library functions for formatted output: the printf() that writes to the standard output stream stdout (which by default is the command line), the sprintf() function that writes to a string, and the fprintf() function that writes to a file. These functions have the following form:
int printf(const char* format_string, . . .);
int sprintf(char* source_string, const char* format_string, . . .);
int fprintf(FILE* file_stream, const char* format_string, . . .);
The ellipsis at the end of the parameter list indicates that there can be zero or more arguments supplied. These functions return the number of bytes written, or a negative value if an error occurs. The format string can contain ordinary characters (including escape sequences) that are written to the output, together with format specifications for outputting the values of succeeding arguments.
An output format specification always begins with a % character and has the following general form:
%[flags][width][.precision][size_flag]type
The items between square brackets are all optional, so the only mandatory bits are the % character at the beginning and the type specifier for the type of conversion to be used.
The significance of each of the optional parts is as follows:
[flags] are zero or more conversion flags that control how the output is presented. The flags you can use are shown in Table D-1.
[width] specifies the minimum field width for the output value. The width you specify will be exceeded if the value does not fit within the specified minimum width. For example, %15u outputs an unsigned integer value right-justified in a field width of 15 characters padded to the left with spaces as necessary.
[.precision] specifies the number of places following the decimal point in the output for a floating-point value. For example, %15.6f outputs a floating-point value in a minimum field width of 15 characters with four places after the decimal point.
[size_flag] is a size specification for the value that modifies the meaning of the type specification. Possible size specifications are l (lowercase L), L, ll (two lowercase L's), or h. The size specification you can use in any given situation depends on the type specification you are using, as shown in Table D-2.
type is a character specifying the type of conversion to be applied to the value to be output, as shown in Table D-2.
Table D-2. Conversion Type and Size Specifications
Input Format Specifications
For the scanf() function that reads data from the standard input stream, stdin (which by default is the keyboard), the sscanf() function that reads data from a string in memory, and the fscanf() function that reads data from a file, data is read from the source controlled by a format string that is passed as an argument to the function. These input functions have the following form:
int scanf(const char* format_string, pArg1, ...);
int sscanf(const char* destination_string, const char* format_string, ...);
int fscanf(FILE* file_stream, const char* format_string, ...);
Each of these functions returns a count of the number of data items read by the operation. The ellipsis at the end of the parameter list indicates that there can be zero or more arguments here. Don't forget, the arguments that follow the format string must always be pointers. It is a common error to use a variable that is not a pointer as an argument to one of these input functions.
The format string controlling how the input is processed can contain spaces, other characters, and format specifications, beginning with a % character, for data items.
A single whitespace character in the format string causes the function to ignore successive whitespace characters in the input. The first nonwhitespace character found will be interpreted as the first character of the next data item. When a newline character in the input follows a value that has been read, for example, when you are reading a single character from the keyboard using the %c format specification, any newline, tab, or space character that is entered will be read as the input character. This will be particularly apparent when you are reading a single character repeatedly, where the newline from the Enter key will be left in the buffer. If you want the function to ignore the whitespace in such situations, you can force the function to skip whitespace by including at least one whitespace character preceding the %c in the format string.
You can also include nonwhitespace characters in the input format string that are not part of a format specification. Any nonwhitespace character in the format string that is not part of a format specification must be matched by the same character in the input, otherwise the input operation ends.
The format specification for an item of data is of the following form:
%[*][width][size_flag]type
The items enclosed between square brackets are optional. The mandatory parts of the format specification are the % character marking the start of the format specification and the type conversion type specification at the end. The meanings of the optional parts are as follows:
[*] indicates that that the input data item corresponding to this format specification should be scanned but not stored. For example, %*d will scan an integer value and discard it.
[width] specifies the maximum number of characters to be scanned for this input value. If a whitespace character is found before width characters have been scanned, it is the end of the input for the current data item. For example, %2d reads up to two characters as an integer value. The width specification is useful for reading multiple inputs that are not separated by whitespace characters. You could read 12131415 and interpret it as the values 12, 13, 14, and 15 by using "%2d%2d%2d%2d" as the format string.
[size_flag] modifies the input type specified by the type part of the specification. Possible size_flag specifications include h, l, (lowercase L), ll (lowercase L's), and L. Which of these you can use depends on the type specifier you are using, as described in Table D-3.
Table D-3. Input Conversion Type Specifications and Modifiers
Note that if you want to read a string that includes whitespace characters, you have the %[set_of_characters] form of specification available. With this specification, successive characters are read from the input source as long as they appear in the set you supply between the square brackets. Thus, the specification %[ abcdefghijklmnopqrstuvwxyz] will read any sequence of lowercase letters and spaces as a single string. A more useful variation on this is to precede the set of characters with a caret, ^, as in %[^set_of_characters], in which case the set of characters represents the characters that will be interpreted as ending the string input. For example, the specification %[^,!] will read a sequence of characters until either a comma or an exclamation point is found, which will end the string input.