printf Function

Prints formatted text to stdout.

Include

<stdio.h>

Prototype

int printf(const char *format, ...);

Arguments

format: format control string
...: optional arguments; see “Remarks”

Return Value

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

Remarks

This function relies on the putch function to determine the destination of the standard output stream. A putch function must be written for each project that uses printf, and the project must include code that initializes any peripherals used by this routine. A stub for putch can be found in the sources directory of the compiler. Ensure the source code for your putch added to your project once it is complete. An example putch function that prints to a USART might be similar to:

void putch(char data)
{
    while( ! TXIF)
        continue;
    TXREG = data;
}

There must be exactly the same number of arguments as there are format specifiers. If the are less arguments than match the format specifiers, the output is undefined. If there are more arguments than match the format specifiers, the remaining arguments are discarded. Each format specifier begins with a percent sign followed by optional fields and a required type as shown here:

%[flags][width][.precision][size]type

flags

`-`	Left justify the value within a given field width.
`0`	Use 0 for the pad character instead of space (which is the default).
`+`	Generate a plus sign for positive signed values.
space	Generate a space or signed values that have neither a plus nor a minus sign.
`#`	To prefix 0 on an octal conversion, to prefix 0x or 0X on a hexadecimal conversion, or to generate a decimal point and fraction digits that are otherwise suppressed on a floating-point conversion.

width

Specify the number of characters to generate for the conversion. If the asterisk (*) is used instead of a decimal number, the next argument (which must be of type int) 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.

precision

The field width can be followed with dot (.) and a decimal integer representing the precision that specifies one of the following:

minimum number of digits to generate on an integer conversion
number of fraction digits to generate on an e, E, or f conversion
maximum number of significant digits to generate on a g or G conversion
maximum number of characters to generate from a C string on an s conversion

If the period appears without the integer, the integer is assumed to be zero. If the asterisk (*) is used instead of a decimal number, the next argument (which must be of type int) will be used for the precision.

size

h modifier	Used with type d, i, o, u, x, X; converts the value to a `short int` or `unsigned short int`.
h modifier	Used with n; specifies that the pointer points to a `short int`.
l modifier	Used with type d, i, o, u, x, X; converts the value to a `long int` or `unsigned long int`.
l modifier	Used with n; specifies that the pointer points to a `long int`.
l modifier	Used with c; specifies a wide character.
l modifier	Used with type e, E, f, F, g, G; converts the value to a `double`.
ll modifier	Used with type d, i, o, u, x, X; converts the value to a `long long int` or `unsigned long long int`.
ll modifier	Used with n; specifies that the pointer points to a `long long int`.
L modifier	Used with e, E, f, g, G; converts the value to a `long double`.

type

d, i	`signed int`.
o	`unsigned int` in octal.
u	`unsigned int` in decimal.
x	`unsigned int` in lowercase hexadecimal.
X	`unsigned int` in uppercase hexadecimal.
e, E	`double` in scientific notation.
f	`double` decimal notation.
g, G	`double` (takes the form of e, E or f as appropriate).
c	`char` - a single character.
s	`string`.
p	value of a pointer.
n	The associated argument shall be an integer pointer into which is placed the number of characters written so far. No characters are printed.
%	A `%` character is printed.

Example

#include <stdio.h>

int main(void)
{
  /* print a character right justified in a 3  */
  /* character space.                          */
  printf("%3c\n", 'a');

  /* print an integer, left justified (as      */
  /* specified by the minus sign in the format */
  /* string) in a 4 character space. Print a   */
  /* second integer that is right justified in */
  /* a 4 character space using the pipe (|) as */
  /* a separator between the integers.         */
  printf("%-4d|%4d\n", -4, 4);

  /* print a number converted to octal in 4    */
  /* digits.                                   */
  printf("%.4o\n", 10);

  /* print a number converted to hexadecimal   */
  /* format with a 0x prefix.                  */
  printf("%#x\n", 28);

  /* print a float in scientific notation      */
  printf("%E\n", 1.1e20);

  /* print a float with 2 fraction digits      */
  printf("%.2f\n", -3.346);

  /* print a long float with %E, %e, or %f     */
  /* whichever is the shortest version         */
  printf("%Lg\n", .02L);
}

Example Output

  a
-4  |   4
0012
0x1c
1.100000E+20
-3.35
0.02