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. 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: head/lib/libc/stdio/scanf.3 235363 2012-05-12 20:27:13Z joel $ 34.\" 35.Dd March 21, 2022 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 ) , 196or that the conversion will be one of 197.Cm a , e , f , 198or 199.Cm g 200and the next pointer is a pointer to 201.Vt "long double" 202(non-standard). 203.It Cm L 204Indicates that the conversion will be one of 205.Cm a , e , f , 206or 207.Cm g 208and the next pointer is a pointer to 209.Vt "long double" , 210or that the conversion will be one of 211.Cm dioux 212or 213.Cm n 214and the next pointer is a pointer to a 215.Vt "long long int" 216(rather than 217.Vt int ) 218(non-standard). 219.It Cm j 220Indicates that the conversion will be one of 221.Cm dioux 222or 223.Cm n 224and the next pointer is a pointer to a 225.Vt intmax_t 226(rather than 227.Vt int ) . 228.It Cm t 229Indicates that the conversion will be one of 230.Cm dioux 231or 232.Cm n 233and the next pointer is a pointer to a 234.Vt ptrdiff_t 235(rather than 236.Vt int ) . 237.It Cm z 238Indicates that the conversion will be one of 239.Cm dioux 240or 241.Cm n 242and the next pointer is a pointer to a 243.Vt size_t 244(rather than 245.Vt int ) . 246.It Cm q 247(deprecated.) 248Indicates that the conversion will be one of 249.Cm dioux 250or 251.Cm n 252and the next pointer is a pointer to a 253.Vt "long long int" 254(rather than 255.Vt int ) . 256.El 257.Pp 258In addition to these flags, 259there may be an optional maximum field width, 260expressed as a decimal integer, 261between the 262.Cm % 263and the conversion. 264If no width is given, 265a default of 266.Dq infinity 267is used (with one exception, below); 268otherwise at most this many bytes are scanned 269in processing the conversion. 270In the case of the 271.Cm lc , 272.Cm ls 273and 274.Cm l[ 275conversions, the field width specifies the maximum number 276of multibyte characters that will be scanned. 277Before conversion begins, 278most conversions skip white space; 279this white space is not counted against the field width. 280.Pp 281The following conversions are available: 282.Bl -tag -width XXXX 283.It Cm % 284Matches a literal 285.Ql % . 286That is, 287.Dq Li %% 288in the format string 289matches a single input 290.Ql % 291character. 292No conversion is done, and assignment does not occur. 293.It Cm d 294Matches an optionally signed decimal integer; 295the next pointer must be a pointer to 296.Vt int . 297.It Cm i 298Matches an optionally signed integer; 299the next pointer must be a pointer to 300.Vt int . 301The integer is read in base 16 if it begins 302with 303.Ql 0x 304or 305.Ql 0X , 306in base 8 if it begins with 307.Ql 0 , 308and in base 10 otherwise. 309Only characters that correspond to the base are used. 310.It Cm o 311Matches an octal integer; 312the next pointer must be a pointer to 313.Vt "unsigned int" . 314.It Cm u 315Matches an optionally signed decimal integer; 316the next pointer must be a pointer to 317.Vt "unsigned int" . 318.It Cm x , X 319Matches an optionally signed hexadecimal integer; 320the next pointer must be a pointer to 321.Vt "unsigned int" . 322.It Cm a , A , e , E , f , F , g , G 323Matches a floating-point number in the style of 324.Xr strtod 3 . 325The next pointer must be a pointer to 326.Vt float 327(unless 328.Cm l , 329.Cm L 330or 331.Cm ll 332is specified.) 333.It Cm s 334Matches a sequence of non-white-space characters; 335the next pointer must be a pointer to 336.Vt char , 337and the array must be large enough to accept all the sequence and the 338terminating 339.Dv NUL 340character. 341The input string stops at white space 342or at the maximum field width, whichever occurs first. 343.Pp 344If an 345.Cm l 346qualifier is present, the next pointer must be a pointer to 347.Vt wchar_t , 348into which the input will be placed after conversion by 349.Xr mbrtowc 3 . 350.It Cm S 351The same as 352.Cm ls . 353.It Cm c 354Matches a sequence of 355.Em width 356count 357characters (default 1); 358the next pointer must be a pointer to 359.Vt char , 360and there must be enough room for all the characters 361(no terminating 362.Dv NUL 363is added). 364The usual skip of leading white space is suppressed. 365To skip white space first, use an explicit space in the format. 366.Pp 367If an 368.Cm l 369qualifier is present, the next pointer must be a pointer to 370.Vt wchar_t , 371into which the input will be placed after conversion by 372.Xr mbrtowc 3 . 373.It Cm C 374The same as 375.Cm lc . 376.It Cm \&[ 377Matches a nonempty sequence of characters from the specified set 378of accepted characters; 379the next pointer must be a pointer to 380.Vt char , 381and there must be enough room for all the characters in the string, 382plus a terminating 383.Dv NUL 384character. 385The usual skip of leading white space is suppressed. 386The string is to be made up of characters in 387(or not in) 388a particular set; 389the set is defined by the characters between the open bracket 390.Cm \&[ 391character 392and a close bracket 393.Cm \&] 394character. 395The set 396.Em excludes 397those characters 398if the first character after the open bracket is a circumflex 399.Cm ^ . 400To include a close bracket in the set, 401make it the first character after the open bracket 402or the circumflex; 403any other position will end the set. 404The hyphen character 405.Cm - 406is also special; 407when placed between two other characters, 408it adds all intervening characters to the set. 409To include a hyphen, 410make it the last character before the final close bracket. 411For instance, 412.Ql [^]0-9-] 413means the set 414.Dq "everything except close bracket, zero through nine, and hyphen" . 415The string ends with the appearance of a character not in the 416(or, with a circumflex, in) set 417or when the field width runs out. 418.Pp 419If an 420.Cm l 421qualifier is present, the next pointer must be a pointer to 422.Vt wchar_t , 423into which the input will be placed after conversion by 424.Xr mbrtowc 3 . 425.It Cm p 426Matches a pointer value (as printed by 427.Ql %p 428in 429.Xr printf 3 ) ; 430the next pointer must be a pointer to 431.Vt void . 432.It Cm n 433Nothing is expected; 434instead, the number of characters consumed thus far from the input 435is stored through the next pointer, 436which must be a pointer to 437.Vt int . 438This is 439.Em not 440a conversion, although it can be suppressed with the 441.Cm * 442flag. 443.El 444.Pp 445The decimal point 446character is defined in the program's locale (category 447.Dv LC_NUMERIC ) . 448.Pp 449For backwards compatibility, a 450.Dq conversion 451of 452.Ql %\e0 453causes an immediate return of 454.Dv EOF . 455.Sh RETURN VALUES 456These 457functions 458return 459the number of input items assigned, which can be fewer than provided 460for, or even zero, in the event of a matching failure. 461Zero 462indicates that, while there was input available, 463no conversions were assigned; 464typically this is due to an invalid input character, 465such as an alphabetic character for a 466.Ql %d 467conversion. 468The value 469.Dv EOF 470is returned if an input failure occurs before any conversion such as an 471end-of-file occurs. 472If an error or end-of-file occurs after conversion 473has begun, 474the number of conversions which were successfully completed is returned. 475.Sh SEE ALSO 476.Xr getc 3 , 477.Xr mbrtowc 3 , 478.Xr printf 3 , 479.Xr strtod 3 , 480.Xr strtol 3 , 481.Xr strtoul 3 , 482.Xr wscanf 3 483.Sh STANDARDS 484The functions 485.Fn fscanf , 486.Fn scanf , 487.Fn sscanf , 488.Fn vfscanf , 489.Fn vscanf 490and 491.Fn vsscanf 492conform to 493.St -isoC-99 . 494.Pp 495As an extension, 496.Dx 497treats the length modifiers 498.Cm ll 499and 500.Cm L 501as synonyms, so that the non-standard 502.Cm %Ld 503is equivalent to 504.Cm %ld 505and the non-standard 506.Cm %llg 507is equivalent 508to 509.Cm %Lg . 510.Sh BUGS 511Earlier implementations of 512.Nm 513treated 514.Cm \&%D , \&%E , \&%F , \&%O 515and 516.Cm \&%X 517as their lowercase equivalents with an 518.Cm l 519modifier. 520In addition, 521.Nm 522treated an unknown conversion character as 523.Cm \&%d 524or 525.Cm \&%D , 526depending on its case. 527This functionality has been removed. 528.Pp 529Numerical strings are truncated to 512 characters; for example, 530.Cm %f 531and 532.Cm %d 533are implicitly 534.Cm %512f 535and 536.Cm %512d . 537.Pp 538The 539.Cm %n$ 540modifiers for positional arguments are not implemented. 541.Pp 542The 543.Nm 544family of functions do not correctly handle multibyte characters in the 545.Fa format 546argument. 547