466
+ − 1 <refentry id="scanf">
+ − 2 <refnamediv>
574
+ − 3 <refname>Scanf</refname>
+ − 4 <refname>Fscanf</refname>
+ − 5 <refname>Sscanf</refname>
+ − 6 <refpurpose>input string interpretation</refpurpose>
466
+ − 7 </refnamediv>
+ − 8
+ − 9 <refsynopsisdiv>
+ − 10 <funcsynopsis>
468
+ − 11 <funcsynopsisinfo>
+ − 12 #include <stdio.h>
+ − 13 </funcsynopsisinfo>
466
+ − 14 <funcprototype>
574
+ − 15 <funcdef><function>fscanf</function></funcdef>
+ − 16 <paramdef>FILE *<parameter>fp</parameter></paramdef>
+ − 17 <paramdef>char *<parameter>control</parameter></paramdef>
+ − 18 <paramdef>char *<parameter>pointer...</parameter></paramdef>
+ − 19 </funcprototype>
+ − 20
+ − 21 <funcprototype>
466
+ − 22 <funcdef><function>scanf</function></funcdef>
574
+ − 23 <paramdef>char *<parameter>control</parameter></paramdef>
+ − 24 <paramdef>char *<parameter>pointer...</parameter></paramdef>
466
+ − 25 </funcprototype>
574
+ − 26
+ − 27 <funcprototype>
+ − 28 <funcdef><function>sscanf</function></funcdef>
+ − 29 <paramdef>char *<parameter>string</parameter></paramdef>
+ − 30 <paramdef>char *<parameter>control</parameter></paramdef>
+ − 31 <paramdef>char *<parameter>pointer...</parameter></paramdef>
+ − 32 </funcprototype>
+ − 33
466
+ − 34 </funcsynopsis>
+ − 35
+ − 36 </refsynopsisdiv>
+ − 37
+ − 38 <refsect1><title>Description</title>
+ − 39 <para>
640
+ − 40 These functions perform the complement to "printf()" etc.
466
+ − 41 </para>
605
+ − 42 <para>
+ − 43 Fscanf performs conversions from the file "fp", scanf from the
+ − 44 standard input, and sscanf from the string pointed to by
+ − 45 "string".
+ − 46 </para>
+ − 47 <para>
+ − 48 Each function expects a control string containing conversion
+ − 49 specifications, and zero or more pointers to objects into which
+ − 50 the converted values are stored.
+ − 51 </para>
+ − 52 <para>
+ − 53 The control string may contain three types of fields:
+ − 54 <orderedlist numeration="loweralpha" spacing="compact">
+ − 55 <listitem><para>
+ − 56 Space, tab characters, or "\n" which match any of
+ − 57 the three in the input.
+ − 58 </para></listitem>
+ − 59 <listitem><para>
+ − 60 Characters not among the above and not "%" which must
+ − 61 match characters in the input.
+ − 62 </para></listitem>
+ − 63 <listitem><para>
+ − 64 A "%" followed by an optional "*" indicates
+ − 65 suppression of assignment, an optional field width
+ − 66 maximum and a conversion character indicating the
+ − 67 type expected.
+ − 68 </para></listitem>
+ − 69 </orderedlist>
+ − 70 </para>
+ − 71 <para>
+ − 72 A conversion character controls the conversion to be applied
+ − 73 to the next field and indicates the type of the corresponding
+ − 74 pointer argument. A field consists of consecutive non-space
+ − 75 characters and ends at either a character inappropiate for the
+ − 76 conversion or when a specified field is exhausted.
+ − 77 When one field is finished, white-space characters are passed
+ − 78 over until the next field is found.
+ − 79 </para>
+ − 80 <informaltable frame="none">
+ − 81 <tgroup cols="2">
640
+ − 82 <colspec colwidth="0.5in"/>
+ − 83 <colspec colwidth="3.5in"/>
605
+ − 84 <tbody>
+ − 85 <row>
+ − 86 <entry>d</entry>
+ − 87 <entry>A decimal string is to be converted to an integer.</entry>
+ − 88 </row>
+ − 89 <row>
+ − 90 <entry>o</entry>
+ − 91 <entry>An octal string; the coresponding argument should
+ − 92 point to an integer.</entry>
+ − 93 </row>
+ − 94 <row>
+ − 95 <entry>x</entry>
+ − 96 <entry>A hexadecimal string for conversion to an integer.</entry>
+ − 97 </row>
+ − 98 <row>
+ − 99 <entry>s</entry>
+ − 100 <entry>A string of non-space characters is expected and
+ − 101 will be copied to the buffer pointed to by the
+ − 102 corresponding argument and a null ("\0") appended.
+ − 103 The user must ensure that the buffer is large
+ − 104 enough. The input string is considered terminated
+ − 105 by a space, tab of ("\n").</entry>
+ − 106 </row>
+ − 107 <row>
+ − 108 <entry>c</entry>
+ − 109 <entry>A character is expected and is copied into the byte
+ − 110 pointed to by the argument. The white-space
+ − 111 skipping is suppressed for this conversion. If a
+ − 112 field width is given, the argument is assumed to
+ − 113 point to a character array and the number of
+ − 114 characters indicated is copied to it. NOTE to ensure
+ − 115 that the next non-white-space character is read use
+ − 116 "%1s" and that TWO bytes are pointed to by the
+ − 117 argument.</entry>
+ − 118 </row>
+ − 119 <row>
+ − 120 <entry>e,f</entry>
+ − 121 <entry>A floating point representation is expected on the
+ − 122 input and the argument must be a pointer to a float.
+ − 123 Any of the usual ways of writing floating point
+ − 124 numbers are recognized.</entry>
+ − 125 </row>
+ − 126 <row>
+ − 127 <entry>[</entry>
+ − 128 <entry>This denotes the start of a set of match characters;
+ − 129 the inclusion or exclusion of which delimits the
+ − 130 input field. The white-space skipping is
+ − 131 suppressed. The corresponding argument should be a
+ − 132 pointer to a character array. If the first
+ − 133 character in the match string is not "^",
+ − 134 characters are copied from the input as long as they
+ − 135 can be found in the match string. If the first
+ − 136 character is the "^", copying continues while characters
+ − 137 cannot be found in the match string. The match
+ − 138 string is delimited by a "]".</entry>
+ − 139 </row>
+ − 140 <row>
+ − 141 <entry>D,O,X</entry>
+ − 142 <entry>Similar to d,o,x above, but the corresponding
+ − 143 argument is considered to point to a long integer.</entry>
+ − 144 </row>
+ − 145 <row>
+ − 146 <entry>E,F</entry>
+ − 147 <entry>Similar to e,f above, but the corresponding
+ − 148 should point to a double.</entry>
+ − 149 </row>
+ − 150 <row>
+ − 151 <entry>%</entry>
+ − 152 <entry>A match for "%" is sought; no conversion takes place.</entry>
+ − 153 </row>
+ − 154 </tbody>
+ − 155 </tgroup>
+ − 156 </informaltable>
+ − 157 <para>
+ − 158 Each of the functions returns a count of the number of
+ − 159 fields successfully matched and assigned.
+ − 160 </para>
+ − 161 </refsect1>
+ − 162
+ − 163 <refsect1><title>Caveats</title>
+ − 164 <para>
+ − 165 The returned count of matches/assigments does not include
+ − 166 character matches and assigments suppressed by "*". The
+ − 167 arguments must ALL be pointers. It is a common error to call
+ − 168 scanf with the value of an item rather than a pointer to it.
+ − 169 </para>
466
+ − 170 </refsect1>
542
+ − 171
552
+ − 172 <refsect1><title>Diagnostics</title>
+ − 173 <para>
+ − 174 These functions return EOF on end of input or error and a count
+ − 175 which is shorter than expected for unexpected or unmatched
+ − 176 items.
+ − 177 </para>
+ − 178 </refsect1>
+ − 179
542
+ − 180 <refsect1><title>See Also</title>
+ − 181 <para>
605
+ − 182 <link linkend="atof">Atoi(), atof()</link>,
542
+ − 183 <link linkend="getc">getc()</link>,
+ − 184 <link linkend="printf">printf()</link>
+ − 185 Kernighan and Ritchie pp 147-150
+ − 186 </para>
+ − 187 </refsect1>
+ − 188
466
+ − 189 </refentry>