View source for Software:Scanf format string

{{Short description|Control parameter used in programming languages}}
{{lowercase}}
A '''scanf format string''' (''scan f''ormatted) is a control parameter used in various functions to specify the layout of an input [[String (computer science)|string]]. The functions can then divide the string and translate into values of appropriate [[Data type|data type]]s. String scanning functions are often supplied in standard [[Library (computing)|libraries]].Scanf is a function that reads formatted data from the standard input string, which is usually the keyboard and writes the results whenever called in the specified arguments.

The term "scanf" comes from the [[C standard library|C library]], which popularized this type of function, but such functions predate C, and other names are used, such as <code>readf</code> in [[ALGOL 68]]. scanf format strings, which provide formatted input ([[Parsing|parsing]]), are complementary to [[Software:Printf format string|printf format string]]s, which provide formatted output (templating). These provide simple functionality and fixed format compared to more sophisticated and flexible parsers or template engines, but are sufficient for many purposes.

==History==
[[Biography:Mike Lesk|Mike Lesk]]'s [[Stdio.h|portable input/output library]], including <code>scanf</code>, officially became part of Unix in [[Software:Version 7 Unix|Version 7]].<ref name="reader">{{cite techreport |first1=M. D. |last1=McIlroy |year=1987 |url=http://www.cs.dartmouth.edu/~doug/reader.pdf |title=A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 |series=CSTR |number=139 |institution=Bell Labs}}</ref>

==Usage==
The <code>scanf</code> function, which is found in C, reads input for numbers and other datatypes from standard input (often a command line interface or similar kind of a text user interface).

The following C code reads a variable number of unformatted decimal [[Integer|integer]]s from the standard input stream and prints each of them out on separate lines:

<source lang="c">
#include <stdio.h>

int main(void)
{
    int n;

    while (scanf("%d", &n) == 1)
        printf("%d\n", n);
    return 0;
}
</source>

After being processed by the program above, an irregularly spaced list of integers such as

 456 123 789 456 12
 456 1
       2378

will appear consistently spaced as:
 456
 123
 789
 456
 12
 456
 1
 2378

To print out a word:

<source lang="c">
#include <stdio.h>

int main(void)
{
    char word[20];

    if (scanf("%19s", word) == 1)
        puts(word);
    return 0;
}
</source>

No matter what the data type the programmer wants the program to read, the arguments (such as <code>&n</code> above) must be [[Pointer (computer programming)|pointer]]s pointing to memory. Otherwise, the function will not perform correctly because it will be attempting to overwrite the wrong sections of memory, rather than pointing to the memory location of the variable you are attempting to get input for.

In the last example an address-of operator (<code>&</code>) is ''not'' used for the argument: as <code>word</code> is the name of an [[Array data structure|array]] of <code>char</code>, as such it is (in all contexts in which it evaluates to an address) equivalent to a pointer to the first element of the array. While the expression <code>&word</code> would numerically evaluate to the same value, semantically, it has an entirely different meaning in that it stands for the address of the whole array rather than an element of it. This fact needs to be kept in mind when assigning <code>scanf</code> output to strings.

As <code>scanf</code> is designated to read only from standard input, many programming languages with interfaces, such as [[Organization:PHP|PHP]], have derivatives such as <code>sscanf</code> and <code>fscanf</code> but not <code>scanf</code> itself.

==Format string specifications==
The formatting placeholders in <code>scanf</code> are more or less the same as that in [[Printf|<code>printf</code>]], its reverse function. As in printf, the POSIX extension {{code|n$}} is defined.<ref name=linux/>

There are rarely constants (i.e., characters that are not formatting placeholders) in a format string, mainly because a program is usually not designed to read known data, although <code>scanf</code> does accept these if explicitly specified. The exception is one or more whitespace characters, which discards all whitespace characters in the input.<ref name=linux/>

