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


scanf

Read 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 scanf(const char *format, ...);
Parameters:

Parameters for this facility are:

format  
const char *  
The format string  

Remarks:

The scanf() function reads text and converts the text read to programmer specified types.


Scanf Control String and Conversion Specifiers

The format argument is a character array containing normal text, white space (space, tab, newline), and conversion specifications. The normal text specifies literal characters that must be matched in the input stream. A white space character indicates that white space characters are skipped until a non-white space character is reached. The conversion specifications indicate what characters in the input stream are to be converted and stored.

The conversion specifications must have matching arguments in the order they appear in format. Because scanf() stores data in memory, the matching conversion specification arguments must be pointers to objects of the relevant types.

A conversion specification consists of the percent sign (%) prefix, followed by an optional maximum width or assignment suppression, and ending with a conversion type. A percent sign can be skipped by doubling it in format; %% signifies a single % in the input stream.

An optional width is a decimal number specifying the maximum width of an input field. scanf() will not read more characters for a conversion than is specified by the width.

An optional assignment suppression character (*) can be used to skip an item by reading it but not assigning it. A conversion specification with assignment suppression must not have a corresponding argument.

The last character, the conversion type, specifies the kind of conversion requested. "Length Modifiers And Conversion Specifiers For Formatted Input Functions," describes the conversion type characters.


MSL AltiVec Extensions for Scanf

The AltiVec extensions to the standard scanf 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 Scanf Extensions" demonstrates their use.

Length Modifiers And Conversion Specifiers For Formatted Input Functions:

Modifier
Description

Length Specifiers
hh  

The hh flag indicates that the following d, i, o, u, x, X or n conversion specifier applies to an argument that is of type char or unsigned char.

h  
The h flag indicates that the following d, i, o, u, x, X or n conversion specifier applies to an argument that is of type short int or unsigned short int.  
l  
When used with integer conversion specifier, the l flag indicates long int or an unsigned long int type. When used with floating point conversion specifier, the l flag indicates a double.   When used with a c or s conversion specifier, the l flag indicates that the corresponding argument with type pointer to wchar_t.  
ll  
When used with integer conversion specifier, the ll flag indicates that the corresponding argument is of type long long or an unsigned long long.  
L  
The L flag indicates that the corresponding float conversion specifier corresponds to an argument of type 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: 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: vector long, vector unsigned long or vector bool when followed by c, d, i, o, u, x or X  

Conversion Sepcifiers
d  
A decimal integer is read.  
i  
A decimal, octal, or hexadecimal integer is read. The integer can be prefixed with a plus or minus sign (+, -), 0 for octal numbers, 0x or 0X for hexadecimal numbers.  
o  
An octal integer is read.  
u  
An unsigned decimal integer is read.  
x, X  
A hexadecimal integer is read.  
e, E, f, g, G  
A floating point number is read. The number can be in plain decimal format (e.g. 3456.483) or in scientific notation   ([-]b.aaadd).  
s  
A character string is read. The input character string is considered terminated when a white space character is reached or the maximum width has been reached. The null character is appended to the end of the array.  
c  
A character is read. White space characters are not skipped, but read using this conversion specifier..  
p  
A pointer address is read. The input format should be the same as that output by the p conversion type in printf().  
n  
This conversion type does not read from the input stream but stores the number of characters read in its corresponding argument.  
[scanset]  
Input stream characters are read and filtered determined by the scanset. See "Scanset," for a full description.  

Return:

scanf() returns the number of items successfully read and returns EOF if a conversion type does not match its argument or and end-of-file is reached.

See Also:

"Wide Character and Byte Character Stream Orientation"

"fscanf"

"sscanf"

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

int main(void)
{
	int i;
	unsigned int j;
	char c;
	char s[40];
	double x;
	
	printf("Enter an integer surrounded by ! marks\n");
	scanf("!%d!", &i);
	printf("Enter three integers\n");
	printf("in hexadecimal, octal, or decimal.\n");
	// note that 3 integers are read, but only the last two
	// are assigned to i and j
	scanf("%*i %i %ui", &i, &j);

	printf("Enter a character and a character string.\n");
	scanf("%c %10s", &c, s);

	printf("Enter a floating point value.\n");
	scanf("%lf", &x);

	return 0;
}

Output:
Enter an integer surrounded by ! marks
!94!
Enter three integers
in hexadecimal, octal, or decimal.
1A 6 24
Enter a character and a character string.
Enter a floating point value.
A
Sounds like 'works'!
3.4

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

int main(void)
{
	vector signed char v8, vs8;
	vector unsigned short v16;
	vector signed long v32;
	vector float vf32;

	sscanf("1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16", "%vd", &v8);
	sscanf("1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16", "%,vd", &vs8);
	sscanf("abcdefgh", "%vhc", &v16);
	sscanf("1, 4, 300, 400", "%,3lvd", &v32);
	sscanf("1.10, 2.22, 3.333, 4.4444", "%,5vf", &vf32);
	
	return 0;
}

The Result is: 
v8  = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16;
vs8 = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16;
v16 = 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'
v32 =  1, 4, 300, 400
vf32 = 1.1000, 2.2200, 3.3330, 4.4444


[ 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