[ First ]  [ Previous ]  [ Next ]  [ Last ]  [ Manuals ]


printf

Output formatted text.

Compatibility:

This function is compatible with the following targets:

ANSI

BeOS

EMB/RTOS

Mac OS

Palm OS

Win32


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

Parameters for this facility are:

format  
const char *  
A format string  

Remarks:

The printf() function outputs formatted text. The function takes one or more arguments, the first being format, a character array pointer. The optional arguments following format are items (integers, characters, floating point values, etc.) that are to be converted to character strings and inserted into the output of format at specified points.

The printf() function sends its output to stdout.


Printf Control String and Conversion Specifiers

The format character array contains normal text and conversion specifications. Conversion specifications must have matching arguments in the same order in which they occur in format.

The various elements of the format string is specified in the ANSI standards to be in this order from left to right.

A conversion specification describes the format its associated argument is to be converted to. A specification starts with a percent sign (%), optional flag characters, an optional minimum width, an optional precision width, and the necessary, terminating conversion type. Doubling the percent sign (%%) results in the output of a single %.

An optional flag character modifies the formatting of the output; it can be left or right justified, and numerical values can be padded with zeroes or output in alternate forms. More than one optional flag character can be used in a conversion specification. "Length Modifiers And Conversion Specifiers For Formatted Output Functions" describes the flag characters.

The optional minimum width is a decimal digit string. If the converted value has more characters that the minimum width, it is expanded as required. If the converted value has fewer characters than the minimum width, it is, by default, right justified (padded on the left). If the - flag character is used, the converted value is left justified (padded on the right).


NOTE

The maximum minimum field width allowed in MSL Standard Libraries is 509 characters.

The optional precision width is a period character (.) followed by decimal digit string. For floating point values, the precision width specifies the number of digits to print after the decimal point. For integer values, the precision width functions identically to, and cancels, the minimum width specification. When used with a character array, the precision width indicates the maximum width of the output.

A minimum width and a precision width can also be specified with an asterisk (*) instead of a decimal digit string. An asterisk indicates that there is a matching argument, preceding the conversion argument, specifying the minimum width or precision width.

The terminating character, the conversion type, specifies the conversion applied to the conversion specification's matching argument "Length Modifiers And Conversion Specifiers For Formatted Output Functions," describes the conversion type characters.


MSL AltiVec Extensions for Printf

The AltiVec extensions to the standard printf family of functions is supported in Metrowerks Standard Libraries.

Separator arguments after % and before any specifier may be any character or may be the @ symbol. The @ symbol is a non-Motorola extension that will use a specified string as a specifier.

In the specific case of a 'c' specifier any char may be used as a sepaator for all other specifiers '-', '+', '#', ' ' may not be used.

The listing "Example of AltiVec Printf Extensions" demonstrates their use.

Length Modifiers And Conversion Specifiers For Formatted Output Functions:

Modifier
Description

Size
h  
The h flag followed by d, i, o, u, x, or X conversion specifier indicates that the corresponding argument is a short int or unsigned short int.  
l  
The lower case L followed by d, i, o, u, x, or X conversion specifier indicates the argument is a long int or unsigned long int.   The lower case L followed by a c conversion spcifier, it indicates that the argument is of type wint_t.   The lower case L followed by an s conversion specifier, it indicates that the argument is of type wchar_t.  
ll  
The double l followed by d, i, o, u, x, or X conversion specifier indicates the argument is a long long or unsigned long long  
L  
The upper case L followed by e, E, f, g, or G conversion specifier indicates a long double.  

v

AltiVec: A vector bool char, vector signed char or vector unsigned char when followed by c, d, i, o, u, x or X   A vector float, when followed by f.  
vh   hv  
AltiVec: A vector short, vector unisgned short, vector bool short or vector pixel when followed by c, d, i, o, u, x or X  
vl   lv  
AltiVec: A vector int, vector unsigned int or vector bool int when followed by c, d, i, o, u, x or X  

Flags
-  
The conversion will be left justified.  
+  
The conversion, if numeric, will be prefixed with a sign   (+ or -). By default, only negative numeric values are prefixed with a minus sign (-).  
space  
If the first character of the conversion is not a sign character, it is prefixed with a space. Because the plus sign flag character (+) always prefixes a numeric value with a sign, the space flag has no effect when combined with the plus flag.  
#  
For c, d, i, and u conversion types, the # flag has no effect. For s conversion types, a pointer to a Pascal string, is output as a character string. For o conversion types, the # flag prefixes the conversion with a 0. For x conversion types with this flag, the conversion is prefixed with a 0x. For e, E, f, g, and G conversions, the # flag forces a decimal point in the output. For g and G conversions with this flag, trailing zeroes after the decimal point are not removed.  
0  
This flag pads zeroes on the left of the conversion. It applies to d, i, o, u, x, X, e, E, f, g, and G conversion types. The leading zeroes follow sign and base indication characters, replacing what would normally be space characters. The minus sign flag character overrides the 0 flag character. The 0 flag is ignored when used with a precision width for d, i , o, u, x, and X conversion types.  
@  
AltiVec This flag indicates a pointer to a string specified by an agument. This string will be used as a separator for vector elements.  

