6.18.51 vprintf Function

Prints formatted text to stdout using a variable length argument list.

Include

<stdio.h>

<stdarg.h>

Prototype

int vprintf(const char * restrict format, va_list ap);

Arguments

format
format control string
ap
pointer to a list of arguments

Return Value

Returns number of characters generated or a negative number if an error occurs.

Remarks

To access the arguments, the ap object must be initialized by the macro va_start and may be reinitialized by additional calls to va_arg. This must be done before the vfprintf function is called. Invoke va_end after the function returns. For more details, see stdarg.h.

When building with MPLAB XC16 or XC-DSC, this function requires a heap.

To reduce code size, the functionality of this routine can be automatically customized by the compiler with each build. See the Smart IO Routines section in your compiler's user's guide for more information on the options that control this feature.

The format string is composed of text, which is copied unchanged to the output stream, and conversion specifications, which begin with the % character and which fetch zero or more of the optional arguments, converting them according to the corresponding conversion specifier when required, and then writing the result to the output stream. If the are less arguments than required by the conversion specifications, the output is undefined. If there are more arguments than required by the conversion specifications, the additional arguments are unused.

Each conversion specification begins with a percent sign followed by optional fields and a required type as shown here:

%[flags][width][.precision][length]specifier

The flags modify the meaning of the conversion specification. The are described in the following table.

Flag Meaning
- Left justify the conversion result within a given field width.
0 Use 0 for the pad character instead of space (which is the default) for d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, except when converting an infinity or NaN. If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, andX conversions, if a precision is specified, the 0 flag is ignored. For other conversions, the behavior is undefined.
+ Write a plus sign for positive signed conversion results.
space Prefix a space when the first character of a conversion result does not include a sign (+ or -) or if a signed conversion results in no characters. If the space and + flags both appear, the space flag is ignored.
# Convert the result to an alternative form. Specifically, for o conversions, it increases the precision, ensuring the first digit of the result is a zero, if and only if necessary. (If the value and precision are both 0, a single 0 is printed). For x (or X) conversions, 0x (or 0X) is prefixed to nonzero results. For a, A, e, E, f, F, g, and G conversions, the result of converting a floating-point number always contains a decimal-point character, even if no digits follow it. For g and G conversions, trailing zeros are not removed from the result. For other conversions, the behavior is undefined.

The width field indicated how many characters the value should consume. If the converted value has fewer characters than the field width, it is padded with spaces on the left, unless the left adjustment flag - has been used.

If the asterisk, *, is used instead of a decimal number, the int argument before the argument to be converted will be used for the field width. If the result is less than the field width, pad characters will be used on the left to fill the field. If the result is greater than the field width, the field is expanded to accommodate the value without padding.

The precision field indicates:
  • the minimum number of digits to appear for the d, i, o, u, x, and X conversions
  • the number of digits to appear after the decimal-point character for a, A, e, E, f, and F conversions
  • the maximum number of significant digits for the g and G conversions
  • the maximum number of bytes to be written for s conversions
The precision takes the form of a period, ., followed either by an asterisk, * or by an optional decimal integer. If neither the * or integer is specified, the precision is assumed to be zero. If the asterisk, *, is used instead of a decimal number, the int argument before the argument to be converted will be used for the precision. If a precision appears with any other conversion specifier, the behavior is undefined.

The length modifier specifies the size of the argument as described in the following table. Their use with other conversion specifiers results in undefined behavior.

Modifier Meaning
h  When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a short int or unsigned short int.
h When used with the n conversion specifier, indicates that the pointer argument points to a short int.
hh When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a signed char or unsigned char.
hh When used with the n conversion specifier, indicates that the pointer argument points to a signed char.
j When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is aintmax_t or uintmax_t.
j When used with the n conversion specifier, indicates that the pointer points to a intmax_t.
l When used with d, i, o, u, x, or X conversion specifiers, converts the argument value to a long int or unsigned long int.
l When used with the n conversion specifier, indicates that the pointer points to a long int.
l When used with the c conversion specifier, indicates that the argument value is a wide character (wint_t type).
l When used with the s conversion specifier, indicates that the argument value is a wide string (wchar_t type).
l When used the e, E, f, F, g, G, has no effect.
ll When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a long long int or unsigned long long int.
ll When used with the n conversion specifier, indicates that the pointer points to a long long int.
ll

MPLAB XC16 and XC-DSC: When used with the s conversion specifier, indicates that the string pointer is an __eds__ pointer.

Other compilers: The modifier is silently ignored.
L When used with the a, A, e, E, f, F, g, G conversion specifiers, indicates the argument value is a long double.
t When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a ptrdiff_t or the corresponding unsigned integer type.
t When used with the n conversion specifier, indicates that the pointer points to a ptrdiff_t.
z When used with d, i, o, u, x, or X conversion specifiers, indicates that the argument value is a size_t or the corresponding signed integer type.
z When used with the n conversion specifier, indicates that the pointer points to a size_t.

The conversion specifiers specify the type of conversion to be applied to the argument and how that value should be printed, as described in the following table.

Specifier Argument value type Printing notes
a, A double Converted to the general form [−]0xh.hhhhp±d, where there is one hexadecimal digit before the decimal-point character and the number of hexadecimal digits after it is equal to the precision.
c char or wint_t The integer argument value is converted to a char type and printed as a single character. When the l modifier is present, the wint_t argument is converted to multibyte characters then printed.
d signed int Converted to signed decimal with the general form [−]dddd. The precision specifies the minimum number of digits to appear.
e, E double Converted to the general form [−]d.ddde±dd, where there is one digit before the decimal-point character and the number of digits after it is equal to the precision, which is 6 if that is missing. If the precision is zero and the # flag is not specified, no decimal-point character appears.
f, F double Converted to decimal notation using the general form [−]ddd.ddd, where the number of digits after the decimal-point character is equal to the precision specification, which is 6 if that is missing. If the precision is zero and the # flag is not specified, no decimal-point character appears.
g, G double takes the form of e, f, or E or F in the case of G, as appropriate
i signed int Converted to signed decimal with the general form [−]dddd. The precision specifies the minimum number of digits to appear.
n an integer pointer The number of characters written so far is written to the object pointed to by the pointer. No characters are printed.
o unsigned int Converted to unsigned octal with the general form dddd. The precision specifies the minimum number of digits to appear
p void * Printed as the value (not necessarily an address) held by the pointer.
s char array, or wchar_t array A string, whose characters are written up to but not including the terminating null character. When the l modifier is present, wide characters from the array are converted to multibyte characters up to and including a terminating null wide character, which are then written up to but not including the terminating null character.
u unsigned int Converted to unsigned decimal with the general form dddd. The precision specifies the minimum number of digits to appear
x unsigned int Converted to unsigned hexadecimal notation with the general form dddd. The letters abcdef are printed for digits above 9. The precision specifies the minimum number of digits to appear
X unsigned int Converted to unsigned hexadecimal notation with the general form dddd. The letters ABCDEF are printed for digits above 9. The precision specifies the minimum number of digits to appear
% No argument is converted and a % character is printed.

Example 

#include <stdio.h>
#include <stdarg.h>

void errmsg(const char *fmt, ...)
{
  va_list ap;

  va_start(ap, fmt);
  printf("Error: ");
  vprintf(fmt, ap);
  va_end(ap);
}
int main(void)
{
  int num = 3;

  errmsg("The letter '%c' is not %s\n", 'a', "an integer value.");
  errmsg("Requires %d%s\n", num, " or more characters.\n");
}

Example Output 

Error: The letter 'a' is not an integer value.
Error: Requires 3 or more characters.