EAGLE Help

printf()


Function
Writes formatted output to a file.

Syntax
int printf(string format[, argument, ...]);

Returns
The printf function returns the number of characters written to the file that has been opened by the most recent output statement.

In case of an error, printf returns -1.

See also sprintf, output, fileerror

Format string

The format string controls how the arguments will be converted, formatted and printed. There must be exactly as many arguments as necessary for the format. The number and type of arguments will be checked against the format, and any mismatch will lead to an error message.

The format string contains two types of objects - plain characters and format specifiers:

Format specifiers

A format specifier has the following form:

% [flags] [width] [.prec] type

Each format specification begins with the percent character (%). After the % comes the following, in this order:

Conversion type characters

d signed decimal int
o unsigned octal int
u unsigned decimal int
x unsigned hexadecimal int (with a, b,...)
X unsigned hexadecimal int (with A, B,...)
f signed real value of the form [-]dddd.dddd
e signed real value of the form [-]d.dddde[±]ddd
E same as e, but with E for exponent
g signed real value in either e or f form, based on given value and precision
G same as g, but with E for exponent if e format used
c single character
s character string
% the % character is printed

Flag characters

The following flag characters can appear in any order and combination.

"-" the formatted item is left-justified within the field; normally, items are right-justified
"+" a signed, positive item will always start with a plus character (+); normally, only negative items begin with a sign
" " a signed, positive item will always start with a space character; if both "+" and " " are specified, "+" overrides " "

Width specifiers

The width specifier sets the minimum field width for an output value.

Width is specified either directly, through a decimal digit string, or indirectly, through an asterisk (*). If you use an asterisk for the width specifier, the next argument in the call (which must be an int) specifies the minimum output field width.

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 simply expanded to contain the conversion result.

n At least n characters are printed. If the output value has less than n characters, the output is padded with blanks (right-padded if "-" flag given, left-padded otherwise).
0n At least n characters are printed. If the output value has less than n characters, it is filled on the left with zeroes.
* The argument list supplies the width specifier, which must precede the actual argument being formatted.

Precision specifiers

A precision specifier always begins with a period (.) to separate it from any preceding width specifier. Then, like width, precision is specified either directly through a decimal digit string, or indirectly, through an asterisk (*). If you use an asterisk for the precision specifier, the next argument in the call (which must be an int) specifies the precision.

none Precision set to default.
.0 For int types, precision is set to default; for real types, no decimal point is printed.
.n n characters or n decimal places are printed. If the output value has more than n characters the output might be truncated or rounded (depending on the type character).
* The argument list supplies the precision specifier, which must precede the actual argument being formatted.

Default precision values

douxX 1
eEf 6
gG all significant digits
c no effect
s print entire string

How precision specification (.n) affects conversion

douxX .n specifies that at least n characters are printed. If the input argument has less than n digits, the output value is left-padded with zeros. If the input argument has more than n digits, the output value is not truncated.
eEf .n specifies that n characters are printed after the decimal point, and the last digit printed is rounded.
gG .n specifies that at most n significant digits are printed.
c .n has no effect on the output.
s .n specifies that no more than n characters are printed.

Binary zero characters

Unlike sprintf, the printf function can print binary zero characters (0x00).

char c = 0x00;
printf("%c", c);

Example

int i = 42;
real r = 3.14;
char c = 'A';
string s = "Hello";
printf("Integer: %8d\n", i);
printf("Hex:     %8X\n", i);
printf("Real:    %8f\n", r);
printf("Char:    %-8c\n", c);
printf("String:  %-8s\n", s);

Index Copyright © 2005 CadSoft Computer GmbH