lib/libcr/stdio/scanf.3

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