1<html lang="en"> 2<head> 3<title>sscanf - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Stdio.html#Stdio" title="Stdio"> 9<link rel="prev" href="sprintf.html#sprintf" title="sprintf"> 10<link rel="next" href="swprintf.html#swprintf" title="swprintf"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<meta http-equiv="Content-Style-Type" content="text/css"> 13<style type="text/css"><!-- 14 pre.display { font-family:inherit } 15 pre.format { font-family:inherit } 16 pre.smalldisplay { font-family:inherit; font-size:smaller } 17 pre.smallformat { font-family:inherit; font-size:smaller } 18 pre.smallexample { font-size:smaller } 19 pre.smalllisp { font-size:smaller } 20 span.sc { font-variant:small-caps } 21 span.roman { font-family:serif; font-weight:normal; } 22 span.sansserif { font-family:sans-serif; font-weight:normal; } 23--></style> 24<link rel="stylesheet" type="text/css" href="../cs.css"> 25</head> 26<body> 27<div class="node"> 28<a name="sscanf"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="swprintf.html#swprintf">swprintf</a>, 31Previous: <a rel="previous" accesskey="p" href="sprintf.html#sprintf">sprintf</a>, 32Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> 33<hr> 34</div> 35 36<h3 class="section">4.61 <code>sscanf</code>, <code>fscanf</code>, <code>scanf</code>—scan and format input</h3> 37 38<p><a name="index-scanf-297"></a><a name="index-g_t_005fscanf_005fr-298"></a><a name="index-fscanf-299"></a><a name="index-g_t_005ffscanf_005fr-300"></a><a name="index-sscanf-301"></a><a name="index-g_t_005fsscanf_005fr-302"></a><strong>Synopsis</strong> 39<pre class="example"> #include <stdio.h> 40 41 int scanf(const char *<var>format</var>, ...); 42 int fscanf(FILE *<var>fd</var>, const char *<var>format</var>, ...); 43 int sscanf(const char *<var>str</var>, const char *<var>format</var>, ...); 44 45 int _scanf_r(struct _reent *<var>ptr</var>, const char *<var>format</var>, ...); 46 int _fscanf_r(struct _reent *<var>ptr</var>, FILE *<var>fd</var>, 47 const char *<var>format</var>, ...); 48 int _sscanf_r(struct _reent *<var>ptr</var>, const char *<var>str</var>, 49 const char *<var>format</var>, ...); 50 51</pre> 52 <p><strong>Description</strong><br> 53<code>scanf</code> scans a series of input fields from standard input, 54one character at a time. Each field is interpreted according to 55a format specifier passed to <code>scanf</code> in the format string at 56<code>*</code><var>format</var>. <code>scanf</code> stores the interpreted input from 57each field at the address passed to it as the corresponding argument 58following <var>format</var>. You must supply the same number of 59format specifiers and address arguments as there are input fields. 60 61 <p>There must be sufficient address arguments for the given format 62specifiers; if not the results are unpredictable and likely 63disasterous. Excess address arguments are merely ignored. 64 65 <p><code>scanf</code> often produces unexpected results if the input diverges from 66an expected pattern. Since the combination of <code>gets</code> or <code>fgets</code> 67followed by <code>sscanf</code> is safe and easy, that is the preferred way 68to be certain that a program is synchronized with input at the end 69of a line. 70 71 <p><code>fscanf</code> and <code>sscanf</code> are identical to <code>scanf</code>, other than the 72source of input: <code>fscanf</code> reads from a file, and <code>sscanf</code> 73from a string. 74 75 <p>The routines <code>_scanf_r</code>, <code>_fscanf_r</code>, and <code>_sscanf_r</code> are reentrant 76versions of <code>scanf</code>, <code>fscanf</code>, and <code>sscanf</code> that take an additional 77first argument pointing to a reentrancy structure. 78 79 <p>The string at <code>*</code><var>format</var> is a character sequence composed 80of zero or more directives. Directives are composed of 81one or more whitespace characters, non-whitespace characters, 82and format specifications. 83 84 <p>Whitespace characters are blank ( ), tab (<code>\t</code>), or 85newline (<code>\n</code>). 86When <code>scanf</code> encounters a whitespace character in the format string 87it will read (but not store) all consecutive whitespace characters 88up to the next non-whitespace character in the input. 89 90 <p>Non-whitespace characters are all other ASCII characters except the 91percent sign (<code>%</code>). When <code>scanf</code> encounters a non-whitespace 92character in the format string it will read, but not store 93a matching non-whitespace character. 94 95 <p>Format specifications tell <code>scanf</code> to read and convert characters 96from the input field into specific types of values, and store then 97in the locations specified by the address arguments. 98 99 <p>Trailing whitespace is left unread unless explicitly 100matched in the format string. 101 102 <p>The format specifiers must begin with a percent sign (<code>%</code>) 103and have the following form: 104 105<pre class="smallexample"> %[*][<var>width</var>][<var>size</var>]<var>type</var> 106</pre> 107 <p>Each format specification begins with the percent character (<code>%</code>). 108The other fields are: 109 <dl> 110<dt><code>*</code><dd>an optional marker; if present, it suppresses interpretation and 111assignment of this input field. 112 113 <br><dt><var>width</var><dd>an optional maximum field width: a decimal integer, 114which controls the maximum number of characters that 115will be read before converting the current input field. If the 116input field has fewer than <var>width</var> characters, <code>scanf</code> 117reads all the characters in the field, and then 118proceeds with the next field and its format specification. 119 120 <p>If a whitespace or a non-convertable character occurs 121before <var>width</var> character are read, the characters up 122to that character are read, converted, and stored. 123Then <code>scanf</code> proceeds to the next format specification. 124 125 <br><dt><code>size</code><dd><code>h</code>, <code>j</code>, <code>l</code>, <code>L</code>, <code>t</code>, and <code>z</code> are optional size 126characters which override the default way that <code>scanf</code> 127interprets the data type of the corresponding argument. 128 129 <pre class="smallexample"> Modifier Type(s) 130 hh d, i, o, u, x, n convert input to char, 131 store in char object 132 133 h d, i, o, u, x, n convert input to short, 134 store in short object 135 136 h D, I, O, U, X no effect 137 e, f, c, s, p 138 139 j d, i, o, u, x, n convert input to intmax_t, 140 store in intmax_t object 141 142 j all others no effect 143 144 l d, i, o, u, x, n convert input to long, 145 store in long object 146 147 l e, f, g convert input to double 148 store in a double object 149 150 l D, I, O, U, X no effect 151 c, s, p 152 153 ll d, i, o, u, x, n convert to long long, 154 store in long long 155 156 L d, i, o, u, x, n convert to long long, 157 store in long long 158 159 L e, f, g, E, G convert to long double, 160 store in long double 161 162 L all others no effect 163 164 t d, i, o, u, x, n convert input to ptrdiff_t, 165 store in ptrdiff_t object 166 167 t all others no effect 168 169 z d, i, o, u, x, n convert input to size_t, 170 store in size_t object 171 172 z all others no effect 173 174</pre> 175 <br><dt><var>type</var><dd> 176A character to specify what kind of conversion 177<code>scanf</code> performs. Here is a table of the conversion 178characters: 179 180 <dl> 181<dt><code>%</code><dd>No conversion is done; the percent character (<code>%</code>) is stored. 182 183 <br><dt><code>c</code><dd>Scans one character. Corresponding <var>arg</var>: <code>(char *arg)</code>. 184 185 <br><dt><code>s</code><dd>Reads a character string into the array supplied. 186Corresponding <var>arg</var>: <code>(char arg[])</code>. 187 188 <br><dt><code>[</code><var>pattern</var><code>]</code><dd>Reads a non-empty character string into memory 189starting at <var>arg</var>. This area must be large 190enough to accept the sequence and a 191terminating null character which will be added 192automatically. (<var>pattern</var> is discussed in the paragraph following 193this table). Corresponding <var>arg</var>: <code>(char *arg)</code>. 194 195 <br><dt><code>d</code><dd>Reads a decimal integer into the corresponding <var>arg</var>: <code>(int *arg)</code>. 196 197 <br><dt><code>D</code><dd>Reads a decimal integer into the corresponding 198<var>arg</var>: <code>(long *arg)</code>. 199 200 <br><dt><code>o</code><dd>Reads an octal integer into the corresponding <var>arg</var>: <code>(int *arg)</code>. 201 202 <br><dt><code>O</code><dd>Reads an octal integer into the corresponding <var>arg</var>: <code>(long *arg)</code>. 203 204 <br><dt><code>u</code><dd>Reads an unsigned decimal integer into the corresponding 205<var>arg</var>: <code>(unsigned int *arg)</code>. 206<br><dt><code>U</code><dd>Reads an unsigned decimal integer into the corresponding <var>arg</var>: 207<code>(unsigned long *arg)</code>. 208 209 <br><dt><code>x,X</code><dd>Read a hexadecimal integer into the corresponding <var>arg</var>: 210<code>(int *arg)</code>. 211 212 <br><dt><code>e, f, g</code><dd>Read a floating-point number into the corresponding <var>arg</var>: 213<code>(float *arg)</code>. 214 215 <br><dt><code>E, F, G</code><dd>Read a floating-point number into the corresponding <var>arg</var>: 216<code>(double *arg)</code>. 217 218 <br><dt><code>i</code><dd>Reads a decimal, octal or hexadecimal integer into the 219corresponding <var>arg</var>: <code>(int *arg)</code>. 220 221 <br><dt><code>I</code><dd>Reads a decimal, octal or hexadecimal integer into the 222corresponding <var>arg</var>: <code>(long *arg)</code>. 223 224 <br><dt><code>n</code><dd>Stores the number of characters read in the corresponding 225<var>arg</var>: <code>(int *arg)</code>. 226 227 <br><dt><code>p</code><dd>Stores a scanned pointer. ANSI C leaves the details 228to each implementation; this implementation treats 229<code>%p</code> exactly the same as <code>%U</code>. Corresponding 230<var>arg</var>: <code>(void **arg)</code>. 231</dl> 232 233 <p>A <var>pattern</var> of characters surrounded by square brackets can be used 234instead of the <code>s</code> type character. <var>pattern</var> is a set of 235characters which define a search set of possible characters making up 236the <code>scanf</code> input field. If the first character in the brackets is a 237caret (<code>^</code>), the search set is inverted to include all ASCII characters 238except those between the brackets. There is also a range facility 239which you can use as a shortcut. <code>%[0-9] </code> matches all decimal digits. 240The hyphen must not be the first or last character in the set. 241The character prior to the hyphen must be lexically less than the 242character after it. 243 244 <p>Here are some <var>pattern</var> examples: 245 <dl> 246<dt><code>%[abcd]</code><dd>matches strings containing only <code>a</code>, <code>b</code>, <code>c</code>, and <code>d</code>. 247 248 <br><dt><code>%[^abcd]</code><dd>matches strings containing any characters except <code>a</code>, <code>b</code>, 249<code>c</code>, or <code>d</code> 250 251 <br><dt><code>%[A-DW-Z]</code><dd>matches strings containing <code>A</code>, <code>B</code>, <code>C</code>, <code>D</code>, <code>W</code>, 252<code>X</code>, <code>Y</code>, <code>Z</code> 253 254 <br><dt><code>%[z-a]</code><dd>matches the characters <code>z</code>, <code>-</code>, and <code>a</code> 255</dl> 256 257 <p>Floating point numbers (for field types <code>e</code>, <code>f</code>, <code>g</code>, <code>E</code>, 258<code>F</code>, <code>G</code>) must correspond to the following general form: 259 260 <pre class="smallexample"> [+/-] ddddd[.]ddd [E|e[+|-]ddd] 261</pre> 262 <p>where objects inclosed in square brackets are optional, and <code>ddd</code> 263represents decimal, octal, or hexadecimal digits. 264</dl> 265 266 <p><br> 267<strong>Returns</strong><br> 268<code>scanf</code> returns the number of input fields successfully 269scanned, converted and stored; the return value does 270not include scanned fields which were not stored. 271 272 <p>If <code>scanf</code> attempts to read at end-of-file, the return 273value is <code>EOF</code>. 274 275 <p>If no fields were stored, the return value is <code>0</code>. 276 277 <p><code>scanf</code> might stop scanning a particular field before 278reaching the normal field end character, or may 279terminate entirely. 280 281 <p><code>scanf</code> stops scanning and storing the current field 282and moves to the next input field (if any) 283in any of the following situations: 284 285 <ul> 286<li>The assignment suppressing character (<code>*</code>) appears 287after the <code>%</code> in the format specification; the current 288input field is scanned but not stored. 289 290 <li><var>width</var> characters have been read (<var>width</var> is a 291width specification, a positive decimal integer). 292 293 <li>The next character read cannot be converted 294under the the current format (for example, 295if a <code>Z</code> is read when the format is decimal). 296 297 <li>The next character in the input field does not appear 298in the search set (or does appear in the inverted search set). 299</ul> 300 301 <p>When <code>scanf</code> stops scanning the current input field for one of 302these reasons, the next character is considered unread and 303used as the first character of the following input field, or the 304first character in a subsequent read operation on the input. 305 306 <p><code>scanf</code> will terminate under the following circumstances: 307 308 <ul> 309<li>The next character in the input field conflicts 310with a corresponding non-whitespace character in the 311format string. 312 313 <li>The next character in the input field is <code>EOF</code>. 314 315 <li>The format string has been exhausted. 316</ul> 317 318 <p>When the format string contains a character sequence that is 319not part of a format specification, the same character 320sequence must appear in the input; <code>scanf</code> will 321scan but not store the matched characters. If a 322conflict occurs, the first conflicting character remains in the input 323as if it had never been read. 324 325 <p><br> 326<strong>Portability</strong><br> 327<code>scanf</code> is ANSI C. 328 329 <p>Supporting OS subroutines required: <code>close</code>, <code>fstat</code>, <code>isatty</code>, 330<code>lseek</code>, <code>read</code>, <code>sbrk</code>, <code>write</code>. 331 332 <p><br> 333 334 </body></html> 335 336