Format - StreamIO

printf, wprintf
Print formatted output to the standard output stream.
int printf( const char *format [, argument]... );
int wprintf( const wchar_t *format [, argument]... );

Routine	Required Header	Compatibility
printf	<stdio.h>	ANSI, Win 95, Win NT
wprintf	<stdio.h> or <wchar.h>	ANSI, Win 95, Win NT

Remarks
The printf function formats and prints a series of characters and values to the standard output stream, stdout. If arguments follow the format string, the format string must contain specifications that determine the output format for the arguments. printf and fprintf behave identically except that printf writes output to stdout rather than to a destination of type FILE.
wprintf is a wide-character version of printf; format is a wide-character string. wprintf and printf behave identically otherwise.

Generic-Text Routine Mappings

TCHAR.H	_UNICODE & _MBCS	_MBCS	_UNICODE
Routine	Not Defined	Defined	Defined
_tprintf	printf	printf	wprintf

Subject: Floating-Point Support Routines, Stream I/O Routines, Locale Routines
Keywords: See also fopen, fprintf, scanf, sprintf, vprintf Functions

Return Value
Each of these functions returns the number of characters printed, or a negative value if an error occurs.

Parameters

format	Format control string
argument	Optional arguments

The format argument consists of ordinary characters, escape sequences, and (if arguments follow format) format specifications. The ordinary characters and escape sequences are copied to stdout in order of their appearance. For example, the line
printf("Line one\n\t\tLine two\n");
produces the output
Line one
Line two
Format specifications always begin with a percent sign (%) and are read left to right. When printf encounters the first format specification (if any), it converts the value of the first argument after format and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications.
Details: Format control strings

Example
/* PRINTF.C: This program uses the printf and wprintf functions
* to produce formatted output.
*/

#include <stdio.h>

void main( void )
{
char ch = 'h', *string = "computer";
int count = -9234;
double fp = 251.7366;
wchar_t wch = L'w', *wstring = L"Unicode";

/* Display integers. */
printf( "Integer formats:\n"
"\tDecimal: %d Justified: %.6d Unsigned: %u\n",
count, count, count, count );

printf( "Decimal %d as:\n\tHex: %Xh C hex: 0x%x Octal: %o\n",
count, count, count, count );

/* Display in different radixes. */
printf( "Digits 10 equal:\n\tHex: %i Octal: %i Decimal: %i\n",
0x10, 010, 10 );

/* Display characters. */

printf("Characters in field (1):\n%10c%5hc%5C%5lc\n", ch, ch, wch, wch);
wprintf(L"Characters in field (2):\n%10C%5hc%5c%5lc\n", ch, ch, wch, wch);

/* Display strings. */

printf("Strings in field (1):\n%25s\n%25.4hs\n\t%S%25.3ls\n",
string, string, wstring, wstring);
wprintf(L"Strings in field (2):\n%25S\n%25.4hs\n\t%s%25.3ls\n",
string, string, wstring, wstring);

/* Display real numbers. */
printf( "Real numbers:\n\t%f %.2f %e %E\n", fp, fp, fp, fp );

/* Display pointer. */
printf( "\nAddress as:\t%p\n", &count);

/* Count characters printed. */
printf( "\nDisplay to here:\n" );
printf( "1234567890123456%n78901234567890\n", &count );
printf( "\tNumber displayed: %d\n\n", count );
}

Output
Integer formats:
Decimal: -9234 Justified: -009234 Unsigned: 4294958062
Decimal -9234 as:
Hex: FFFFDBEEh C hex: 0xffffdbee Octal: 37777755756
Digits 10 equal:
Hex: 16 Octal: 8 Decimal: 10
Characters in field (1):
h h w w
Characters in field (2):
h h w w
Strings in field (1):
computer
comp
Unicode Uni
Strings in field (2):
computer
comp
Unicode Uni
Real numbers:
251.736600 251.74 2.517366e+002 2.517366E+002

Address as: 0012FFAC

Display to here:
123456789012345678901234567890
Number displayed: 16

scanf, wscanf
Read formatted data from the standard input stream.
int scanf( const char *format [,argument]... );
int wscanf( const wchar_t *format [,argument]... );

Routine	Required Header	Compatibility
scanf	<stdio.h>	ANSI, Win 95, Win NT
wscanf	<stdio.h> or <wchar.h>	ANSI, Win 95, Win NT

