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