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