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