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