| 1 | .\" Copyright (c) 1990, 1991, 1993 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" This code is derived from software contributed to Berkeley by |
| 5 | .\" Chris Torek and the American National Standards Committee X3, |
| 6 | .\" on Information Processing Systems. |
| 7 | .\" |
| 8 | .\" %sccs.include.redist.man% |
| 9 | .\" |
| 10 | .\" @(#)scanf.3 8.2 (Berkeley) %G% |
| 11 | .\" |
| 12 | .Dd |
| 13 | .Dt SCANF 3 |
| 14 | .Os |
| 15 | .Sh NAME |
| 16 | .Nm scanf , |
| 17 | .Nm fscanf , |
| 18 | .Nm sscanf , |
| 19 | .Nm vscanf , |
| 20 | .Nm vsscanf , |
| 21 | .Nm vfscanf |
| 22 | .Nd input format conversion |
| 23 | .Sh SYNOPSIS |
| 24 | .Fd #include <stdio.h> |
| 25 | .Ft int |
| 26 | .Fn scanf "const char *format" ... |
| 27 | .Ft int |
| 28 | .Fn fscanf "FILE *stream" "const char *format" ... |
| 29 | .Ft int |
| 30 | .Fn sscanf "const char *str" "const char *format" ... |
| 31 | .Fd #include <stdarg.h> |
| 32 | .Ft int |
| 33 | .Fn vscanf "const char *format" "va_list ap" |
| 34 | .Ft int |
| 35 | .Fn vsscanf "const char *str" "const char *format" "va_list ap" |
| 36 | .Ft int |
| 37 | .Fn vfscanf "FILE *stream" "const char *format" "va_list ap" |
| 38 | .Sh DESCRIPTION |
| 39 | The |
| 40 | .Fn scanf |
| 41 | family of functions scans input according to a |
| 42 | .Fa format |
| 43 | as described below. |
| 44 | This format may contain |
| 45 | .Em conversion specifiers ; |
| 46 | the results from such conversions, if any, |
| 47 | are stored through the |
| 48 | .Em pointer |
| 49 | arguments. |
| 50 | The |
| 51 | .Fn scanf |
| 52 | function |
| 53 | reads input from the standard input stream |
| 54 | .Em stdin , |
| 55 | .Fn fscanf |
| 56 | reads input from the stream pointer |
| 57 | .Fa stream , |
| 58 | and |
| 59 | .Fn sscanf |
| 60 | reads its input from the character string pointed to by |
| 61 | .Fa str . |
| 62 | The |
| 63 | .Fn vfscanf |
| 64 | function |
| 65 | is analogous to |
| 66 | .Xr vfprintf 3 |
| 67 | and reads input from the stream pointer |
| 68 | .Fa stream |
| 69 | using a variable argument list of pointers (see |
| 70 | .Xr stdarg 3 ) . |
| 71 | The |
| 72 | .Fn vscanf |
| 73 | function scans a variable argument list from the standard input and |
| 74 | the |
| 75 | .Fn vsscanf |
| 76 | function scans it from a string; |
| 77 | these are analogous to |
| 78 | the |
| 79 | .Fn vprintf |
| 80 | and |
| 81 | .Fn vsprintf |
| 82 | functions respectively. |
| 83 | Each successive |
| 84 | .Em pointer |
| 85 | argument must correspond properly with |
| 86 | each successive conversion specifier |
| 87 | (but see `suppression' below). |
| 88 | All conversions are introduced by the |
| 89 | .Cm % |
| 90 | (percent sign) character. |
| 91 | The |
| 92 | .Fa format |
| 93 | string |
| 94 | may also contain other characters. |
| 95 | White space (such as blanks, tabs, or newlines) in the |
| 96 | .Fa format |
| 97 | string match any amount of white space, including none, in the input. |
| 98 | Everything else |
| 99 | matches only itself. |
| 100 | Scanning stops |
| 101 | when an input character does not match such a format character. |
| 102 | Scanning also stops |
| 103 | when an input conversion cannot be made (see below). |
| 104 | .Sh CONVERSIONS |
| 105 | Following the |
| 106 | .Cm % |
| 107 | character introducing a conversion |
| 108 | there may be a number of |
| 109 | .Em flag |
| 110 | characters, as follows: |
| 111 | .Bl -tag -width indent |
| 112 | .It Cm * |
| 113 | Suppresses assignment. |
| 114 | The conversion that follows occurs as usual, but no pointer is used; |
| 115 | the result of the conversion is simply discarded. |
| 116 | .It Cm h |
| 117 | Indicates that the conversion will be one of |
| 118 | .Cm dioux |
| 119 | or |
| 120 | .Cm n |
| 121 | and the next pointer is a pointer to a |
| 122 | .Em short int |
| 123 | (rather than |
| 124 | .Em int ) . |
| 125 | .It Cm l |
| 126 | Indicates either that the conversion will be one of |
| 127 | .Cm dioux |
| 128 | or |
| 129 | .Cm n |
| 130 | and the next pointer is a pointer to a |
| 131 | .Em long int |
| 132 | (rather than |
| 133 | .Em int ) , |
| 134 | or that the conversion will be one of |
| 135 | .Cm efg |
| 136 | and the next pointer is a pointer to |
| 137 | .Em double |
| 138 | (rather than |
| 139 | .Em float ) . |
| 140 | .It Cm L |
| 141 | Indicates that the conversion will be |
| 142 | .Cm efg |
| 143 | and the next pointer is a pointer to |
| 144 | .Em long double . |
| 145 | (This type is not implemented; the |
| 146 | .Cm L |
| 147 | flag is currently ignored.) |
| 148 | .El |
| 149 | .Pp |
| 150 | In addition to these flags, |
| 151 | there may be an optional maximum field width, |
| 152 | expressed as a decimal integer, |
| 153 | between the |
| 154 | .Cm % |
| 155 | and the conversion. |
| 156 | If no width is given, |
| 157 | a default of `infinity' is used (with one exception, below); |
| 158 | otherwise at most this many characters are scanned |
| 159 | in processing the conversion. |
| 160 | Before conversion begins, |
| 161 | most conversions skip white space; |
| 162 | this white space is not counted against the field width. |
| 163 | .Pp |
| 164 | The following conversions are available: |
| 165 | .Bl -tag -width XXXX |
| 166 | .It Cm % |
| 167 | Matches a literal `%'. |
| 168 | That is, `%\&%' in the format string |
| 169 | matches a single input `%' character. |
| 170 | No conversion is done, and assignment does not occur. |
| 171 | .It Cm d |
| 172 | Matches an optionally signed decimal integer; |
| 173 | the next pointer must be a pointer to |
| 174 | .Em int . |
| 175 | .It Cm D |
| 176 | Equivalent to |
| 177 | .Xr ld ; |
| 178 | this exists only for backwards compatibility. |
| 179 | .It Cm i |
| 180 | Matches an optionally signed integer; |
| 181 | the next pointer must be a pointer to |
| 182 | .Em int . |
| 183 | The integer is read in base 16 if it begins |
| 184 | with |
| 185 | .Ql 0x |
| 186 | or |
| 187 | .Ql 0X , |
| 188 | in base 8 if it begins with |
| 189 | .Ql 0 , |
| 190 | and in base 10 otherwise. |
| 191 | Only characters that correspond to the base are used. |
| 192 | .It Cm o |
| 193 | Matches an octal integer; |
| 194 | the next pointer must be a pointer to |
| 195 | .Em unsigned int . |
| 196 | .It Cm O |
| 197 | Equivalent to |
| 198 | .Xr lo ; |
| 199 | this exists for backwards compatibility. |
| 200 | .It Cm u |
| 201 | Matches an optionally signed decimal integer; |
| 202 | the next pointer must be a pointer to |
| 203 | .Em unsigned int . |
| 204 | .It Cm x |
| 205 | Matches an optionally signed hexadecimal integer; |
| 206 | the next pointer must be a pointer to |
| 207 | .Em unsigned int . |
| 208 | .It Cm X |
| 209 | Equivalent to |
| 210 | .Cm lx ; |
| 211 | this violates the |
| 212 | .St -ansiC , |
| 213 | but is backwards compatible with previous |
| 214 | .Ux |
| 215 | systems. |
| 216 | .It Cm f |
| 217 | Matches an optionally signed floating-point number; |
| 218 | the next pointer must be a pointer to |
| 219 | .Em float . |
| 220 | .It Cm e |
| 221 | Equivalent to |
| 222 | .Cm f . |
| 223 | .It Cm g |
| 224 | Equivalent to |
| 225 | .Cm f . |
| 226 | .It Cm E |
| 227 | Equivalent to |
| 228 | .Cm lf ; |
| 229 | this violates the |
| 230 | .St -ansiC , |
| 231 | but is backwards compatible with previous |
| 232 | .Ux |
| 233 | systems. |
| 234 | .It Cm F |
| 235 | Equivalent to |
| 236 | .Cm lf ; |
| 237 | this exists only for backwards compatibility. |
| 238 | .It Cm s |
| 239 | Matches a sequence of non-white-space characters; |
| 240 | the next pointer must be a pointer to |
| 241 | .Em char , |
| 242 | and the array must be large enough to accept all the sequence and the |
| 243 | terminating |
| 244 | .Dv NUL |
| 245 | character. |
| 246 | The input string stops at white space |
| 247 | or at the maximum field width, whichever occurs first. |
| 248 | .It Cm c |
| 249 | Matches a sequence of |
| 250 | .Em width |
| 251 | count |
| 252 | characters (default 1); |
| 253 | the next pointer must be a pointer to |
| 254 | .Em char , |
| 255 | and there must be enough room for all the characters |
| 256 | (no terminating |
| 257 | .Dv NUL |
| 258 | is added). |
| 259 | The usual skip of leading white space is suppressed. |
| 260 | To skip white space first, use an explicit space in the format. |
| 261 | .It Cm \&[ |
| 262 | Matches a nonempty sequence of characters from the specified set |
| 263 | of accepted characters; |
| 264 | the next pointer must be a pointer to |
| 265 | .Em char , |
| 266 | and there must be enough room for all the characters in the string, |
| 267 | plus a terminating |
| 268 | .Dv NUL |
| 269 | character. |
| 270 | The usual skip of leading white space is suppressed. |
| 271 | The string is to be made up of characters in |
| 272 | (or not in) |
| 273 | a particular set; |
| 274 | the set is defined by the characters between the open bracket |
| 275 | .Cm [ |
| 276 | character |
| 277 | and a close bracket |
| 278 | .Cm ] |
| 279 | character. |
| 280 | The set |
| 281 | .Em excludes |
| 282 | those characters |
| 283 | if the first character after the open bracket is a circumflex |
| 284 | .Cm ^ . |
| 285 | To include a close bracket in the set, |
| 286 | make it the first character after the open bracket |
| 287 | or the circumflex; |
| 288 | any other position will end the set. |
| 289 | The hyphen character |
| 290 | .Cm - |
| 291 | is also special; |
| 292 | when placed between two other characters, |
| 293 | it adds all intervening characters to the set. |
| 294 | To include a hyphen, |
| 295 | make it the last character before the final close bracket. |
| 296 | For instance, |
| 297 | .Ql [^]0-9-] |
| 298 | means the set `everything except close bracket, zero through nine, |
| 299 | and hyphen'. |
| 300 | The string ends with the appearance of a character not in the |
| 301 | (or, with a circumflex, in) set |
| 302 | or when the field width runs out. |
| 303 | .It Cm p |
| 304 | Matches a pointer value (as printed by |
| 305 | .Ql %p |
| 306 | in |
| 307 | .Xr printf 3 ) ; |
| 308 | the next pointer must be a pointer to |
| 309 | .Em void . |
| 310 | .It Cm n |
| 311 | Nothing is expected; |
| 312 | instead, the number of characters consumed thus far from the input |
| 313 | is stored through the next pointer, |
| 314 | which must be a pointer to |
| 315 | .Em int . |
| 316 | This is |
| 317 | .Em not |
| 318 | a conversion, although it can be suppressed with the |
| 319 | .Cm * |
| 320 | flag. |
| 321 | .El |
| 322 | .Pp |
| 323 | For backwards compatibility, |
| 324 | other conversion characters (except |
| 325 | .Ql \e0 ) |
| 326 | are taken as if they were |
| 327 | .Ql %d |
| 328 | or, if uppercase, |
| 329 | .Ql %ld , |
| 330 | and a `conversion' of |
| 331 | .Ql %\e0 |
| 332 | causes an immediate return of |
| 333 | .Dv EOF . |
| 334 | The |
| 335 | .Cm F |
| 336 | and |
| 337 | .Cm X |
| 338 | conversions will be changed in the future |
| 339 | to conform to the |
| 340 | .Tn ANSI |
| 341 | C standard, |
| 342 | after which they will act like |
| 343 | .Cm f |
| 344 | and |
| 345 | .Cm x |
| 346 | respectively. |
| 347 | .Pp |
| 348 | .Sh RETURN VALUES |
| 349 | These |
| 350 | functions |
| 351 | return |
| 352 | the number of input items assigned, which can be fewer than provided |
| 353 | for, or even zero, in the event of a matching failure. |
| 354 | Zero |
| 355 | indicates that, while there was input available, |
| 356 | no conversions were assigned; |
| 357 | typically this is due to an invalid input character, |
| 358 | such as an alphabetic character for a |
| 359 | .Ql %d |
| 360 | conversion. |
| 361 | The value |
| 362 | .Dv EOF |
| 363 | is returned if an input failure occurs before any conversion such as an |
| 364 | end-of-file occurs. If an error or end-of-file occurs after conversion |
| 365 | has begun, |
| 366 | the number of conversions which were successfully completed is returned. |
| 367 | .Sh SEE ALSO |
| 368 | .Xr strtol 3 , |
| 369 | .Xr strtoul 3 , |
| 370 | .Xr strtod 3 , |
| 371 | .Xr getc 3 , |
| 372 | .Xr printf 3 |
| 373 | .Sh STANDARDS |
| 374 | The functions |
| 375 | .Fn fscanf , |
| 376 | .Fn scanf , |
| 377 | and |
| 378 | .Fn sscanf |
| 379 | conform to |
| 380 | .St -ansiC . |
| 381 | .Sh HISTORY |
| 382 | The functions |
| 383 | .Fn vscanf , |
| 384 | .Fn vsscanf |
| 385 | and |
| 386 | .Fn vfscanf |
| 387 | are new to this release. |
| 388 | .Sh BUGS |
| 389 | The current situation with |
| 390 | .Cm %F |
| 391 | and |
| 392 | .Cm %X |
| 393 | conversions is unfortunate. |
| 394 | .Pp |
| 395 | All of the backwards compatibility formats will be removed in the future. |
| 396 | .Pp |
| 397 | Numerical strings are truncated to 512 characters; for example, |
| 398 | .Cm %f |
| 399 | and |
| 400 | .Cm %d |
| 401 | are implicitly |
| 402 | .Cm %512f |
| 403 | and |
| 404 | .Cm %512d . |