1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
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.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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 .\" 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.
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
32 .\" @(#)scanf.3 8.2 (Berkeley) 12/11/93
33 .\" $FreeBSD: src/lib/libc/stdio/scanf.3,v 1.25 2007/01/09 00:28:07 imp Exp $
34 .\" $DragonFly: src/lib/libc/stdio/scanf.3,v 1.3 2006/08/26 10:27:55 swildner Exp $
46 .Nd input format conversion
52 .Fn scanf "const char * restrict format" ...
54 .Fn fscanf "FILE * restrict stream" "const char * restrict format" ...
56 .Fn sscanf "const char * restrict str" "const char * restrict format" ...
59 .Fn vscanf "const char * restrict format" "va_list ap"
61 .Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap"
63 .Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap"
67 family of functions scans input according to a
70 This format may contain
71 .Em conversion specifiers ;
72 the results from such conversions, if any,
73 are stored through the
79 reads input from the standard input stream
82 reads input from the stream pointer
86 reads its input from the character string pointed to by
93 and reads input from the stream pointer
95 using a variable argument list of pointers (see
99 function scans a variable argument list from the standard input and
102 function scans it from a string;
103 these are analogous to
108 functions respectively.
111 argument must correspond properly with
112 each successive conversion specifier
116 All conversions are introduced by the
118 (percent sign) character.
122 may also contain other characters.
123 White space (such as blanks, tabs, or newlines) in the
125 string match any amount of white space, including none, in the input.
129 when an input character does not match such a format character.
131 when an input conversion cannot be made (see below).
135 character introducing a conversion
136 there may be a number of
138 characters, as follows:
139 .Bl -tag -width ".Cm l No (ell)"
141 Suppresses assignment.
142 The conversion that follows occurs as usual, but no pointer is used;
143 the result of the conversion is simply discarded.
145 Indicates that the conversion will be one of
149 and the next pointer is a pointer to a
154 Indicates that the conversion will be one of
158 and the next pointer is a pointer to a
163 Indicates that the conversion will be one of
167 and the next pointer is a pointer to a
171 that the conversion will be one of
175 and the next pointer is a pointer to
179 or that the conversion will be one of
184 and the next pointer is a pointer to an array of
188 .It Cm ll No (ell ell)
189 Indicates that the conversion will be one of
193 and the next pointer is a pointer to a
198 Indicates that the conversion will be one of
202 and the next pointer is a pointer to
205 Indicates that the conversion will be one of
209 and the next pointer is a pointer to a
214 Indicates that the conversion will be one of
218 and the next pointer is a pointer to a
223 Indicates that the conversion will be one of
227 and the next pointer is a pointer to a
233 Indicates that the conversion will be one of
237 and the next pointer is a pointer to a
243 In addition to these flags,
244 there may be an optional maximum field width,
245 expressed as a decimal integer,
249 If no width is given,
252 is used (with one exception, below);
253 otherwise at most this many bytes are scanned
254 in processing the conversion.
260 conversions, the field width specifies the maximum number
261 of multibyte characters that will be scanned.
262 Before conversion begins,
263 most conversions skip white space;
264 this white space is not counted against the field width.
266 The following conversions are available:
274 matches a single input
277 No conversion is done, and assignment does not occur.
279 Matches an optionally signed decimal integer;
280 the next pointer must be a pointer to
283 Matches an optionally signed integer;
284 the next pointer must be a pointer to
286 The integer is read in base 16 if it begins
291 in base 8 if it begins with
293 and in base 10 otherwise.
294 Only characters that correspond to the base are used.
296 Matches an octal integer;
297 the next pointer must be a pointer to
300 Matches an optionally signed decimal integer;
301 the next pointer must be a pointer to
304 Matches an optionally signed hexadecimal integer;
305 the next pointer must be a pointer to
307 .It Cm a , A , e , E , f , F , g , G
308 Matches a floating-point number in the style of
310 The next pointer must be a pointer to
318 Matches a sequence of non-white-space characters;
319 the next pointer must be a pointer to
321 and the array must be large enough to accept all the sequence and the
325 The input string stops at white space
326 or at the maximum field width, whichever occurs first.
330 qualifier is present, the next pointer must be a pointer to
332 into which the input will be placed after conversion by
338 Matches a sequence of
341 characters (default 1);
342 the next pointer must be a pointer to
344 and there must be enough room for all the characters
348 The usual skip of leading white space is suppressed.
349 To skip white space first, use an explicit space in the format.
353 qualifier is present, the next pointer must be a pointer to
355 into which the input will be placed after conversion by
361 Matches a nonempty sequence of characters from the specified set
362 of accepted characters;
363 the next pointer must be a pointer to
365 and there must be enough room for all the characters in the string,
369 The usual skip of leading white space is suppressed.
370 The string is to be made up of characters in
373 the set is defined by the characters between the open bracket
382 if the first character after the open bracket is a circumflex
384 To include a close bracket in the set,
385 make it the first character after the open bracket
387 any other position will end the set.
391 when placed between two other characters,
392 it adds all intervening characters to the set.
394 make it the last character before the final close bracket.
398 .Dq "everything except close bracket, zero through nine, and hyphen" .
399 The string ends with the appearance of a character not in the
400 (or, with a circumflex, in) set
401 or when the field width runs out.
405 qualifier is present, the next pointer must be a pointer to
407 into which the input will be placed after conversion by
410 Matches a pointer value (as printed by
414 the next pointer must be a pointer to
418 instead, the number of characters consumed thus far from the input
419 is stored through the next pointer,
420 which must be a pointer to
424 a conversion, although it can be suppressed with the
430 character is defined in the program's locale (category
433 For backwards compatibility, a
437 causes an immediate return of
443 the number of input items assigned, which can be fewer than provided
444 for, or even zero, in the event of a matching failure.
446 indicates that, while there was input available,
447 no conversions were assigned;
448 typically this is due to an invalid input character,
449 such as an alphabetic character for a
454 is returned if an input failure occurs before any conversion such as an
456 If an error or end-of-file occurs after conversion
458 the number of conversions which were successfully completed is returned.
479 Earlier implementations of
482 .Cm \&%D , \&%E , \&%F , \&%O
485 as their lowercase equivalents with an
490 treated an unknown conversion character as
494 depending on its case.
495 This functionality has been removed.
497 Numerical strings are truncated to 512 characters; for example,
508 modifiers for positional arguments are not implemented.
512 family of functions do not correctly handle multibyte characters in the