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