Some of the most commonly used placeholders follow:
* <code>%a</code> : Scan a floating-point number in its hexadecimal notation.
* <code>%d</code> : Scan an integer as a signed [[Decimal|decimal]] number.
* <code>%i</code> : Scan an integer as a signed number.  Similar to <code>%d</code>, but interprets the number as [[Hexadecimal|hexadecimal]] when preceded by <code>0x</code> and [[Octal|octal]] when preceded by <code>0</code>.  For example, the string <code>031</code> would be read as 31 using <code>%d</code>, and 25 using <code>%i</code>. The flag <code>h</code> in <code>%hi</code> indicates conversion to a <code>short</code> and <code>hh</code> conversion to a <code>char</code>.
* <code>%u</code> : Scan for decimal <code>unsigned int</code> (Note that in the C99 standard the input value minus sign is optional, so if a minus sign is read, no errors will arise and the result will be the [[Two's complement|two's complement]] of a negative number, likely a very large value. See <code>strtoul()</code>.{{Failed verification|date=January 2011}}) Correspondingly, <code>%hu</code> scans for an <code>unsigned short</code> and <code>%hhu</code> for an <code>unsigned char</code>.
* <code>%f</code> : Scan a floating-point number in normal ([[Fixed-point arithmetic|fixed-point]]) notation.
* <code>%g</code>, <code>%G</code> : Scan a floating-point number in either normal or exponential notation. <code>%g</code> uses lower-case letters and <code>%G</code> uses upper-case.
* <code>%x</code>, <code>%X</code> : Scan an integer as an unsigned [[Hexadecimal|hexadecimal]] number.
* <code>%o</code> : Scan an integer as an [[Octal|octal]] number.
* <code>%s</code> : Scan a character string. The scan terminates at whitespace.  A [[Null character|null character]] is stored at the end of the string, which means that the buffer supplied must be at least one character longer than the specified input length.
* <code>%c</code> : Scan a character (char). No [[Null character|null character]] is added.
* whitespace: Any whitespace characters trigger a scan for zero or more whitespace characters.  The number and type of whitespace characters do not need to match in either direction.
* <code>%lf</code> : Scan as a double floating-point number. "Float" format with the "long" specifier.
* <code>%Lf</code> : Scan as a [[Long double|long double]] floating-point number. "Float" format the "long long" specifier.
* <code>%n</code> : Nothing  is  expected. The number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to int.  This  is not a conversion and does not increase the count returned by the function.  


The above can be used in compound with numeric modifiers and the <code>l</code>, <code>L</code> modifiers which stand for "long" and "long long" in between the percent symbol and the letter. There can also be numeric values between the percent symbol and the letters, preceding the <code>long</code> modifiers if any, that specifies the number of characters to be scanned. An optional asterisk (<code>*</code>) right after the percent symbol denotes that the datum read by this format specifier is not to be stored in a variable. No argument behind the format string should be included for this dropped variable.

The <code>ff</code> modifier in printf is not present in scanf, causing differences between modes of input and output. The <code>ll</code> and <code>hh</code> modifiers are not present in the C90 standard, but are present in the C99 standard.<ref>C99 standard, §7.19.6.2 "The fscanf function" alinea 11.</ref>

An example of a format string is
:<code>"%7d%s %c%lf"</code>
The above format string scans the first seven characters as a decimal integer, then reads the remaining as a string until a space, newline, or tab is found, then consumes whitespace until the first non-whitespace character is found, then consumes that character, and finally scans the remaining characters as a [[Double-precision floating-point format|double]]. Therefore, a robust program must check whether the <code>scanf</code> call succeeded and take appropriate action. If the input was not in the correct format, the erroneous data will still be on the input stream and must discarded before new input can be read. An alternative method, which avoids this, is to use <code>fgets</code> and then examine the string read in. The last step can be done by <code>sscanf</code>, for example.

In the case of the many float type characters {{tt|a, e, f, g}}, many implementations choose to collapse most into the same parser. Microsoft MSVCRT does it with {{tt|e, f, g}},<ref>{{cite web |title=scanf Type Field Characters |url=https://docs.microsoft.com/en-us/cpp/c-runtime-library/scanf-type-field-characters?view=vs-2019 |website=docs.microsoft.com }}</ref> while [[Software:Glibc|glibc]] does so with all four.<ref name=linux>{{man|3|scanf|Linux}}</ref>

== Vulnerabilities ==
<code>scanf</code> is vulnerable to format string attacks. Great care should be taken to ensure that the formatting string includes limitations for string and array sizes. In most cases the input string size from a user is arbitrary and cannot be determined before the <code>scanf</code> function is executed. This means that <code>%s</code> placeholders without length specifiers are inherently insecure and exploitable for buffer overflows. Another potential problem is to allow dynamic formatting strings, for example formatting strings stored in configuration files or other user-controlled files. In this case the allowed input length of string sizes cannot be specified unless the formatting string is checked beforehand and limitations are enforced. Related to this are additional or mismatched formatting placeholders which do not match the actual vararg list. These placeholders might be partially extracted from the stack or contain undesirable or even insecure pointers, depending on the particular implementation of varargs.

==See also==

* C programming language
* Format string attack
* [[Software:Printf format string|Printf format string]]
* [[String interpolation]]

==References==
{{Reflist}}

==External links==
*{{man|sh|scanf|SUS}}
* [http://en.cppreference.com/w/cpp/io/c/scanf C++ reference for <code>std::scanf</code>]

{{CProLang}}

[[Category:C standard library]]

{{Sourceattribution|Scanf format string|1}}