1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
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.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
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 $
47 .Nd wide character input format conversion
54 .Fn wscanf "const wchar_t * restrict format" ...
56 .Fn fwscanf "FILE * restrict stream" "const wchar_t * restrict format" ...
58 .Fn swscanf "const wchar_t * restrict str" "const wchar_t * restrict format" ...
61 .Fn vwscanf "const wchar_t * restrict format" "va_list ap"
63 .Fn vswscanf "const wchar_t * restrict str" "const wchar_t * restrict format" "va_list ap"
65 .Fn vfwscanf "FILE * restrict stream" "const wchar_t * restrict format" "va_list ap"
69 family of functions scans input according to a
72 This format may contain
73 .Em conversion specifiers ;
74 the results from such conversions, if any,
75 are stored through the
81 reads input from the standard input stream
84 reads input from the stream pointer
88 reads its input from the wide character string pointed to by
95 and reads input from the stream pointer
97 using a variable argument list of pointers (see
101 function scans a variable argument list from the standard input and
104 function scans it from a wide character string;
105 these are analogous to
110 functions respectively.
113 argument must correspond properly with
114 each successive conversion specifier
118 All conversions are introduced by the
120 (percent sign) character.
124 may also contain other characters.
125 White space (such as blanks, tabs, or newlines) in the
127 string match any amount of white space, including none, in the input.
131 when an input character does not match such a format character.
133 when an input conversion cannot be made (see below).
137 character introducing a conversion
138 there may be a number of
140 characters, as follows:
141 .Bl -tag -width ".Cm l No (ell)"
143 Suppresses assignment.
144 The conversion that follows occurs as usual, but no pointer is used;
145 the result of the conversion is simply discarded.
147 Indicates that the conversion will be one of
151 and the next pointer is a pointer to a
156 Indicates that the conversion will be one of
160 and the next pointer is a pointer to a
165 Indicates that the conversion will be one of
169 and the next pointer is a pointer to a
173 that the conversion will be one of
177 and the next pointer is a pointer to
181 or that the conversion will be one of
185 and the next pointer is a pointer to an array of
189 .It Cm ll No (ell ell)
190 Indicates that the conversion will be one of
194 and the next pointer is a pointer to a
199 Indicates that the conversion will be one of
203 and the next pointer is a pointer to
206 Indicates that the conversion will be one of
210 and the next pointer is a pointer to a
215 Indicates that the conversion will be one of
219 and the next pointer is a pointer to a
224 Indicates that the conversion will be one of
228 and the next pointer is a pointer to a
234 Indicates that the conversion will be one of
238 and the next pointer is a pointer to a
244 In addition to these flags,
245 there may be an optional maximum field width,
246 expressed as a decimal integer,
250 If no width is given,
253 is used (with one exception, below);
254 otherwise at most this many characters are scanned
255 in processing the conversion.
256 Before conversion begins,
257 most conversions skip white space;
258 this white space is not counted against the field width.
260 The following conversions are available:
268 matches a single input
271 No conversion is done, and assignment does not occur.
273 Matches an optionally signed decimal integer;
274 the next pointer must be a pointer to
277 Matches an optionally signed integer;
278 the next pointer must be a pointer to
280 The integer is read in base 16 if it begins
285 in base 8 if it begins with
287 and in base 10 otherwise.
288 Only characters that correspond to the base are used.
290 Matches an octal integer;
291 the next pointer must be a pointer to
294 Matches an optionally signed decimal integer;
295 the next pointer must be a pointer to
298 Matches an optionally signed hexadecimal integer;
299 the next pointer must be a pointer to
301 .It Cm a , A , e , E , f , F , g , G
302 Matches a floating-point number in the style of
304 The next pointer must be a pointer to
312 Matches a sequence of non-white-space wide characters;
313 the next pointer must be a pointer to
315 and the array must be large enough to accept the multibyte representation
316 of all the sequence and the
320 The input string stops at white space
321 or at the maximum field width, whichever occurs first.
325 qualifier is present, the next pointer must be a pointer to
327 into which the input will be placed.
332 Matches a sequence of
335 wide characters (default 1);
336 the next pointer must be a pointer to
338 and there must be enough room for the multibyte representation
339 of all the characters
343 The usual skip of leading white space is suppressed.
344 To skip white space first, use an explicit space in the format.
348 qualifier is present, the next pointer must be a pointer to
350 into which the input will be placed.
355 Matches a nonempty sequence of characters from the specified set
356 of accepted characters;
357 the next pointer must be a pointer to
359 and there must be enough room for the multibyte representation of
360 all the characters in the string,
364 The usual skip of leading white space is suppressed.
365 The string is to be made up of characters in
368 the set is defined by the characters between the open bracket
377 if the first character after the open bracket is a circumflex
379 To include a close bracket in the set,
380 make it the first character after the open bracket
382 any other position will end the set.
383 To include a hyphen in the set,
384 make it the last character before the final close bracket;
385 some implementations of
389 to represent the range of characters between
393 The string ends with the appearance of a character not in the
394 (or, with a circumflex, in) set
395 or when the field width runs out.
399 qualifier is present, the next pointer must be a pointer to
401 into which the input will be placed.
403 Matches a pointer value (as printed by
407 the next pointer must be a pointer to
411 instead, the number of characters consumed thus far from the input
412 is stored through the next pointer,
413 which must be a pointer to
417 a conversion, although it can be suppressed with the
423 character is defined in the program's locale (category
426 For backwards compatibility, a
430 causes an immediate return of
436 the number of input items assigned, which can be fewer than provided
437 for, or even zero, in the event of a matching failure.
439 indicates that, while there was input available,
440 no conversions were assigned;
441 typically this is due to an invalid input character,
442 such as an alphabetic character for a
447 is returned if an input failure occurs before any conversion such as an
449 If an error or end-of-file occurs after conversion
451 the number of conversions which were successfully completed is returned.
473 In addition to the bugs documented in
478 notation for specifying character ranges with the character