There are 16 standard library functions for formatted output that have the following prototypes:
int printf(const char* restrict format, ...); int printf_s(const char* restrict format, ...); int sprintf(char* restrict str, const char* restrict format,...); int sprintf_s(char* restrict str, rsize_t n, const char* restrict format, ...); int snprintf(char * restrict, size_t, const char * restrict, ...); int snprintf_s(char* restrict str, rsize_t n, const char* restrict format, ...); int fprintf(FILE* restrict stream, const char* restrict format, ...); int fprintf_s(FILE* restrict stream, const char* restrict format, ...); int vfprintf(FILE * restrict, const char * restrict, va_list); int vsprintf(char * restrict, const char * restrict, va_list); int vprintf(const char * restrict, va_list); int vsnprintf(char * restrict, size_t, const char * restrict, va_list); int vfprintf_s(FILE * restrict, const char * restrict, va_list); int vprintf_s(const char * restrict, va_list); int vsnprintf_s(char * restrict, rsize_t, const char * restrict, va_list); int vsprintf_s(char * restrict, rsize_t, const char * restrict, va_list);
The functions with names ending _s are optional and require that __STDC_WANT_LIB_EXT1__ be defined as 1.
The ellipsis 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 occurred.
The format string can contain ordinary characters 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 inside square brackets are all optional.
The only mandatory bits are the % character.
The possible choices for each of the optional parts are as follows:
[flags] are zero or more conversion flags that control how the output is presented.
The flags you can use are:
| Sign | Meaning |
|---|---|
| + | Include the sign in the output, + or -. For example, %+d will output a decimal integer with the sign always included. |
| space | Use space or - for the sign (i.e., a positive value is preceded by a space). It is useful for aligning output when there may be positive and negative values in a column of output. For example, % d will output a decimal integer with a space for the sign with positive values. |
| - | Left justify the output in the field width with spaces padding to the right if necessary. For example, %-10d will output an integer as a decimal value left justified in a field width of ten characters. The %-+10d specification will output a decimal integer with the sign always appearing, and left justified in a field width of ten characters. |
| # | Prefix hexadecimal output values with 0x or 0X (corresponding to x and X conversion type specification respectively), and octal values with 0. Always include a decimal point in floating-point values. Do not remove trailing zeros for g and G specifications. |
| 0 | Use 0 as the pad character to the left in a right-justified numerical output value. For example, %012d will output a decimal integer right justified in a field width of 12 characters, padded to the left with zeros as necessary. If precision is specified for an integer output, the 0 flag is ignored. |
[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.
[.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 six places after the decimal point.
For integer conversions, it specifies the minimum number of digits.
[size_flag] is a size specification for the value that modifies the meaning of the type specification. Possible size specifications are:
| Flag | Meaning |
|---|---|
| l (lowercase l) | specifies that a d, i, u, o, x, or X conversion type applies to an argument of type long or unsigned long. When applied to a type n conversion the argument is type long*. When applied to a type c conversion the argument is type wint_t. When applied to a type s conversion, the argument is type wchar_t*. |
| L | specifies that a following floating-point conversion specifier applies to a long double argument. |
| ll (two lowercase Ls) specifies that a d, i, u, o, x, or X conversion type applies to an argument of type long long or unsigned long long. When applied to a type n conversion, the argument is type long long*. | |
| h | specifies that a d, i, u, o, x, or X conversion type applies to an argument of type short or unsigned short. When applied to a type n conversion, the argument is type short*. |
| hh | specifies that a d, i, u, o, x, or X conversion type applies to an argument of type signed char or unsigned char. When applied to a type n conversion, the argument is type signed char*. |
| j | specifies that a following d, i, u, o, x, or X conversion type applies to an argument of type intmax_t or uintmax_t. When applied to an n conversion, the argument is of type intmax_t*. |
| z | specifies that a following d, i, u, o, x, or X conversion type applies to an argument of type size_t. When applied to an n conversion, the argument is of type size_t*. |
| t | specifies that a following d, i, u, o, x, or X conversion type applies to an argument of type ptrdiff_t. When applied to an n conversion, the argument is of type ptrdiff_t*. |
| type | a character specifying the type of conversion to be applied to a value as output: |
| d, i | The value is assumed to be of type int and the output is as a signed decimal integer. |
| u | The value is assumed to be of type unsigned int and the output is as an unsigned decimal integer. |
| o | for type of unsigned int and the output is as an unsigned octal value. |
| x or X | for type unsigned int and the output is as an unsigned hexadecimal value. The hexadecimal digits a to f are used if the lowercase type conversion specification is used and A to F otherwise. |
| c | for type of char and the output is as a character. |
| a or A | for type of double and the output is as a floating-point value in hexadecimal scientific notation ( with an exponent). The exponent value in the output will be preceded by p when you use the lowercase type conversion and P otherwise. Uppercase hexadecimal digits are used for output with A and lowercase with a. |
| e or E | for type of double and the output is as a floating-point value in decimal scientific notation (with an exponent). The exponent value in the output will be preceded by e when you use the lowercase type conversion and E otherwise. |
| f or F | for type of double and the output is as a floating-point value in ordinary notation (without an exponent). |
| g or G | for type of double and the output is as a floating-point value in ordinary notation (without an exponent) unless the exponent value is greater than the precision (default value 6) or is less than -4, in which case the output will be in scientific notation. |
| s | for null-terminated string of characters of type char and characters are output until the null character is found or until the precision specification is reached if it is present. The optional precision specification represents the maximum number of characters that may be output. |
| p | for a pointer, and because the output is an address, it will be a hexadecimal value. |
| n | for a pointer of type int* and the number of characters in the output so far is stored at the address pointed to by the argument. You cannot use this with the optional library functions for formatted output. |
| % | No argument is expected and the output is the % character. |