int sscanf(const char *s, const char *format[, arg, ...]);
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.
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:
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.
The assignment suppression character "*" suppresses the interpretation and assignment of the input field.
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.
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.
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.
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.
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. |
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.
The next character in the input field does not match the corresponding ordinary character in the string to be converted. |
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. |