printf()

NAME

printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf() - formatted output conversion

SYNOPSIS

#include <stdio.h>

int printf (const char *format ...) int fprintf (FILE *stream, const char *format ...) int sprintf (char *str, const char *format ...) int snprintf (char *str, size_t size, const char *format ...)
#include <stdarg.h>
int vprintf (const char *format, va_list ap) int vfprintf (FILE *stream, const char *format, va_list ap) int vsprintf (char *str, const char *format, va_list ap) int vsnprintf (char *str, size_t size, const char *format, va_list ap)

DESCRIPTION

The functions in the printf(3) family produce output according to a format, as described below. Printf(3) and vprintf(3) write output to stdout, the standard output stream; fprintf(3) and vfprintf(3) write output to the specified output stream; sprintf(3), snprintf(3), vsprintf(3), and vsnprintf(3) write to the character string str.

These functions return the number of characters printed (not including the trailing \0 used to end output to strings). Sprintf(3) and vsprintf(3) effectively assume an infinite size.

Snprintf(3) and vsnprintf(3) write at most size-1 of the characters printed into the output string (the size'th character then get the terminating \0); if the return value is greater than or equal to the size, the string was too short and some of the printed characters were discarded. Sprintf(3) and vsprintf(3) effectively assume an infinite size.

The output is written according to the format string that specifies how subsequent arguments (or arguments accessed through the variable-length argument facilities of <stdarg.h>) are converted for output.

The format string contains zero or more directives; a directive is either an ordinary character (any character but %), which is copied unchanged to the output stream. The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; or a conversion specification. A conversion specification fetches zero or more subsequent arguments. Each conversion specification is introduced by the character %. The arguments must correspond properly (after type promotion) with the conversion specifier. The syntax of a conversion specifier is:

%[#][0][-][ ][+][width][.[precision]][h|l|L|q]type

Only the type is required.

In sequence, these flags are:

#
A # character specifies that the value should be converted to an "alternate form". This affects only o, x, X, e, E, f, g, and G conversions.
0
A zero character specifies that padding on the left is done with zeros rather than blanks. For all conversions except n, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion (d i, o, u, i, x, and X), the 0 flag is ignored.
-
A negative field width flag - indicates the converted value is to be left adjusted on the field boundary. Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.
A space specifies that a blank should be left before a positive number produced by a signed conversion (d e, E, f, g, G, or i).
+
A + character specifies that a sign always be placed before a number produced by a signed conversion. A + overrides a space if both are used.
width
This optional decimal digit string specifies a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width.

A field width may be indicated by an asterisk * instead of a digit string. In this case, an int argument supplies the field width. A negative field width is treated as a left adjustment flag followed by a positive field width.

precision
An optional precision, in the form of a period . followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point for e, E, and f conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s conversions.

A precision may be indicated by an asterisk * instead of a digit string. In this case, an int argument supplies the precision. A negative precision is treated as though it were missing.

h|l|L|q
One of the optional characters h, l (ell), L, or q, depending on the conversion type The values are:
h
a following d, i, o, u, x, or X conversion corresponds to a short int or unsigned short int argument, or that a following n conversion corresponds to a pointer to a short int argument.
l
(ell) A following d, i, o, u, x, or X conversion applies to a pointer to a long int or unsigned long int argument, or that a following n conversion corresponds to a pointer to a long int argument.
L
A following e, E, f, g, or G conversion corresponds to a long double argument.
q
A following d, i, o, u, x, or X conversion applies to a pointer to a quad_t or u_quad_t (unsigned long int) argument, or that a following n conversion corresponds to a pointer to a quad_t argument. The types quad_t (extended precisions) and u_quad_t (unsigned extended precision) are defined in <sys/types.h>. Two l (ell) conversion option characters are equivalent to a single q.
type
A character that specifies the type of conversion to be applied.
Type Argument Conversion
% Prints literal % character
c int Prints a character
d int Signed decimal
D long int Signed decimal; equivalent to ld
e double Decimal in form [-]d.ddde[mdd]
E double Decimal in form [-]d.dddE[mdd]
f double Decimal in form [-]ddd.ddd
g double The more compact of f or e format
i int Signed decimal
n int * Number of character printed so far stored in argument
o int Unsigned octal
O long int Unsigned octal; equivalent to lo
p void * Hexadecimal value of pointer, as for %#x or %#lx
s char * String
u int Unsigned decimal
U long int Unsigned decimal; equivalent to lu
X int Unsigned hexadecimal using letters ABCDEF
x int Unsigned hexadecimal using letters abcdef

Note:

f
The number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.
g
The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.
s
The char * argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating NUL character.
n
The number of characters written so far is stored into the integer indicated by the int * (or variant) pointer argument. No argument is converted.
%
A % is written. No argument is converted. The complete conversion specification is %%.

In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

EXAMPLES

To print a date and time in the form `Sunday, July 3, 10:02', where weekday and month are pointers to strings:

#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
	 weekday, month, day, hour, min);

To print to five decimal places:

#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

To allocate a 128-byte string and print into it:

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *nefmt(const char *fmt, ...)
{
	 char *p;
	 va_list ap;
	 if ((p = malloc(128)) == NULL)
		return (NULL);
	 va_start(ap, fmt);
	 (void) vsnprintf(p, 128, fmt, ap);
	 va_end(ap);
	 return (p);
}

SEE ALSO

printf(1)

scanf(3)