printf

Writes formatted output to a specified file designated by stdout

Local Servers:blocking
Remote Servers:blocking
Classification:ANSI
Platform:NLM
Service:Stream I/O

Syntax

  #include <stdio.h>  
   
  int printf  (  
     const char   *format,   
     ... );

Parameters

format
(IN) Points to the format control string.

Return Values

The printf function returns the number of characters written, or it returns a negative value if an output error occurred. If an error occurs, errno is set.

Remarks

The printf function writes output to the file designated by stdout under control of the argument format.

The format control string consists of ordinary characters, which are written exactly as they occur in the format string, and of conversion specifiers, which cause argument values to be written as they are encountered during the processing of the format string. An ordinary character in the format string is any character, other than a percent (%) character, that is not part of a conversion specifier. A conversion specifier is a sequence of characters in the format string. The conversion specifier begins with a % and is followed, in sequence, by the following:

  • Zero or more format control flags, which can modify the final effect of the format directive.
  • An optional decimal integer, or an asterisk character (*), which specifies a minimum field width to be reserved for the formatted item.
  • An optional precision specification in the form of a period character (.) followed by an optional decimal integer or an asterisk character (*).
  • An optional type-length specification. It can be any one of the following characters:

    h l L N F

  • A character that specifies the type of conversion to be performed. It can be any one of the following characters:

    c d e E f F g G i n o p s u x X

The valid format control flags are:

-

The formatted item is left-justified within the field; normally, items are right-justified.

 

A signed, positive object always starts with a plus (+) character; normally, only negative items begin with a sign.

" "

A signed, positive object always starts with a space character; if both + and - are specified, + overrides -.

#

An alternate conversion form is used:

 

For o (unsigned octal) conversions, the precision is incremented so that the first digit is 0.

 

For x or X (unsigned hexadecimal) conversions, a nonzero value is prepended with 0x or 0X, respectively.

 

For e, E, f, g, or G (any floating-point) conversions, the result always contains a decimal-point character, even if no digits follow it; normally, a decimal- point character appears in the result only if there is a digit to follow it.

 

In addition to the preceding, for g or G conversions, trailing zeros are not removed from the result.

If no field width is specified, or if the value that is given is less than the number of characters in the converted value (subject to any precision value), a field of sufficient width to contain the converted value is used. If the converted value has fewer characters than are specified by the field width, the value is padded on the left (or right, subject to the left-justification flag) with spaces or zero characters (0). If the field width begins with a zero, the value is padded with zeros; otherwise, the value is padded with spaces. If the field width is *, a value of type int from the argument list is used (before a precision argument or a conversion argument) as the minimum field width. A negative field width value is interpreted as a left- justification flag, followed by a positive field width.

As with the field width specifier, a precision specifier of * causes a value of type int from the argument list to be used as the precision specifier. If no precision value is given, a precision of 0 is used. The precision value affects the following conversions:

  • For d, i, o, u, x, and X (integer) conversions, the precision specifies the minimum number of digits to appear.
  • For e, E, and f (fixed-precision, floating-point) conversions, the precision specifies the number of digits to appear after the decimal-point character.
  • For g and G (variable-precision, floating-point) conversions, the precision specifies the maximum number of significant digits to appear.
  • For s (string) conversions, the precision specifies the maximum number of characters to appear.

A type length specifier affects the conversion as follows:

h

Causes a d, i, o, u, x, or X (integer) conversion to process a short int or unsigned short int argument; note that although the argument can have been promoted as part of the function call, the value is converted to the smaller type before it is converted.

 

It causes an n (converted length assignment) operation to assign the converted length to an object of type unsigned short int.

l

Causes a d, i, o, u, x, or X (integer) conversion to process a long int or unsigned long int argument.

 

It causes an n (converted length assignment) operation to assign the converted length to an object of type unsigned long int.

F

Causes the pointer associated with n, p, or s conversions to be treated as a far pointer.

L

Causes an e, E, f, g, or G (double) conversion to process a long double argument.

