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. 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.
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
36 .\" @(#)scanf.3 8.2 (Berkeley) 12/11/93
49 .Nd input format conversion
55 .Fn scanf "const char * restrict format" ...
57 .Fn fscanf "FILE * restrict stream" "const char * restrict format" ...
59 .Fn sscanf "const char * restrict str" "const char * restrict format" ...
62 .Fn vscanf "const char * restrict format" "va_list ap"
64 .Fn vsscanf "const char * restrict str" "const char * restrict format" "va_list ap"
66 .Fn vfscanf "FILE * restrict stream" "const char * restrict format" "va_list ap"
70 family of functions scans input according to a
73 This format may contain
74 .Em conversion specifiers ;
75 the results from such conversions, if any,
76 are stored through the
82 reads input from the standard input stream
85 reads input from the stream pointer
89 reads its input from the character string pointed to by
96 and reads input from the stream pointer
98 using a variable argument list of pointers (see
102 function scans a variable argument list from the standard input and
105 function scans it from a string;
106 these are analogous to
111 functions respectively.
114 argument must correspond properly with
115 each successive conversion specifier
119 All conversions are introduced by the
121 (percent sign) character.
125 may also contain other characters.
126 White space (such as blanks, tabs, or newlines) in the
128 string match any amount of white space, including none, in the input.
132 when an input character does not match such a format character.
134 when an input conversion cannot be made (see below).
138 character introducing a conversion
139 there may be a number of
141 characters, as follows:
142 .Bl -tag -width ".Cm l No (ell)"
144 Suppresses assignment.
145 The conversion that follows occurs as usual, but no pointer is used;
146 the result of the conversion is simply discarded.
148 Indicates that the conversion will be one of
152 and the next pointer is a pointer to a
157 Indicates that the conversion will be one of
161 and the next pointer is a pointer to a
166 Indicates that the conversion will be one of
170 and the next pointer is a pointer to a
174 that the conversion will be one of
178 and the next pointer is a pointer to
182 or that the conversion will be one of
187 and the next pointer is a pointer to an array of
191 .It Cm ll No (ell ell)
192 Indicates that the conversion will be one of
196 and the next pointer is a pointer to a
201 Indicates that the conversion will be one of
205 and the next pointer is a pointer to
208 Indicates that the conversion will be one of
212 and the next pointer is a pointer to a
217 Indicates that the conversion will be one of
221 and the next pointer is a pointer to a
226 Indicates that the conversion will be one of
230 and the next pointer is a pointer to a
236 Indicates that the conversion will be one of
240 and the next pointer is a pointer to a
246 In addition to these flags,
247 there may be an optional maximum field width,
248 expressed as a decimal integer,
252 If no width is given,
255 is used (with one exception, below);
256 otherwise at most this many bytes are scanned
257 in processing the conversion.
263 conversions, the field width specifies the maximum number
264 of multibyte characters that will be scanned.
265 Before conversion begins,
266 most conversions skip white space;
267 this white space is not counted against the field width.
269 The following conversions are available:
277 matches a single input
280 No conversion is done, and assignment does not occur.
282 Matches an optionally signed decimal integer;
283 the next pointer must be a pointer to
286 Matches an optionally signed integer;
287 the next pointer must be a pointer to
289 The integer is read in base 16 if it begins
294 in base 8 if it begins with
296 and in base 10 otherwise.
297 Only characters that correspond to the base are used.
299 Matches an octal integer;
300 the next pointer must be a pointer to
303 Matches an optionally signed decimal integer;
304 the next pointer must be a pointer to
307 Matches an optionally signed hexadecimal integer;
308 the next pointer must be a pointer to
310 .It Cm a , A , e , E , f , F , g , G
311 Matches a floating-point number in the style of
313 The next pointer must be a pointer to
321 Matches a sequence of non-white-space characters;
322 the next pointer must be a pointer to
324 and the array must be large enough to accept all the sequence and the
328 The input string stops at white space
329 or at the maximum field width, whichever occurs first.
333 qualifier is present, the next pointer must be a pointer to
335 into which the input will be placed after conversion by
341 Matches a sequence of
344 characters (default 1);
345 the next pointer must be a pointer to
347 and there must be enough room for all the characters
351 The usual skip of leading white space is suppressed.
352 To skip white space first, use an explicit space in the format.
356 qualifier is present, the next pointer must be a pointer to
358 into which the input will be placed after conversion by
364 Matches a nonempty sequence of characters from the specified set
365 of accepted characters;
366 the next pointer must be a pointer to
368 and there must be enough room for all the characters in the string,
372 The usual skip of leading white space is suppressed.
373 The string is to be made up of characters in
376 the set is defined by the characters between the open bracket
385 if the first character after the open bracket is a circumflex
387 To include a close bracket in the set,
388 make it the first character after the open bracket
390 any other position will end the set.
394 when placed between two other characters,
395 it adds all intervening characters to the set.
397 make it the last character before the final close bracket.
401 .Dq "everything except close bracket, zero through nine, and hyphen" .
402 The string ends with the appearance of a character not in the
403 (or, with a circumflex, in) set
404 or when the field width runs out.
408 qualifier is present, the next pointer must be a pointer to
410 into which the input will be placed after conversion by
413 Matches a pointer value (as printed by
417 the next pointer must be a pointer to
421 instead, the number of characters consumed thus far from the input
422 is stored through the next pointer,
423 which must be a pointer to
427 a conversion, although it can be suppressed with the
433 character is defined in the program's locale (category
436 For backwards compatibility, a
440 causes an immediate return of
446 the number of input items assigned, which can be fewer than provided
447 for, or even zero, in the event of a matching failure.
449 indicates that, while there was input available,
450 no conversions were assigned;
451 typically this is due to an invalid input character,
452 such as an alphabetic character for a
457 is returned if an input failure occurs before any conversion such as an
459 If an error or end-of-file occurs after conversion
461 the number of conversions which were successfully completed is returned.
482 Earlier implementations of
485 .Cm \&%D , \&%E , \&%F , \&%O
488 as their lowercase equivalents with an
493 treated an unknown conversion character as
497 depending on its case.
498 This functionality has been removed.
500 Numerical strings are truncated to 512 characters; for example,
511 modifiers for positional arguments are not implemented.
515 family of functions do not correctly handle multibyte characters in the