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 .\" 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.
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: head/lib/libc/stdio/scanf.3 235363 2012-05-12 20:27:13Z joel $
45 .Nd input format conversion
51 .Fn scanf "const char * restrict format" ...
53 .Fn fscanf "FILE * restrict stream" "const char * restrict format" ...
55 .Fn sscanf "const char * restrict str" "const char * restrict format" ...
58 .Fn vscanf "const char * restrict format" "va_list ap"
60 .Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap"
62 .Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap"
66 family of functions scans input according to a
69 This format may contain
70 .Em conversion specifiers ;
71 the results from such conversions, if any,
72 are stored through the
78 reads input from the standard input stream
81 reads input from the stream pointer
85 reads its input from the character string pointed to by
92 and reads input from the stream pointer
94 using a variable argument list of pointers (see
98 function scans a variable argument list from the standard input and
101 function scans it from a string;
102 these are analogous to
107 functions respectively.
110 argument must correspond properly with
111 each successive conversion specifier
115 All conversions are introduced by the
117 (percent sign) character.
121 may also contain other characters.
122 White space (such as blanks, tabs, or newlines) in the
124 string match any amount of white space, including none, in the input.
128 when an input character does not match such a format character.
130 when an input conversion cannot be made (see below).
134 character introducing a conversion
135 there may be a number of
137 characters, as follows:
138 .Bl -tag -width ".Cm l No (ell)"
140 Suppresses assignment.
141 The conversion that follows occurs as usual, but no pointer is used;
142 the result of the conversion is simply discarded.
144 Indicates that the conversion will be one of
148 and the next pointer is a pointer to a
153 Indicates that the conversion will be one of
157 and the next pointer is a pointer to a
162 Indicates that the conversion will be one of
166 and the next pointer is a pointer to a
170 that the conversion will be one of
174 and the next pointer is a pointer to
178 or that the conversion will be one of
183 and the next pointer is a pointer to an array of
187 .It Cm ll No (ell ell)
188 Indicates that the conversion will be one of
192 and the next pointer is a pointer to a
196 or that the conversion will be one of
200 and the next pointer is a pointer to
204 Indicates that the conversion will be one of
208 and the next pointer is a pointer to
210 or that the conversion will be one of
214 and the next pointer is a pointer to a
220 Indicates that the conversion will be one of
224 and the next pointer is a pointer to a
229 Indicates that the conversion will be one of
233 and the next pointer is a pointer to a
238 Indicates that the conversion will be one of
242 and the next pointer is a pointer to a
248 Indicates that the conversion will be one of
252 and the next pointer is a pointer to a
258 In addition to these flags,
259 there may be an optional maximum field width,
260 expressed as a decimal integer,
264 If no width is given,
267 is used (with one exception, below);
268 otherwise at most this many bytes are scanned
269 in processing the conversion.
275 conversions, the field width specifies the maximum number
276 of multibyte characters that will be scanned.
277 Before conversion begins,
278 most conversions skip white space;
279 this white space is not counted against the field width.
281 The following conversions are available:
289 matches a single input
292 No conversion is done, and assignment does not occur.
294 Matches an optionally signed decimal integer;
295 the next pointer must be a pointer to
298 Matches an optionally signed integer;
299 the next pointer must be a pointer to
301 The integer is read in base 16 if it begins
306 in base 8 if it begins with
308 and in base 10 otherwise.
309 Only characters that correspond to the base are used.
311 Matches an octal integer;
312 the next pointer must be a pointer to
315 Matches an optionally signed decimal integer;
316 the next pointer must be a pointer to
319 Matches an optionally signed hexadecimal integer;
320 the next pointer must be a pointer to
322 .It Cm a , A , e , E , f , F , g , G
323 Matches a floating-point number in the style of
325 The next pointer must be a pointer to
334 Matches a sequence of non-white-space characters;
335 the next pointer must be a pointer to
337 and the array must be large enough to accept all the sequence and the
341 The input string stops at white space
342 or at the maximum field width, whichever occurs first.
346 qualifier is present, the next pointer must be a pointer to
348 into which the input will be placed after conversion by
354 Matches a sequence of
357 characters (default 1);
358 the next pointer must be a pointer to
360 and there must be enough room for all the characters
364 The usual skip of leading white space is suppressed.
365 To skip white space first, use an explicit space in the format.
369 qualifier is present, the next pointer must be a pointer to
371 into which the input will be placed after conversion by
377 Matches a nonempty sequence of characters from the specified set
378 of accepted characters;
379 the next pointer must be a pointer to
381 and there must be enough room for all the characters in the string,
385 The usual skip of leading white space is suppressed.
386 The string is to be made up of characters in
389 the set is defined by the characters between the open bracket
398 if the first character after the open bracket is a circumflex
400 To include a close bracket in the set,
401 make it the first character after the open bracket
403 any other position will end the set.
407 when placed between two other characters,
408 it adds all intervening characters to the set.
410 make it the last character before the final close bracket.
414 .Dq "everything except close bracket, zero through nine, and hyphen" .
415 The string ends with the appearance of a character not in the
416 (or, with a circumflex, in) set
417 or when the field width runs out.
421 qualifier is present, the next pointer must be a pointer to
423 into which the input will be placed after conversion by
426 Matches a pointer value (as printed by
430 the next pointer must be a pointer to
434 instead, the number of characters consumed thus far from the input
435 is stored through the next pointer,
436 which must be a pointer to
440 a conversion, although it can be suppressed with the
446 character is defined in the program's locale (category
449 For backwards compatibility, a
453 causes an immediate return of
459 the number of input items assigned, which can be fewer than provided
460 for, or even zero, in the event of a matching failure.
462 indicates that, while there was input available,
463 no conversions were assigned;
464 typically this is due to an invalid input character,
465 such as an alphabetic character for a
470 is returned if an input failure occurs before any conversion such as an
472 If an error or end-of-file occurs after conversion
474 the number of conversions which were successfully completed is returned.
497 treats the length modifiers
501 as synonyms, so that the non-standard
511 Earlier implementations of
514 .Cm \&%D , \&%E , \&%F , \&%O
517 as their lowercase equivalents with an
522 treated an unknown conversion character as
526 depending on its case.
527 This functionality has been removed.
529 Numerical strings are truncated to 512 characters; for example,
540 modifiers for positional arguments are not implemented.
544 family of functions do not correctly handle multibyte characters in the