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