sscanf


nput with format

[Classification]

Standard library

[Syntax]

#include <stdio.h>

int sscanf(const char *s, const char *format[, arg, ...]);

[Return value]

The number of input fields for which scanning, conversion, and storage were executed normally is returned. The return value does not include scanned fields that were not stored. If an attempt is made to read to the end of the file, the return value is EOF. If no field was stored, the return value is 0.

[Description]

This function reads the input to be converted according to the format specified by the character string pointed to by format from the array pointed to by s and treats the arg arguments that follow format as pointers that point to objects for storing the converted input.

An input string that can be recognized and "the conversion that is to be performed for assignment" are specified for format. If sufficient arguments do not exist for format, the operation is undefined. If format is used up even when arguments remain, the remaining arguments are ignored.

The format consists of the following three types of directives:

One or more Space characters

Space ( ), tab (\t), or new-line (\n).

If a space character is found in the string when sscanf is executed, all consecutive space characters are read until the next non-space character appears (the space characters are not stored).

Ordinary characters

All ASCII characters other than "%".

If an ordinary character is found in the string when sscanf is executed, that character is read but not stored. sscanf reads a string from the input field, converts it into a value of a specific type, and stores it at the position specified by the argument, according to the conversion specification. If an explicit match does not occur according to the conversion specification, no subsequent space character is read.

Conversion specification

Fetches 0 or more arguments and directs the conversion.

 

Each conversion specification starts with "%". The following appear after the "%":

 

%[assignment-suppression-character][field-width][size][type-specification-character]

 

Each conversion specification is explained below.

(1)

Assignment suppression character

The assignment suppression character "*" suppresses the interpretation and assignment of the input field.

(2)

field width

This is a non-zero decimal integer that defines the maximum field width.

It specifies the maximum number of characters that are read before the input field is converted. If the input field is smaller than this field width, sscanf reads all the characters in the field and then proceeds to the next field and its conversion specification.

If a space character or a character that cannot be converted is found before the number of characters equivalent to the field width is read, the characters up to the white space or the character that cannot be converted are read and stored. Then, sscanf proceeds to the next conversion specification.

(3)

size

This is an arbitrary optional size character h, l, ll, or L, which changes the default method for interpreting the data type of the corresponding argument.

When h is specified, a following d, i, n, o, u, or x type specification is forcibly converted to short int type and stored as short type. Nothing is done for c, e, f, n, p, s, D, I, O, U, or X.

When l is specified, a following d, i, n, o, u, or x type specification is forcibly converted to long int type and stored as long type. An e, f, or g type specification is forcibly converted to double type and stored as double type. Nothing is done for c, n, p, s, D, I, O, U, and X.

When ll is specified, a following d, i, o, u, x, or X type specification is forcibly converted to long long type and stored as long long type. Nothing is done for other type specifications.

When L is specified, a following e, f, or g type specification is forcibly converted to long double type and stored as long double type. Nothing is done for other type specifications.

In cases other than the above, the operation is undefined.

(4)

type specification character

These are characters that specify the type of conversion that is to be applied.

The characters that specify conversion types and their meanings are as follows.

%

Match the character "%". No conversion or assignment is performed. The conversion specification is "%%".

c

Scan one character. The corresponding argument should be "char *arg".

d

Read a decimal integer into the corresponding argument. The corresponding argument should be "int *arg".

e, f, g

Read a floating-point number into the corresponding argument. The corresponding argument should be "float *arg".

i

Read a decimal, octal, or hexadecimal integer into the corresponding argument. The corresponding argument should be "int *arg".

n

Store the number of characters that were read in the corresponding argument. The corresponding argument should be "int *arg".

o

Read an octal integer into the corresponding argument. The corresponding argument must be "int *arg".

p

Store the pointer that was scanned.

The ca processes %p and %U in exactly the same manner. The corresponding argument should be "void **arg".

s

Read a string into a given array. The corresponding argument should be "char arg[ ]".

u

Read an unsigned decimal integer into the corresponding argument. The corresponding argument should be "unsigned int *arg".

x, X

Read a hexadecimal integer into the corresponding argument. The corresponding argument should be "int *arg".

D

Read a decimal integer into the corresponding argument. The corresponding argument should be "long *arg".

E, F, G

Read a floating-point number into the corresponding argument. The corresponding argument should be "double *arg".

I

Read a decimal, octal, or hexadecimal integer into the corresponding argument. The corresponding argument should be "long *arg".

O

Read an octal integer into the corresponding argument. The corresponding argument should be "long *arg".

U

Read an unsigned decimal integer into the corresponding argument. The corresponding argument should be "unsigned long *arg".

[ ]

Read a non-empty string into the memory area starting with argument arg. This area must be large enough to accommodate the string and the null character (\0) that is automatically appended to indicate the end of the string. The corresponding argument should be "char *arg".

The character pattern enclosed by [ ] can be used in place of the type specification character s. The character pattern is a character set that defines the search set of the characters constituting the input field of sscanf. If the first character within [ ] is "^", the search set is complemented, and all ASCII characters other than the characters within [ ] are included. In addition, a range specification feature that can be used as a shortcut is also available. For example, %[0-9] matches all decimal numbers. In this set, "-" cannot be specified as the first or last character. The character preceding "-" must be less in lexical sequence than the succeeding character.

 

-

%[abcd]
Matches character strings that include only a, b, c, and d.

-

%[^abcd]
Matches character strings that include any characters other than a, b, c, and d.

-

%[A-DW-Z]
Matches character strings that include A, B, C, D, W, X, Y, and Z.

-

%[z-a]
Matches z, -, and a (this is not considered a range specification).

 

Make sure that a floating-point number (type specification characters e, f, g, E, F, and G) corresponds to thefollowing general format.

 

[ + | - ] ddddd [ . ] ddd [ E | e [ + | - ] ddd ]

 

However, the portions enclosed by [ ] in the above format are arbitrarily selected, and ddd indicates a decimal digit.

[Caution]

-

sscanf may stop scanning a specific field before the normal end-of-field character is reached or may stop completely.

-

sscanf stops scanning and storing a field and moves to the next field under the following conditions.

-

The substitution suppression character (*) appears after "%" in the format specification, and the input field at that point has been scanned but not stored.

-

A field width (positive decimal integer) specification character was read.

-

The character to be read next cannot be converted according to the conversion specification (for example, if Z is read when the specification is a decimal number).

-

The next character in the input field does not appear in the search set (or appears in the complement search set).

If sscanf stops scanning the input field at that point because of any of the above reasons, it is assumed that the next character has not yet been read, and this character is used as the first character of the next field or the first character for the read operation to be executed after the input.

-

sscanf ends under the following conditions:

-

The next character in the input field does not match the corresponding ordinary character in the string to be converted.

-

The next character in the input field is EOF.

-

The string to be converted ends.

-

If a list of characters that is not part of the conversion specification is included in the string to be converted, make sure that the same list of characters does not appear in the input. sscanf scans matching characters but does not store them. If there was a mismatch, the first character that does not match remains in the input as if it were not read.

[Example]

#include    <stdio.h>
void func(void) {
        int         i, n;
        float       x;
        const char  *s;
        char        name[10];
        s = "23 11.1e-1 NAME";
        n = sscanf(s,"%d%f%s", &i, &x, name);   /*Stores 23 in i, 1.110000 in x, and 
                                                  "NAME" in name.  The return value n 
                                                  is 3.*/
}