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