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