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