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.
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.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
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.
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
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 $
52 .Nd wide character input format conversion
59 .Fn wscanf "const wchar_t * restrict format" ...
61 .Fn fwscanf "FILE * restrict stream" "const wchar_t * restrict format" ...
63 .Fn swscanf "const wchar_t * restrict str" "const wchar_t * restrict format" ...
66 .Fn vwscanf "const wchar_t * restrict format" "va_list ap"
68 .Fn vswscanf "const wchar_t * restrict str" "const wchar_t * restrict format" "va_list ap"
70 .Fn vfwscanf "FILE * restrict stream" "const wchar_t * restrict format" "va_list ap"
74 family of functions scans input according to a
77 This format may contain
78 .Em conversion specifiers ;
79 the results from such conversions, if any,
80 are stored through the
86 reads input from the standard input stream
89 reads input from the stream pointer
93 reads its input from the wide character string pointed to by
100 and reads input from the stream pointer
102 using a variable argument list of pointers (see
106 function scans a variable argument list from the standard input and
109 function scans it from a wide character string;
110 these are analogous to
115 functions respectively.
118 argument must correspond properly with
119 each successive conversion specifier
123 All conversions are introduced by the
125 (percent sign) character.
129 may also contain other characters.
130 White space (such as blanks, tabs, or newlines) in the
132 string match any amount of white space, including none, in the input.
136 when an input character does not match such a format character.
138 when an input conversion cannot be made (see below).
142 character introducing a conversion
143 there may be a number of
145 characters, as follows:
146 .Bl -tag -width ".Cm l No (ell)"
148 Suppresses assignment.
149 The conversion that follows occurs as usual, but no pointer is used;
150 the result of the conversion is simply discarded.
152 Indicates that the conversion will be one of
156 and the next pointer is a pointer to a
161 Indicates that the conversion will be one of
165 and the next pointer is a pointer to a
170 Indicates that the conversion will be one of
174 and the next pointer is a pointer to a
178 that the conversion will be one of
182 and the next pointer is a pointer to
186 or that the conversion will be one of
190 and the next pointer is a pointer to an array of
194 .It Cm ll No (ell ell)
195 Indicates that the conversion will be one of
199 and the next pointer is a pointer to a
204 Indicates that the conversion will be one of
208 and the next pointer is a pointer to
211 Indicates that the conversion will be one of
215 and the next pointer is a pointer to a
220 Indicates that the conversion will be one of
224 and the next pointer is a pointer to a
229 Indicates that the conversion will be one of
233 and the next pointer is a pointer to a
239 Indicates that the conversion will be one of
243 and the next pointer is a pointer to a
249 In addition to these flags,
250 there may be an optional maximum field width,
251 expressed as a decimal integer,
255 If no width is given,
258 is used (with one exception, below);
259 otherwise at most this many characters are scanned
260 in processing the conversion.
261 Before conversion begins,
262 most conversions skip white space;
263 this white space is not counted against the field width.
265 The following conversions are available:
273 matches a single input
276 No conversion is done, and assignment does not occur.
278 Matches an optionally signed decimal integer;
279 the next pointer must be a pointer to
282 Matches an optionally signed integer;
283 the next pointer must be a pointer to
285 The integer is read in base 16 if it begins
290 in base 8 if it begins with
292 and in base 10 otherwise.
293 Only characters that correspond to the base are used.
295 Matches an octal integer;
296 the next pointer must be a pointer to
299 Matches an optionally signed decimal integer;
300 the next pointer must be a pointer to
303 Matches an optionally signed hexadecimal integer;
304 the next pointer must be a pointer to
306 .It Cm a , A , e , E , f , F , g , G
307 Matches a floating-point number in the style of
309 The next pointer must be a pointer to
317 Matches a sequence of non-white-space wide characters;
318 the next pointer must be a pointer to
320 and the array must be large enough to accept the multibyte representation
321 of all the sequence and the
325 The input string stops at white space
326 or at the maximum field width, whichever occurs first.
330 qualifier is present, the next pointer must be a pointer to
332 into which the input will be placed.
337 Matches a sequence of
340 wide characters (default 1);
341 the next pointer must be a pointer to
343 and there must be enough room for the multibyte representation
344 of all the characters
348 The usual skip of leading white space is suppressed.
349 To skip white space first, use an explicit space in the format.
353 qualifier is present, the next pointer must be a pointer to
355 into which the input will be placed.
360 Matches a nonempty sequence of characters from the specified set
361 of accepted characters;
362 the next pointer must be a pointer to
364 and there must be enough room for the multibyte representation of
365 all the characters in the string,
369 The usual skip of leading white space is suppressed.
370 The string is to be made up of characters in
373 the set is defined by the characters between the open bracket
382 if the first character after the open bracket is a circumflex
384 To include a close bracket in the set,
385 make it the first character after the open bracket
387 any other position will end the set.
388 To include a hyphen in the set,
389 make it the last character before the final close bracket;
390 some implementations of
394 to represent the range of characters between
398 The string ends with the appearance of a character not in the
399 (or, with a circumflex, in) set
400 or when the field width runs out.
404 qualifier is present, the next pointer must be a pointer to
406 into which the input will be placed.
408 Matches a pointer value (as printed by
412 the next pointer must be a pointer to
416 instead, the number of characters consumed thus far from the input
417 is stored through the next pointer,
418 which must be a pointer to
422 a conversion, although it can be suppressed with the
428 character is defined in the program's locale (category
431 For backwards compatibility, a
435 causes an immediate return of
441 the number of input items assigned, which can be fewer than provided
442 for, or even zero, in the event of a matching failure.
444 indicates that, while there was input available,
445 no conversions were assigned;
446 typically this is due to an invalid input character,
447 such as an alphabetic character for a
452 is returned if an input failure occurs before any conversion such as an
454 If an error or end-of-file occurs after conversion
456 the number of conversions which were successfully completed is returned.
478 In addition to the bugs documented in
483 notation for specifying character ranges with the character