Document the recent upgrade of the printf and scanf families of functions.
[dragonfly.git] / lib / libc / stdio / scanf.3
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. All advertising materials mentioning features or use of this software
17 .\"    must display the following acknowledgement:
18 .\"     This product includes software developed by the University of
19 .\"     California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\"    may be used to endorse or promote products derived from this software
22 .\"    without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\"     @(#)scanf.3     8.2 (Berkeley) 12/11/93
37 .\" $FreeBSD: src/lib/libc/stdio/scanf.3,v 1.24 2003/06/28 09:03:25 das Exp $
38 .\" $DragonFly: src/lib/libc/stdio/scanf.3,v 1.3 2006/08/26 10:27:55 swildner Exp $
39 .\"
40 .Dd August 26, 2006
41 .Dt SCANF 3
42 .Os
43 .Sh NAME
44 .Nm scanf ,
45 .Nm fscanf ,
46 .Nm sscanf ,
47 .Nm vscanf ,
48 .Nm vsscanf ,
49 .Nm vfscanf
50 .Nd input format conversion
51 .Sh LIBRARY
52 .Lb libc
53 .Sh SYNOPSIS
54 .In stdio.h
55 .Ft int
56 .Fn scanf "const char *format" ...
57 .Ft int
58 .Fn fscanf "FILE *stream" "const char *format" ...
59 .Ft int
60 .Fn sscanf "const char *str" "const char *format" ...
61 .In stdarg.h
62 .Ft int
63 .Fn vscanf "const char *format" "va_list ap"
64 .Ft int
65 .Fn vsscanf "const char *str" "const char *format" "va_list ap"
66 .Ft int
67 .Fn vfscanf "FILE *stream" "const char *format" "va_list ap"
68 .Sh DESCRIPTION
69 The
70 .Fn scanf
71 family of functions scans input according to a
72 .Fa format
73 as described below.
74 This format may contain
75 .Em conversion specifiers ;
76 the results from such conversions, if any,
77 are stored through the
78 .Em pointer
79 arguments.
80 The
81 .Fn scanf
82 function
83 reads input from the standard input stream
84 .Dv stdin ,
85 .Fn fscanf
86 reads input from the stream pointer
87 .Fa stream ,
88 and
89 .Fn sscanf
90 reads its input from the character string pointed to by
91 .Fa str .
92 The
93 .Fn vfscanf
94 function
95 is analogous to
96 .Xr vfprintf 3
97 and reads input from the stream pointer
98 .Fa stream
99 using a variable argument list of pointers (see
100 .Xr stdarg 3 ) .
101 The
102 .Fn vscanf
103 function scans a variable argument list from the standard input and
104 the
105 .Fn vsscanf
106 function scans it from a string;
107 these are analogous to
108 the
109 .Fn vprintf
110 and
111 .Fn vsprintf
112 functions respectively.
113 Each successive
114 .Em pointer
115 argument must correspond properly with
116 each successive conversion specifier
117 (but see the
118 .Cm *
119 conversion below).
120 All conversions are introduced by the
121 .Cm %
122 (percent sign) character.
123 The
124 .Fa format
125 string
126 may also contain other characters.
127 White space (such as blanks, tabs, or newlines) in the
128 .Fa format
129 string match any amount of white space, including none, in the input.
130 Everything else
131 matches only itself.
132 Scanning stops
133 when an input character does not match such a format character.
134 Scanning also stops
135 when an input conversion cannot be made (see below).
136 .Sh CONVERSIONS
137 Following the
138 .Cm %
139 character introducing a conversion
140 there may be a number of
141 .Em flag
142 characters, as follows:
143 .Bl -tag -width ".Cm l No (ell)"
144 .It Cm *
145 Suppresses assignment.
146 The conversion that follows occurs as usual, but no pointer is used;
147 the result of the conversion is simply discarded.
148 .It Cm hh
149 Indicates that the conversion will be one of
150 .Cm dioux
151 or
152 .Cm n
153 and the next pointer is a pointer to a
154 .Vt char
155 (rather than
156 .Vt int ) .
157 .It Cm h
158 Indicates that the conversion will be one of
159 .Cm dioux
160 or
161 .Cm n
162 and the next pointer is a pointer to a
163 .Vt "short int"
164 (rather than
165 .Vt int ) .
166 .It Cm l No (ell)
167 Indicates that the conversion will be one of
168 .Cm dioux
169 or
170 .Cm n
171 and the next pointer is a pointer to a
172 .Vt "long int"
173 (rather than
174 .Vt int ) ,
175 that the conversion will be one of
176 .Cm e , f ,
177 or
178 .Cm g
179 and the next pointer is a pointer to
180 .Vt double
181 (rather than
182 .Vt float ) ,
183 or that the conversion will be one of
184 .Cm c ,
185 .Cm s
186 or
187 .Cm \&[
188 and the next pointer is a pointer to an array of
189 .Vt wchar_t
190 (rather than
191 .Vt char ) .
192 .It Cm ll No (ell ell)
193 Indicates that the conversion will be one of
194 .Cm dioux
195 or
196 .Cm n
197 and the next pointer is a pointer to a
198 .Vt "long long int"
199 (rather than
200 .Vt int ) .
201 .It Cm L
202 Indicates that the conversion will be one of
203 .Cm e , f ,
204 or
205 .Cm g
206 and the next pointer is a pointer to
207 .Vt "long double" .
208 .It Cm j
209 Indicates that the conversion will be one of
210 .Cm dioux
211 or
212 .Cm n
213 and the next pointer is a pointer to a
214 .Vt intmax_t
215 (rather than
216 .Vt int ) .
217 .It Cm t
218 Indicates that the conversion will be one of
219 .Cm dioux
220 or
221 .Cm n
222 and the next pointer is a pointer to a
223 .Vt ptrdiff_t
224 (rather than
225 .Vt int ) .
226 .It Cm z
227 Indicates that the conversion will be one of
228 .Cm dioux
229 or
230 .Cm n
231 and the next pointer is a pointer to a
232 .Vt size_t
233 (rather than
234 .Vt int ) .
235 .It Cm q
236 (deprecated.)
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 "long long int"
243 (rather than
244 .Vt int ) .
245 .El
246 .Pp
247 In addition to these flags,
248 there may be an optional maximum field width,
249 expressed as a decimal integer,
250 between the
251 .Cm %
252 and the conversion.
253 If no width is given,
254 a default of
255 .Dq infinity
256 is used (with one exception, below);
257 otherwise at most this many bytes are scanned
258 in processing the conversion.
259 In the case of the
260 .Cm lc ,
261 .Cm ls
262 and
263 .Cm l[
264 conversions, the field width specifies the maximum number
265 of multibyte characters that will be scanned.
266 Before conversion begins,
267 most conversions skip white space;
268 this white space is not counted against the field width.
269 .Pp
270 The following conversions are available:
271 .Bl -tag -width XXXX
272 .It Cm %
273 Matches a literal
274 .Ql % .
275 That is,
276 .Dq Li %%
277 in the format string
278 matches a single input
279 .Ql %
280 character.
281 No conversion is done, and assignment does not occur.
282 .It Cm d
283 Matches an optionally signed decimal integer;
284 the next pointer must be a pointer to
285 .Vt int .
286 .It Cm i
287 Matches an optionally signed integer;
288 the next pointer must be a pointer to
289 .Vt int .
290 The integer is read in base 16 if it begins
291 with
292 .Ql 0x
293 or
294 .Ql 0X ,
295 in base 8 if it begins with
296 .Ql 0 ,
297 and in base 10 otherwise.
298 Only characters that correspond to the base are used.
299 .It Cm o
300 Matches an octal integer;
301 the next pointer must be a pointer to
302 .Vt "unsigned int" .
303 .It Cm u
304 Matches an optionally signed decimal integer;
305 the next pointer must be a pointer to
306 .Vt "unsigned int" .
307 .It Cm x , X
308 Matches an optionally signed hexadecimal integer;
309 the next pointer must be a pointer to
310 .Vt "unsigned int" .
311 .It Cm e , E , f , F , g , G
312 Matches a floating-point number in the style of
313 .Xr strtod 3 .
314 The next pointer must be a pointer to
315 .Vt float
316 (unless
317 .Cm l
318 or
319 .Cm L
320 is specified.)
321 .It Cm s
322 Matches a sequence of non-white-space characters;
323 the next pointer must be a pointer to
324 .Vt char ,
325 and the array must be large enough to accept all the sequence and the
326 terminating
327 .Dv NUL
328 character.
329 The input string stops at white space
330 or at the maximum field width, whichever occurs first.
331 .Pp
332 If an
333 .Cm l
334 qualifier is present, the next pointer must be a pointer to
335 .Vt wchar_t ,
336 into which the input will be placed after conversion by
337 .Xr mbrtowc 3 .
338 .It Cm S
339 The same as
340 .Cm ls .
341 .It Cm c
342 Matches a sequence of
343 .Em width
344 count
345 characters (default 1);
346 the next pointer must be a pointer to
347 .Vt char ,
348 and there must be enough room for all the characters
349 (no terminating
350 .Dv NUL
351 is added).
352 The usual skip of leading white space is suppressed.
353 To skip white space first, use an explicit space in the format.
354 .Pp
355 If an
356 .Cm l
357 qualifier is present, the next pointer must be a pointer to
358 .Vt wchar_t ,
359 into which the input will be placed after conversion by
360 .Xr mbrtowc 3 .
361 .It Cm C
362 The same as
363 .Cm lc .
364 .It Cm \&[
365 Matches a nonempty sequence of characters from the specified set
366 of accepted characters;
367 the next pointer must be a pointer to
368 .Vt char ,
369 and there must be enough room for all the characters in the string,
370 plus a terminating
371 .Dv NUL
372 character.
373 The usual skip of leading white space is suppressed.
374 The string is to be made up of characters in
375 (or not in)
376 a particular set;
377 the set is defined by the characters between the open bracket
378 .Cm [
379 character
380 and a close bracket
381 .Cm ]
382 character.
383 The set
384 .Em excludes
385 those characters
386 if the first character after the open bracket is a circumflex
387 .Cm ^ .
388 To include a close bracket in the set,
389 make it the first character after the open bracket
390 or the circumflex;
391 any other position will end the set.
392 The hyphen character
393 .Cm -
394 is also special;
395 when placed between two other characters,
396 it adds all intervening characters to the set.
397 To include a hyphen,
398 make it the last character before the final close bracket.
399 For instance,
400 .Ql [^]0-9-]
401 means the set
402 .Dq "everything except close bracket, zero through nine, and hyphen" .
403 The string ends with the appearance of a character not in the
404 (or, with a circumflex, in) set
405 or when the field width runs out.
406 .Pp
407 If an
408 .Cm l
409 qualifier is present, the next pointer must be a pointer to
410 .Vt wchar_t ,
411 into which the input will be placed after conversion by
412 .Xr mbrtowc 3 .
413 .It Cm p
414 Matches a pointer value (as printed by
415 .Ql %p
416 in
417 .Xr printf 3 ) ;
418 the next pointer must be a pointer to
419 .Vt void .
420 .It Cm n
421 Nothing is expected;
422 instead, the number of characters consumed thus far from the input
423 is stored through the next pointer,
424 which must be a pointer to
425 .Vt int .
426 This is
427 .Em not
428 a conversion, although it can be suppressed with the
429 .Cm *
430 flag.
431 .El
432 .Pp
433 The decimal point
434 character is defined in the program's locale (category
435 .Dv LC_NUMERIC ) .
436 .Pp
437 For backwards compatibility, a
438 .Dq conversion
439 of
440 .Ql %\e0
441 causes an immediate return of
442 .Dv EOF .
443 .Sh RETURN VALUES
444 These
445 functions
446 return
447 the number of input items assigned, which can be fewer than provided
448 for, or even zero, in the event of a matching failure.
449 Zero
450 indicates that, while there was input available,
451 no conversions were assigned;
452 typically this is due to an invalid input character,
453 such as an alphabetic character for a
454 .Ql %d
455 conversion.
456 The value
457 .Dv EOF
458 is returned if an input failure occurs before any conversion such as an
459 end-of-file occurs.
460 If an error or end-of-file occurs after conversion
461 has begun,
462 the number of conversions which were successfully completed is returned.
463 .Sh SEE ALSO
464 .Xr getc 3 ,
465 .Xr mbrtowc 3 ,
466 .Xr printf 3 ,
467 .Xr strtod 3 ,
468 .Xr strtol 3 ,
469 .Xr strtoul 3 ,
470 .Xr wscanf 3
471 .Sh STANDARDS
472 The functions
473 .Fn fscanf ,
474 .Fn scanf ,
475 .Fn sscanf ,
476 .Fn vfscanf ,
477 .Fn vscanf
478 and
479 .Fn vsscanf
480 conform to
481 .St -isoC-99 .
482 .Sh BUGS
483 Earlier implementations of
484 .Nm
485 treated
486 .Cm \&%D , \&%E , \&%F , \&%O
487 and
488 .Cm \&%X
489 as their lowercase equivalents with an
490 .Cm l
491 modifier.
492 In addition,
493 .Nm
494 treated an unknown conversion character as
495 .Cm \&%d
496 or
497 .Cm \&%D ,
498 depending on its case.
499 This functionality has been removed.
500 .Pp
501 Numerical strings are truncated to 512 characters; for example,
502 .Cm %f
503 and
504 .Cm %d
505 are implicitly
506 .Cm %512f
507 and
508 .Cm %512d .
509 .Pp
510 The
511 .Cm %n$
512 modifiers for positional arguments are not implemented.
513 .Pp
514 The
515 .Nm
516 family of functions do not correctly handle multibyte characters in the
517 .Fa format
518 argument.