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