lib/libc/stdio/scanf.3

   1 .\"     $NetBSD: scanf.3,v 1.22 2009/12/14 04:40:29 dholland Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Chris Torek and the American National Standards Committee X3,
   8 .\" on Information Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)scanf.3     8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd December 14, 2009
  37 .Dt SCANF 3
  38 .Os
  39 .Sh NAME
  40 .Nm scanf ,
  41 .Nm fscanf ,
  42 .Nm sscanf ,
  43 .Nm vscanf ,
  44 .Nm vsscanf ,
  45 .Nm vfscanf
  46 .Nd input format conversion
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In stdio.h
  51 .Ft int
  52 .Fn scanf "const char * restrict format" ...
  53 .Ft int
  54 .Fn fscanf "FILE * restrict stream" "const char * restrict format" ...
  55 .Ft int
  56 .Fn sscanf "const char * restrict str" "const char * restrict format" ...
  57 .In stdarg.h
  58 .Ft int
  59 .Fn vscanf "const char * restrict format" "va_list ap"
  60 .Ft int
  61 .Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap"
  62 .Ft int
  63 .Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn scanf
  67 family of functions scans input according to a
  68 .Fa format
  69 as described below.
  70 This format may contain
  71 .Em conversion specifiers ;
  72 the results from such conversions, if any,
  73 are stored through the
  74 .Em pointer
  75 arguments.
  76 The
  77 .Fn scanf
  78 function
  79 reads input from the standard input stream
  80 .Em stdin ,
  81 .Fn fscanf
  82 reads input from the stream pointer
  83 .Fa stream ,
  84 and
  85 .Fn sscanf
  86 reads its input from the character string pointed to by
  87 .Fa str .
  88 The
  89 .Fn vfscanf
  90 function
  91 is analogous to
  92 .Xr vfprintf 3
  93 and reads input from the stream pointer
  94 .Fa stream
  95 using a variable argument list of pointers (see
  96 .Xr stdarg 3 ) .
  97 The
  98 .Fn vscanf
  99 function scans a variable argument list from the standard input and
 100 the
 101 .Fn vsscanf
 102 function scans it from a string;
 103 these are analogous to
 104 the
 105 .Fn vprintf
 106 and
 107 .Fn vsprintf
 108 functions respectively.
 109 Each successive
 110 .Em pointer
 111 argument must correspond properly with
 112 each successive conversion specifier
 113 (but see `suppression' below).
 114 All conversions are introduced by the
 115 .Cm %
 116 (percent sign) character.
 117 The
 118 .Fa format
 119 string
 120 may also contain other characters.
 121 White space (such as blanks, tabs, or newlines) in the
 122 .Fa format
 123 string match any amount of white space, including none, in the input.
 124 Everything else
 125 matches only itself.
 126 Scanning stops
 127 when an input character does not match such a format character.
 128 Scanning also stops
 129 when an input conversion cannot be made (see below).
 130 .Sh CONVERSIONS
 131 Following the
 132 .Cm %
 133 character introducing a conversion
 134 there may be a number of
 135 .Em flag
 136 characters, as follows:
 137 .Bl -tag -width indent
 138 .It Cm *
 139 Suppresses assignment.
 140 The conversion that follows occurs as usual, but no pointer is used;
 141 the result of the conversion is simply discarded.
 142 .It Cm h
 143 Indicates that the conversion will be one of
 144 .Cm dioux
 145 or
 146 .Cm n
 147 and the next pointer is a pointer to a
 148 .Em short int
 149 (rather than
 150 .Em int ) .
 151 .It Cm hh
 152 Indicates that the conversion will be one of
 153 .Cm dioux
 154 or
 155 .Cm n
 156 and the next pointer is a pointer to a
 157 .Em char
 158 (rather than
 159 .Em int ) .
 160 .It Cm j
 161 Indicates that the conversion will be one of
 162 .Cm dioux
 163 or
 164 .Cm n
 165 and the next pointer is a pointer to an
 166 .Em intmax_t
 167 (rather than
 168 .Em int ) .
 169 .It Cm l
 170 Indicates either that the conversion will be one of
 171 .Cm dioux
 172 or
 173 .Cm n
 174 and the next pointer is a pointer to a
 175 .Em long int
 176 (rather than
 177 .Em int ) ,
 178 or that the conversion will be one of
 179 .Cm efg
 180 and the next pointer is a pointer to
 181 .Em double
 182 (rather than
 183 .Em float ) .
 184 .It Cm ll
 185 Indicates that the conversion will be one of
 186 .Cm dioux
 187 or
 188 .Cm n
 189 and the next pointer is a pointer to a
 190 .Em long long int
 191 (rather than
 192 .Em int ) .
 193 .It Cm q
 194 Indicates that the conversion will be one of
 195 .Cm dioux
 196 or
 197 .Cm n
 198 and the next pointer is a pointer to a
 199 .Em quad_t
 200 (rather than
 201 .Em int ) .
 202 .It Cm t
 203 Indicates that the conversion will be one of
 204 .Cm dioux
 205 or
 206 .Cm n
 207 and the next pointer is a pointer to a
 208 .Em ptrdiff_t
 209 (rather than
 210 .Em int ) .
 211 .It Cm z
 212 Indicates that the conversion will be one of
 213 .Cm dioux
 214 or
 215 .Cm n
 216 and the next pointer is a pointer to a
 217 .Em size_t
 218 (rather than
 219 .Em int ) .
 220 .It Cm L
 221 Indicates that the conversion will be
 222 .Cm efg
 223 and the next pointer is a pointer to
 224 .Em long double .
 225 .El
 226 .Pp
 227 In addition to these flags,
 228 there may be an optional maximum field width,
 229 expressed as a decimal integer,
 230 between the
 231 .Cm %
 232 and the conversion.
 233 If no width is given,
 234 a default of `infinity' is used (with one exception, below);
 235 otherwise at most this many characters are scanned
 236 in processing the conversion.
 237 Before conversion begins,
 238 most conversions skip white space;
 239 this white space is not counted against the field width.
 240 .Pp
 241 The following conversions are available:
 242 .Bl -tag -width XXXX
 243 .It Cm %
 244 Matches a literal `%'.
 245 That is, `%\&%' in the format string
 246 matches a single input `%' character.
 247 No conversion is done, and assignment does not occur.
 248 .It Cm d
 249 Matches an optionally signed decimal integer;
 250 the next pointer must be a pointer to
 251 .Em int .
 252 .It Cm D
 253 Equivalent to
 254 .Cm ld ;
 255 this exists only for backwards compatibility.
 256 .It Cm i
 257 Matches an optionally signed integer;
 258 the next pointer must be a pointer to
 259 .Em int .
 260 The integer is read in base 16 if it begins
 261 with
 262 .Ql 0x
 263 or
 264 .Ql 0X ,
 265 in base 8 if it begins with
 266 .Ql 0 ,
 267 and in base 10 otherwise.
 268 Only characters that correspond to the base are used.
 269 .It Cm o
 270 Matches an octal integer;
 271 the next pointer must be a pointer to
 272 .Em unsigned int .
 273 .It Cm O
 274 Equivalent to
 275 .Cm lo ;
 276 this exists for backwards compatibility.
 277 .It Cm u
 278 Matches an optionally signed decimal integer;
 279 the next pointer must be a pointer to
 280 .Em unsigned int .
 281 .It Cm x
 282 Matches an optionally signed hexadecimal integer;
 283 the next pointer must be a pointer to
 284 .Em unsigned int .
 285 .It Cm X
 286 Equivalent to
 287 .Cm x .
 288 .It Cm f
 289 Matches an optionally signed floating-point number;
 290 the next pointer must be a pointer to
 291 .Em float .
 292 .It Cm e
 293 Equivalent to
 294 .Cm f .
 295 .It Cm g
 296 Equivalent to
 297 .Cm f .
 298 .It Cm E
 299 Equivalent to
 300 .Cm f .
 301 .It Cm G
 302 Equivalent to
 303 .Cm f .
 304 .It Cm s
 305 Matches a sequence of non-white-space characters;
 306 the next pointer must be a pointer to
 307 .Em char ,
 308 and the array must be large enough to accept all the sequence and the
 309 terminating
 310 .Dv NUL
 311 character.
 312 The input string stops at white space
 313 or at the maximum field width, whichever occurs first.
 314 .It Cm c
 315 Matches a sequence of
 316 .Em width
 317 count
 318 characters (default 1);
 319 the next pointer must be a pointer to
 320 .Em char ,
 321 and there must be enough room for all the characters
 322 (no terminating
 323 .Dv NUL
 324 is added).
 325 The usual skip of leading white space is suppressed.
 326 To skip white space first, use an explicit space in the format.
 327 .It Cm \&[
 328 Matches a nonempty sequence of characters from the specified set
 329 of accepted characters;
 330 the next pointer must be a pointer to
 331 .Em char ,
 332 and there must be enough room for all the characters in the string,
 333 plus a terminating
 334 .Dv NUL
 335 character.
 336 The usual skip of leading white space is suppressed.
 337 The string is to be made up of characters in
 338 (or not in)
 339 a particular set;
 340 the set is defined by the characters between the open bracket
 341 .Cm [
 342 character
 343 and a close bracket
 344 .Cm ]
 345 character.
 346 The set
 347 .Em excludes
 348 those characters
 349 if the first character after the open bracket is a circumflex
 350 .Cm ^ .
 351 To include a close bracket in the set,
 352 make it the first character after the open bracket
 353 or the circumflex;
 354 any other position will end the set.
 355 The hyphen character
 356 .Cm -
 357 is also special;
 358 when placed between two other characters,
 359 it adds all intervening characters to the set.
 360 To include a hyphen,
 361 make it the last character before the final close bracket.
 362 For instance,
 363 .Ql [^]0-9-]
 364 means the set `everything except close bracket, zero through nine,
 365 and hyphen'.
 366 The string ends with the appearance of a character not in the
 367 (or, with a circumflex, in) set
 368 or when the field width runs out.
 369 .It Cm p
 370 Matches a pointer value (as printed by
 371 .Ql %p
 372 in
 373 .Xr printf 3 ) ;
 374 the next pointer must be a pointer to
 375 .Em void .
 376 .It Cm n
 377 Nothing is expected;
 378 instead, the number of characters consumed thus far from the input
 379 is stored through the next pointer,
 380 which must be a pointer to
 381 .Em int .
 382 This is
 383 .Em not
 384 a conversion, although it can be suppressed with the
 385 .Cm *
 386 flag.
 387 .El
 388 .Pp
 389 For backwards compatibility,
 390 other conversion characters (except
 391 .Ql \e0 )
 392 are taken as if they were
 393 .Ql %d
 394 or, if uppercase,
 395 .Ql %ld ,
 396 and a `conversion' of
 397 .Ql %\e0
 398 causes an immediate return of
 399 .Dv EOF .
 400 .Sh RETURN VALUES
 401 These
 402 functions
 403 return
 404 the number of input items assigned, which can be fewer than provided
 405 for, or even zero, in the event of a matching failure.
 406 Zero
 407 indicates that, while there was input available,
 408 no conversions were assigned;
 409 typically this is due to an invalid input character,
 410 such as an alphabetic character for a
 411 .Ql %d
 412 conversion.
 413 The value
 414 .Dv EOF
 415 is returned if an input failure occurs before any conversion such as an
 416 end-of-file occurs.
 417 If an error or end-of-file occurs after conversion has begun,
 418 the number of conversions which were successfully completed is returned.
 419 .Sh SEE ALSO
 420 .Xr getc 3 ,
 421 .Xr printf 3 ,
 422 .Xr strtod 3 ,
 423 .Xr strtol 3 ,
 424 .Xr strtoul 3
 425 .Sh STANDARDS
 426 The functions
 427 .Fn fscanf ,
 428 .Fn scanf ,
 429 and
 430 .Fn sscanf
 431 conform to
 432 .St -isoC-90 .
 433 The
 434 .Cm %j ,
 435 .Cm %t
 436 and
 437 .Cm %z
 438 conversion format modifiers
 439 conform to
 440 .St -isoC-99 .
 441 The
 442 .Fn vfscanf ,
 443 .Fn vscanf
 444 and
 445 .Fn vsscanf
 446 functions conform to
 447 .St -isoC-99 .
 448 .Sh HISTORY
 449 The functions
 450 .Fn vscanf ,
 451 .Fn vsscanf
 452 and
 453 .Fn vfscanf
 454 appeared in
 455 .Bx 4.4
 456 or even
 457 .Bx 4.3 .
 458 .Sh NOTES
 459 All of the backwards compatibility formats will be removed in the future.
 460 .Sh BUGS
 461 Numerical strings are truncated to 512 characters; for example,
 462 .Cm %f
 463 and
 464 .Cm %d
 465 are implicitly
 466 .Cm %512f
 467 and
 468 .Cm %512d .