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