Conversions
d  
The corresponding argument is converted to a signed decimal.  
i  
The corresponding argument is converted to a signed decimal.  
o  
The argument is converted to an unsigned octal.  
u  
The argument is converted to an unsigned decimal.  
x, X  
The argument is converted to an unsigned hexadecimal. The x conversion type uses lowercase letters (abcdef) while X uses uppercase letters (ABCDEF).  
n  
This conversion type stores the number of items output by printf() so far. Its corresponding argument must be a pointer to an int.  
f, F  
The corresponding floating point argument (float, or double) is printed in decimal notation. The default precision is 6 (6 digits after the decimal point). If the precision width is explicitly 0, the decimal point is not printed.   For the f conversion specifier, a double argument representing infinity produces [-]inf; a double argument representing a NaN (Not a number) produces [-]nan. For the F conversion specifier, [-]INF or [-]NAN are produced instead.  
e, E  
The floating point argument (float or double) is output in scientific notation: [-]b.aaae±Eee. There is one digit (b) before the decimal point. Unless indicated by an optional precision width, the default is 6 digits after the decimal point (aaa). If the precision width is 0, no decimal point is output. The exponent (ee) is at least 2 digits long.   The e conversion type uses lowercase e as the exponent prefix. The E conversion type uses uppercase E as the exponent prefix.  
g, G  
The g conversion type uses the f or e conversion types and the G conversion type uses the f or E conversion types. Conversion type e (or E) is used only if the converted exponent is less than -4 or greater than the precision width. The precision width indicates the number of significant digits. No decimal point is output if there are no digits following it.  
c  
The corresponding argument is output as a character.  
s  
The corresponding argument, a pointer to a character array, is output as a character string. Character string output is completed when a null character is reached. The null character is not output.  
p  
The corresponding argument is taken to be a pointer. The argument is output using the X conversion type format.  

CodeWarrior Extensions
#s  
The corresponding argument, a pointer to a Pascal string, is output as a character string. A Pascal character string is a length byte followed by the number characters specified in the length byte.   Note: This conversion type is an extension to the ANSI C library but applied in the same manner as for other format variations.  

Return:

printf(), like fprintf(), sprintf(), vfprintf(), and vprintf(), returns the number of arguments that were successfully output. printf() returns a negative value if it fails.

See Also:

"Wide Character and Byte Character Stream Orientation"

"fprintf"

"sprintf"

"vfprintf"

"vprintf"

"vsprintf"

Example of printf() usage.:
#include <stdio.h>

int main(void)
{
	int i = 25;
	char c = 'M';
	short int d = 'm';
	static char s[] = "Metrowerks!";
	static char pas[] = "\pMetrowerks again!";
	float f = 49.95;
	double x = 1038.11005;
	int count;	
	printf("%s printf() demonstration:\n%n", s, &count);
	printf("The last line contained %d characters\n",count);
	printf("Pascal string output: %#20s\n", pas);
	printf("%-4d %x %06x %-5o\n", i, i, i, i);
	printf("%*d\n", 5, i);
	printf("%4c %4u %4.10d\n", c, c, c);
	printf("%4c %4hu %3.10hd\n", d, d, d);
	printf("$%5.2f\n", f);
	printf("%5.2f\n%6.3f\n%7.4f\n", x, x, x);
	printf("%*.*f\n", 8, 5, x);

	return 0;
}

The output is:
Metrowerks! printf() demonstration:
The last line contained 36 characters
Pascal string output:    Metrowerks again!
25   19 000019 31   
   25
   M   77 0000000077
   m  109 0000000109
$49.95
1038.11
1038.110
1038.1101
1038.11005

Example of AltiVec Printf Extensions:
#include <stdio.h> 

int main(void)
{
	vector signed char s =
		(vector signed char)(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16);
	vector unsigned short us16 =
		(vector unsigned short)('a','b','c','d','e','f','g','h');
	vector signed int sv32 =
		(vector signed int)(100, 2000, 30000, 4);
	vector signed int vs32 =
		(vector signed int)(0, -1, 2, 3);
	vector float flt32 =
		(vector float)(1.1, 2.22, 3.3, 4.444);
	
	printf("s = %vd\n", s);
	
	printf("s = %,vd\n", s);
	
	printf("vector=%@vd\n", "\nvector=", s);
	
		// c specifier so no space is added.
	printf("us16 = %vhc\n", us16);
	
	printf("sv32 = %,5lvd\n", sv32);
	
	printf("vs32 = 0x%@.8lvX\n", ", 0x", vs32);
		
	printf("flt32 = %,5.2vf\n", flt32);
	
	
	return 0;
}

The Result is:
s = 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
s = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
vector=1 
vector=2 
vector=3 
vector=4 
vector=5 
vector=6 
vector=7 
vector=8 
vector=9 
vector=10 
vector=11 
vector=12 
vector=13 
vector=14 
vector=15 
vector=16
us16 = abcdefgh
sv32 =   100, 2000,30000,    4
vs32 = 0x00000000, 0xFFFFFFFF, 0x00000002, 0x00000003
flt32 =  1.10, 2.22, 3.30, 4.44


[ First ]  [ Previous ]  [ Next ]  [ Last ]  [ Manuals ]

Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: cw_support@metrowerks.com
Copyright © 2000, Metrowerks Corp. All rights reserved.

Last updated: August 16, 2000