Remarks
The scanf function reads data from the standard input stream stdin and writes the data into the location given by argument. Each argument must be a pointer to a variable of a type that corresponds to a type specifier in format. If copying takes place between strings that overlap, the behavior is undefined.
wscanf is a wide-character version of scanf; the format argument to wscanf is a wide-character string. wscanf and scanf behave identically otherwise.

Generic-Text Routine Mappings

TCHAR.H	_UNICODE & _MBCS	_MBCS	_UNICODE
Routine	Not Defined	Defined	Defined
_tscanf	scanf	scanf	wscanf

For more information, see Format Specification Fields — scanf functions and wscanf Functions.

Subject: Floating-Point Support Routines, Stream I/O Routines, Locale Routines
Kexwords: See also fscanf, printf, sprintf, sscanf

Return Value
Both scanf and wscanf return the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is EOF for an error or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character.

Parameters

format	Format control string
argument	Optional arguments

Example
/* SCANF.C: This program uses the scanf and wscanf functions
* to read formatted input.
*/

#include <stdio.h>

void main( void )
{
int i, result;
float fp;
char c, s[81];
wchar_t wc, ws[81];

printf( "\n\nEnter an int, a float, two chars and two strings\n");

result = scanf( "%d %f %c %C %s %S", &i, &fp, &c, &wc, s, ws );
printf( "\nThe number of fields input is %d\n", result );
printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c, wc, s, ws);

wprintf( L"\n\nEnter an int, a float, two chars and two strings\n");

result = wscanf( L"%d %f %hc %lc %S %ls", &i, &fp, &c, &wc, s, ws );
wprintf( L"\nThe number of fields input is %d\n", result );
wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp, c, wc, s, ws);
}

Output
Enter an int, a float, two chars and two strings
71
98.6
h
z
Byte characters

The number of fields input is 6
The contents are: 71 98.599998 h z Byte characters

Enter an int, a float, two chars and two strings
36
92.3
y
n
Wide characters

The number of fields input is 6
The contents are: 456 92.300003 y n Wide characters

Format Specification Fields:
printf and wprintf Functions
A format specification, which consists of optional and required fields, has the following form:
%[flags] [width] [.precision] [{h | l | I64 | L}]type

Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is copied to stdout. For example, to print a percent-sign character, use %%.
The optional fields, which appear before the type character, control other aspects of the formatting, as follows:
type Required character that determines whether the associated argument is interpreted as a character, a string, or a number
flags Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.
width Optional number that specifies the minimum number of characters output.
precision Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values.
h | l | I64 | L Optional prefixes to type-that specify the size of argument.

Keywords: See also scanf Format specification.

printf Format: Type Field Characters

Character	Type	Output Format
c	int or wint_t	When used with printf functions, specifies a single-byte character; when used with wprintf functions, specifies a wide character.
C	int or wint_t	When used with printf functions, specifies a wide character; when used with wprintf functions, specifies a single-byte character.
d	int	Signed decimal integer.
i	int	Signed decimal integer.
o	int	Unsigned octal integer.
u	int	Unsigned decimal integer.
x	int	Unsigned hexadecimal integer, using "abcdef."
X	int	Unsigned hexadecimal integer, using "ABCDEF."
e	double	Signed value having the form [ – ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or –.
E	double	Identical to the e format except that E rather than e introduces the exponent.
f	double	Signed value having the form [ – ]dddd.dddd where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
g	double	Signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than –4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G	double	Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).
n	Pointer to integer	Number of characters successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument.
p	Pointer to void	Prints the address pointed to by the argument in the form xxxx:yyyy where xxxx is the segment and yyyy is the offset, and the digits x and y are uppercase hexadecimal digits.
s	String	When used with printf functions, specifies a single-byte–character string; when used with wprintf functions, specifies a wide-character string. Characters are printed up to the first null character or until the precision value is reached.
S	String	When used with printf functions, specifies a wide-character string; when used with wprintf functions, specifies a single-byte–character string. Characters are printed up to the first null character or until the precision value is reached.

printf Format: Flag Characters

Flag	Meaning	Default
–	Left align the result within the given field width.	Right align.
+	Prefix the output value with a sign (+ or –) if the output value is of a signed type.	Sign appears only for negative signed values (–).
0	If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored.	No padding.
blank (' ')	Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.	No blank appears.
#	When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.	No blank appears.
#	When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases.	Decimal point appears only if digits follow it.
#	When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.	Decimal point appears only if digits follow it. Trailing zeros are truncated.
#	Ignored when used with c, d, i, u, or s.