N

Causes the pointer associated with n, p, or s conversions to be treated as a near pointer.

The valid conversion type specifiers are:

c

An argument of type int is converted to a value of type char and the corresponding ASCII character code is written to the output stream.

d, i

An argument of type int is converted to a signed decimal notation and written to the output stream. The default precision is 1, but if more digits are required, leading zeros are added.

e, E

An argument of type double is converted to a decimal notation in the form [-]d.ddde[+|-]ddd similar to FORTRAN exponential (E) notation. The leading sign appears (subject to the format control flags) only if the argument is negative. If the argument is nonzero, the digit before the decimal point character is nonzero. The precision is used as the number of digits following the decimal point character. If the precision is not specified, a default precision of 6 is used. If the precision is 0, the decimal point character is suppressed. The value is rounded to the appropriate number of digits. For E conversions, the exponent begins with the character E rather than e. The exponent sign and a three-digit number (that indicates the power of ten by which the decimal fraction is multiplied) are always produced.

f

An argument of type double is converted to a decimal notation in the form [-]ddd.ddd similar to FORTRAN fixed-point (F) notation. The leading sign appears (subject to the format control flags) only if the argument is negative. The precision is used as the number of digits following the decimal point character. If the precision is not specified, a default precision of 6 is used. If the precision is 0, the decimal point character is suppressed, otherwise, at least one digit is produced before the decimal point character. The value is rounded to the appropriate number of digits.

g, G

An argument of type double is converted using either the f or e (or E, for a G conversion) style of conversion depending on the value of the argument. In either case, the precision specifies the number of significant digits that are contained in the result. The e style conversion is used only if the exponent from such a conversion would be less than -4 or greater than the precision. Trailing zeros are removed from the result and a decimal-point character only appears if it is followed by a digit.

n

The number of characters that have been written to the output stream is assigned to the integer pointed to by the argument. No output is produced.

o

An argument of type int is converted to an unsigned octal notation and written to the output stream. The default precision is 1, but if more digits are required, leading zeros are added.

p, P

An argument of type void * is converted to a value of type int and the value is formatted as for a hexadecimal (x) conversion.

s

Characters from the string specified by an argument of type char *, up to, but not including, the terminating NULL character (\0), are written to the output stream. If a precision is specified, no more than that many characters are written.

S

Characters from a length-preceded string are written to the output stream. If a precision is specified, no more than that many characters are written.

u

An argument of type int is converted to an unsigned decimal notation and written to the output stream. The default precision is 1, but if more digits are required, leading zeros are added.

x, X

An argument of type int is converted to an unsigned hexadecimal notation and written to the output stream. The default precision is 1, but if more digits are required, leading zeros are added. Hexadecimal notation uses digits (0 through 9) and characters (a through f or A through F) for x or X conversions respectively, as the hexadecimal digits. Subject to the alternate-form control flag, 0x or 0X is affixed to the output.

Any other conversion type specifier character, including another percent ( %) character, is written to the output stream with no special interpretation.

The arguments must correspond with the conversion type specifiers, left to right in the string; otherwise, indeterminate results occur.

For example, a specifier of the form %8.*f defines a field to be at least 8 characters wide and gets the next argument for the precision to be used in the conversion.

The output from

  printf ("f1 = %8.4f f2 = %10.2E x = %#08x i = %d",  
        23.45,   3141.5926,   0x1db,     -1 );

would be

  f1 =  23.4500 f2 =   3.14E+003 x = 0x0001db i = -1

You can also use strings similar to the following:

  printf ("Test: %3$s %2$d %1$s", string, 10, string);

See Also

fprintf, sprintf, vfprintf

printf Example

  #include <stdio.h>  
   
  main ()  
  {  
     char    *weekday, *month;  
     int     day, year;  
     weekday = "Saturday";  
     month = "April";  
     day = 18;  
     year = 1991;  
     printf ("%s, %s %d, %d\n", weekday, month, day, year);  
  }

produces the following:

  Saturday, April 18, 1991