printf Format: How Precision Values Affect Type

Type	Meaning	Default
c, C	The precision has no effect.	Character is printed.
d, i, u, o, x, X	The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.	Default precision is 1.
e, E	The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.	Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
f	The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.	Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
g, G	The precision specifies the maximum number of significant digits printed.	Six significant digits are printed, with any trailing zeros truncated.
s, S	The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed.	Characters are printed until a null character is encountered.

If the argument corresponding to a floating-point specifier is infinite, indefinite, or NaN, printf gives the following output.

Value	Output
+ infinity	1.#INFrandom-digits
– infinity	–1.#INFrandom-digits
Indefinite (same as quiet NaN)	digit.#INDrandom-digits
NAN	digit.#NANrandom-digits

printf Format: Size Prefixes for printf and wprintf Format-Type Specifiers

To Specify	Use Prefix	With Type Specifier
long int	l	d, i, o, x, or X
long unsigned int	l	u
short int	h	d, i, o, x, or X
short unsigned int	h	u
__int64	I64	d, i, o, u, x, or X
Single-byte character with printf functions	h	c or C
Single-byte character with wprintf functions	h	c or C
Wide character with printf functions	l	c or C
Wide character with wprintf functions	l	c or C
Single-byte – character string with printf functions	h	s or S
Single-byte – character string with wprintf functions	h	s or S
Wide-character string with printf functions	l	s or S
Wide-character string with wprintf functions	l	s or S

Thus to print single-byte or wide-characters with printf functions and wprintf functions, use format specifiers as follows.

To Print Character As	Use Function	With Format Specifier
single byte	printf	c, hc, or hC
single byte	wprintf	C, hc, or hC
wide	wprintf	c, lc, or lC
wide	printf	C, lc, or lC

To print strings with printf functions and wprintf functions, use the prefixes h and l analogously with format type-specifiers s and S.

printf Format: Width Specification
The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values — depending on whether the – flag (for left alignment) is specified — until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).
The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).
If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

Format Specification Fields:
scanf and wscanf Functions
A format specification has the following form:
%[*] [width] [{h | l | I64 | L}]type

The format argument specifies the interpretation of the input and can contain one or more of the following:

White-space characters: blank (' '); tab ('\t'); or newline ('\n').
A white-space character causes scanf to read, but not store, all consecutive white-space characters in the input up to the next non–white-space character. One white-space character in the format matches any number (including 0) and combination of white-space characters in the input.

Non–white-space characters, except for the percent sign (%).
A non–white-space character causes scanf to read, but not store, a matching non–white-space character. If the next character in stdin does not match, scanf terminates.

Format specifications, introduced by the percent sign (%).
A format specification causes scanf to read and convert characters in the input into values of a specified type. The value is assigned to an argument in the argument list.
The format is read from left to right. Characters outside format specifications are expected to match the sequence of characters in stdin; the matching characters in stdin are scanned but not stored. If a character in stdin conflicts with the format specification, scanf terminates, and the character is left in stdin as if it had not been read.

When the first format specification is encountered, the value of the first input field is converted according to this specification and stored in the location that is specified by the first argument. The second format specification causes the second input field to be converted and stored in the second argument, and so on through the end of the format string.

An input field is defined as all characters up to the first white-space character (space, tab, or newline), or up to the first character that cannot be converted according to the format specification, or until the field width (if specified) is reached. If there are too many arguments for the given specifications, the extra arguments are evaluated but ignored. The results are unpredictable if there are not enough arguments for the format specification.

Each field of the format specification is a single character or a number signifying a particular format option. The type character, which appears after the last optional format field, determines whether the input field is interpreted as a character, a string, or a number.

The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign (%) is followed by a character that has no meaning as a format-control character, that character and the following characters (up to the next percent sign) are treated as an ordinary sequence of characters, that is, a sequence of characters that must match the input. For example, to specify that a percent-sign character is to be input, use %%.
An asterisk (*) following the percent sign suppresses assignment of the next input field, which is interpreted as a field of the specified type. The field is scanned but not stored.

Keywords: See also printf Format specification.

StreamIO	Data Stream Input & Output

printf, wprintf	Print formatted output to the standard output stream.
scanf, wscanf	Read formatted data from the standard input stream.
Format specification	Format control string for printf and scanf functions

Aktuelle Daten dieser Seite	Letzte Änderung: