Debian Codegraph @

upstream/mageia-cauldron/man3/sscanf.3

raw
1 '\" t
2 .\" Copyright 1990-1991, The Regents of the University of California.
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH sscanf 3 2025-12-25 "Linux man-pages 6.17"
8 .SH NAME
9 sscanf, vsscanf \- input string format conversion
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
17 .BI "int sscanf(const char *restrict " str ,
18 .BI " const char *restrict " format ", ...);"
19 .P
20 .B #include <stdarg.h>
21 .P
22 .BI "int vsscanf(const char *restrict " str ,
23 .BI " const char *restrict " format ", va_list " ap );
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
31 .BR vsscanf ():
32 .nf
33 _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR sscanf ()
38 family of functions scans formatted input according to
39 .I format
40 as described below.
41 This format may contain
42 .IR "conversion specifications" ;
43 the results from such conversions, if any,
44 are stored in the locations pointed to by the
45 .I pointer
46 arguments that follow
47 .IR format .
48 Each
49 .I pointer
50 argument must be of a type that is appropriate for the value returned
51 by the corresponding conversion specification.
52 .P
53 If the number of conversion specifications in
54 .I format
55 exceeds the number of
56 .I pointer
57 arguments, the results are undefined.
58 If the number of
59 .I pointer
60 arguments exceeds the number of conversion specifications, then the excess
61 .I pointer
62 arguments are evaluated, but are otherwise ignored.
63 .P
64 .BR sscanf ()
65 These functions
66 read their input from the string pointed to by
67 .IR str .
68 .P
69 The
70 .BR vsscanf ()
71 function is analogous to
72 .BR vsprintf (3).
73 .P
74 The
75 .I format
76 string consists of a sequence of
77 .I directives
78 which describe how to process the sequence of input characters.
79 If processing of a directive fails, no further input is read, and
80 .BR sscanf ()
81 returns.
82 A "failure" can be either of the following:
83 .IR "input failure" ,
84 meaning that input characters were unavailable, or
85 .IR "matching failure" ,
86 meaning that the input was inappropriate (see below).
87 .P
88 A directive is one of the following:
89 .TP
90 \[bu]
91 A sequence of white-space characters
92 (space, tab, newline, etc.;
93 see
94 .BR isspace (3)).
95 This directive matches any amount of white space,
96 including none, in the input.
97 .TP
98 \[bu]
99 An ordinary character (i.e., one other than white space or \[aq]%\[aq]).
100 This character must exactly match the next character of input.
101 .TP
102 \[bu]
103 A conversion specification,
104 which commences with a \[aq]%\[aq] (percent) character.
105 A sequence of characters from the input is converted according to
106 this specification, and the result is placed in the corresponding
107 .I pointer
108 argument.
109 If the next item of input does not match the conversion specification,
110 the conversion fails\[em]this is a
111 .IR "matching failure" .
112 .P
113 Each
114 .I conversion specification
115 in
116 .I format
117 begins with either the character \[aq]%\[aq] or the character sequence
118 .RB \[dq] % \f[I]n\f[] $ \[dq]
119 (see below for the distinction) followed by:
120 .TP
121 \[bu]
122 An optional \[aq]*\[aq] assignment-suppression character:
123 .BR sscanf ()
124 reads input as directed by the conversion specification,
125 but discards the input.
126 No corresponding
127 .I pointer
128 argument is required, and this specification is not
129 included in the count of successful assignments returned by
130 .BR sscanf ().
131 .TP
132 \[bu]
133 For decimal conversions, an optional quote character (\[aq]).
134 This specifies that the input number may include thousands'
135 separators as defined by the
136 .B LC_NUMERIC
137 category of the current locale.
138 (See
139 .BR setlocale (3).)
140 The quote character may precede or follow the \[aq]*\[aq]
141 assignment-suppression character.
142 .TP
143 \[bu]
144 An optional \[aq]m\[aq] character.
145 This is used with string conversions
146 .RI ( %s ,
147 .IR %c ,
148 .IR %[ ),
149 and relieves the caller of the
150 need to allocate a corresponding buffer to hold the input: instead,
151 .BR sscanf ()
152 allocates a buffer of sufficient size,
153 and assigns the address of this buffer to the corresponding
154 .I pointer
155 argument,
156 which should be
157 a pointer to a
158 .I "char\ *"
159 variable (this variable does not need to be initialized before the call).
160 The caller should subsequently
161 .BR free (3)
162 this buffer when it is no longer required.
163 .TP
164 \[bu]
165 An optional decimal integer which specifies the
166 .IR "maximum field width" .
167 Reading of characters stops either when this maximum is reached or
168 when a nonmatching character is found, whichever happens first.
169 Most conversions discard initial white space characters (the exceptions
170 are noted below),
171 and these discarded characters don't count toward the maximum field width.
172 String input conversions store a terminating null byte (\[aq]\[rs]0\[aq])
173 to mark the end of the input;
174 the maximum field width does not include this terminator.
175 Some conversions require exactly
176 the number of characters specified in the maximum field width,
177 or they fail.
178 .TP
179 \[bu]
180 An optional
181 .IR "type modifier character" .
182 For example, the
183 .B l
184 type modifier is used with integer conversions such as
185 .B %d
186 to specify that the corresponding
187 .I pointer
188 argument refers to a
189 .I "long"
190 rather than
191 a pointer to an
192 .IR int .
193 .TP
194 \[bu]
195 A
196 .I "conversion specifier"
197 that specifies the type of input conversion to be performed.
198 .P
199 The conversion specifications in
200 .I format
201 are of two forms, either beginning with \[aq]%\[aq] or beginning with
202 .RB \[dq] % \f[I]n\f[] $ \[dq].
203 The two forms should not be mixed in the same
204 .I format
205 string, except that a string containing
206 .RB \[dq] % \f[I]n\f[] $ \[dq]
207 specifications can include
208 .B %%
209 and
210 .BR %* .
211 If
212 .I format
213 contains \[aq]%\[aq]
214 specifications, then these correspond in order with successive
215 .I pointer
216 arguments.
217 In the
218 .RB \[dq] % \f[I]n\f[] $ \[dq]
219 form (which is specified in POSIX.1-2001, but not C99),
220 .I n
221 is a decimal integer that specifies that the converted input should
222 be placed in the location referred to by the
223 .IR n -th
224 .I pointer
225 argument following
226 .IR format .
227 .SS Conversions
228 The following
229 .I "type modifier characters"
230 can appear in a conversion specification:
231 .TP
232 .B h
233 Indicates that the conversion will be one of
234 .BR d ,
235 .BR i ,
236 .BR o ,
237 .BR u ,
238 .BR x ,
239 .BR X ,
240 or
241 .BR n ,
242 and the next pointer is
243 a pointer to a
244 .I short
245 or
246 .I unsigned short
247 (rather than
248 .IR int ).
249 .TP
250 .B hh
251 As for
252 .BR h ,
253 but the next pointer is
254 a pointer to a
255 .I signed char
256 or
257 .IR "unsigned char" .
258 .TP
259 .B j
260 As for
261 .BR h ,
262 but the next pointer is
263 a pointer to an
264 .I intmax_t
265 or a
266 .IR uintmax_t .
267 This modifier was introduced in C99.
268 .TP
269 .B l
270 Indicates either that the conversion will be one of
271 .BR d ,
272 .BR i ,
273 .BR o ,
274 .BR u ,
275 .BR x ,
276 .BR X ,
277 or
278 .BR n ,
279 and the next pointer is
280 a pointer to a
281 .I long
282 or
283 .I unsigned long
284 (rather than
285 .IR int ),
286 or that the conversion will be one of
287 .BR e ,
288 .BR f ,
289 or
290 .BR g ,
291 and the next pointer is
292 a pointer to
293 .I double
294 (rather than
295 .IR float ).
296 If used with
297 .B %c
298 or
299 .BR %s ,
300 the corresponding parameter is considered as
301 a pointer to a wide character or wide-character string respectively.
302 .\" This use of l was introduced in Amendment 1 to ISO C90.
303 .TP
304 .B ll
305 (ell-ell)
306 Indicates that the conversion will be one of
307 .BR b ,
308 .BR d ,
309 .BR i ,
310 .BR o ,
311 .BR u ,
312 .BR x ,
313 .BR X ,
314 or
315 .BR n ,
316 and the next pointer is
317 a pointer to a
318 .I long long
319 or
320 .I unsigned long long
321 (rather than
322 .IR int ).
323 .TP
324 .B L
325 Indicates that the conversion will be either
326 .BR e ,
327 .BR f ,
328 or
329 .BR g ,
330 and the next pointer is
331 a pointer to
332 .I "long double"
333 or
334 (as a GNU extension)
335 the conversion will be
336 .BR d ,
337 .BR i ,
338 .BR o ,
339 .BR u ,
340 or
341 .BR x ,
342 and the next pointer is
343 a pointer to
344 .IR "long long" .
345 .\" MTK, Jul 05: The following is no longer true for modern
346 .\" ANSI C (i.e., C99):
347 .\" (Note that long long is not an
348 .\" ANSI C
349 .\" type. Any program using this will not be portable to all
350 .\" architectures).
351 .TP
352 .B q
353 equivalent to
354 .BR L .
355 This specifier does not exist in ANSI C.
356 .TP
357 .B t
358 As for
359 .BR h ,
360 but the next pointer is
361 a pointer to a
362 .IR ptrdiff_t .
363 This modifier was introduced in C99.
364 .TP
365 .B z
366 As for
367 .BR h ,
368 but the next pointer is
369 a pointer to a
370 .IR size_t .
371 This modifier was introduced in C99.
372 .P
373 The following
374 .I "conversion specifiers"
375 are available:
376 .TP
377 .B %
378 Matches a literal \[aq]%\[aq].
379 That is,
380 .B %\&%
381 in the format string matches a
382 single input \[aq]%\[aq] character.
383 No conversion is done (but initial white space characters are discarded),
384 and assignment does not occur.
385 .TP
386 .B d
387 Matches an optionally signed decimal integer;
388 the next pointer must be
389 a pointer to
390 .IR int .
391 .\" .TP
392 .\" .B D
393 .\" Equivalent to
394 .\" .IR ld ;
395 .\" this exists only for backward compatibility.
396 .\" (Note: thus only in libc4
397 .\" In libc5 and glibc the
398 .\" .B %D
399 .\" is silently ignored, causing old programs to fail mysteriously.)
400 .TP
401 .B i
402 Matches an optionally signed integer;
403 the next pointer must be
404 a pointer to
405 .IR int .
406 The integer is read in base 16 if it begins with
407 .I 0x
408 or
409 .IR 0X ,
410 in base 8 if it begins with
411 .IR 0 ,
412 and in base 10 otherwise.
413 Only characters that correspond to the base are used.
414 .TP
415 .B o
416 Matches an unsigned octal integer;
417 the next pointer must be
418 a pointer to
419 .IR "unsigned int" .
420 .TP
421 .B u
422 Matches an unsigned decimal integer;
423 the next pointer must be
424 a pointer to
425 .IR "unsigned int" .
426 .TP
427 .B x
428 Matches an unsigned hexadecimal integer
429 (that may optionally begin with a prefix of
430 .I 0x
431 or
432 .IR 0X ,
433 which is discarded);
434 the next pointer must be
435 a pointer to
436 .IR "unsigned int" .
437 .TP
438 .B X
439 Equivalent to
440 .BR x .
441 .TP
442 .B f
443 Matches an optionally signed floating-point number;
444 the next pointer must be
445 a pointer to
446 .IR float .
447 .TP
448 .B e
449 Equivalent to
450 .BR f .
451 .TP
452 .B g
453 Equivalent to
454 .BR f .
455 .TP
456 .B E
457 Equivalent to
458 .BR f .
459 .TP
460 .B a
461 (C99) Equivalent to
462 .BR f .
463 .TP
464 .B s
465 Matches a sequence of non-white-space characters;
466 the next pointer must be
467 a pointer to
468 the initial element of a character array
469 that is long enough to hold
470 the input sequence and the terminating null byte (\[aq]\[rs]0\[aq]),
471 which is added automatically.
472 The input string stops at white space or at the maximum field width,
473 whichever occurs first.
474 .TP
475 .B c
476 Matches a sequence of characters whose length is specified by the
477 .I maximum field width
478 (default 1);
479 the next pointer must be
480 a pointer to
481 .IR char ,
482 and there must be enough room for all the characters
483 (no terminating null byte is added).
484 The usual skip of leading white space is suppressed.
485 To skip white space first, use an explicit space in the format.
486 .\" glibc commit 2b16c76609350ec887d49afd4447743da38f7fab
487 This conversion only succeeds
488 if the number of characters specified by the maximum field
489 can be matched.
490 .TP
491 .B \&[
492 Matches a nonempty sequence of characters from the specified set of
493 accepted characters;
494 the next pointer must be
495 a pointer to
496 .IR char ,
497 and there must be enough room for all the characters in the string,
498 plus a terminating null byte.
499 The usual skip of leading white space is suppressed.
500 The string is to be made up of characters in (or not in) a particular set;
501 the set is defined by the characters between the open bracket
502 .B [
503 character and a close bracket
504 .B ]
505 character.
506 The set
507 .I excludes
508 those characters if the first character after the open bracket is a
509 circumflex
510 .RB ( \[ha] ).
511 To include a close bracket in the set,
512 make it the first character after the open bracket or the circumflex;
513 any other position will end the set.
514 The hyphen character
515 .B \-
516 is also special;
517 when placed between two other characters,
518 it adds all intervening characters to the set.
519 To include a hyphen,
520 make it the last character before the final close bracket.
521 For instance,
522 .B [\[ha]]0\-9\-]
523 means
524 the set "everything except close bracket, zero through nine, and hyphen".
525 The string ends with the appearance of a character not in the
526 (or, with a circumflex, in)
527 set
528 or when the field width runs out.
529 .TP
530 .B p
531 Matches a pointer value (as printed by
532 .B %p
533 in
534 .BR printf (3));
535 the next pointer must be
536 a pointer to a pointer to
537 .IR void .
538 .TP
539 .B n
540 Nothing is expected;
541 instead,
542 the number of characters consumed thus far from the input
543 is stored through the next pointer,
544 which must be
545 a pointer to
546 .IR int ,
547 or variant whose size matches the
548 (optionally) supplied integer length modifier.
549 This is
550 .I not
551 a conversion and does
552 .I not
553 increase the count returned by the function.
554 The assignment can be suppressed with the
555 .B *
556 assignment-suppression character, but the effect on the
557 return value is undefined.
558 Therefore
559 .B %*n
560 conversions should not be used.
561 .SH RETURN VALUE
562 On success, these functions return the number of input items
563 successfully matched and assigned;
564 this can be fewer than provided for,
565 or even zero, in the event of an early matching failure.
566 .P
567 The value
568 .B EOF
569 is returned if the end of input is reached before either the first
570 successful conversion or a matching failure occurs.
571 .SH ERRORS
572 .TP
573 .B EILSEQ
574 Input byte sequence does not form a valid character.
575 .TP
576 .B EINVAL
577 Not enough arguments;
578 or
579 .I format
580 is NULL.
581 .TP
582 .B ENOMEM
583 Out of memory.
584 .SH ATTRIBUTES
585 For an explanation of the terms used in this section, see
586 .BR attributes (7).
587 .TS
588 allbox;
589 lbx lb lb
590 l l l.
591 Interface Attribute Value
592 T{
593 .na
594 .nh
595 .BR sscanf (),
596 .BR vsscanf ()
597 T} Thread safety MT-Safe locale
598 .TE
599 .SH STANDARDS
600 C11, POSIX.1-2008.
601 .SH HISTORY
602 C89, POSIX.1-2001.
603 .P
604 The
605 .B q
606 specifier is the 4.4BSD notation for
607 .IR "long long" ,
608 while
609 .B ll
610 or the usage of
611 .B L
612 in integer conversions is the GNU notation.
613 .P
614 The Linux version of these functions is based on the
615 .I GNU
616 .I libio
617 library.
618 Take a look at the
619 .BR info (1)
620 documentation of
621 .I GNU
622 .I libc (glibc-1.08)
623 for a more concise description.
624 .SH NOTES
625 .SS The 'a' assignment-allocation modifier
626 Originally, the GNU C library supported dynamic allocation for string inputs
627 (as a nonstandard extension) via the
628 .B a
629 character.
630 (This feature is present at least as far back as glibc 2.0.)
631 Thus, one could write the following to have
632 .BR sscanf ()
633 allocate a buffer for a string,
634 with a pointer to that buffer being returned in
635 .IR *buf :
636 .P
637 .in +4n
638 .EX
639 char *buf;
640 sscanf(str, "%as", &buf);
641 .EE
642 .in
643 .P
644 The use of the letter
645 .B a
646 for this purpose was problematic, since
647 .B a
648 is also specified by the ISO C standard as a synonym for
649 .B f
650 (floating-point input).
651 POSIX.1-2008 instead specifies the
652 .B m
653 modifier for assignment allocation (as documented in DESCRIPTION, above).
654 .P
655 Note that the
656 .B a
657 modifier is not available if the program is compiled with
658 .I gcc\~\-std=c99
659 or
660 .I gcc\~\-D_ISOC99_SOURCE
661 (unless
662 .B _GNU_SOURCE
663 is also specified), in which case the
664 .B a
665 is interpreted as a specifier for floating-point numbers (see above).
666 .P
667 Support for the
668 .B m
669 modifier was added to glibc 2.7,
670 and new programs should use that modifier instead of
671 .BR a .
672 .P
673 As well as being standardized by POSIX, the
674 .B m
675 modifier has the following further advantages over
676 the use of
677 .BR a :
678 .IP \[bu] 3
679 It may also be applied to
680 .B %c
681 conversion specifiers (e.g.,
682 .BR %3mc ).
683 .IP \[bu]
684 It avoids ambiguity with respect to the
685 .B %a
686 floating-point conversion specifier (and is unaffected by
687 .I gcc\~\-std=c99
688 etc.).
689 .SH BUGS
690 .SS Numeric conversion specifiers
691 Use of the numeric conversion specifiers produces undefined behavior
692 for invalid input.
693 See
694 .UR https:\://port70.net/\:%7Ensz/\:c/\:c11/\:n1570.html\:#7.21.6.2p10
695 C11 7.21.6.2/10
696 .UE .
697 This is a bug in the ISO C standard,
698 and not an inherent design issue with the API.
699 However,
700 current implementations are not safe from that bug,
701 so it is not recommended to use them.
702 Instead,
703 programs should use functions such as
704 .BR strtol (3)
705 to parse numeric input.
706 Alternatively,
707 mitigate it by specifying a maximum field width.
708 .SS Nonstandard modifiers
709 These functions are fully C99 conformant, but provide the
710 additional modifiers
711 .B q
712 and
713 .B a
714 as well as an additional behavior of the
715 .B L
716 and
717 .B ll
718 modifiers.
719 The latter may be considered to be a bug, as it changes the
720 behavior of modifiers defined in C99.
721 .P
722 Some combinations of the type modifiers and conversion
723 specifiers defined by C99 do not make sense
724 (e.g.,
725 .BR "%Ld" ).
726 While they may have a well-defined behavior on Linux, this need not
727 to be so on other systems.
728 Therefore it usually is better to use
729 modifiers that are not defined by C99 at all, that is, use
730 .B q
731 instead of
732 .B L
733 in combination with
734 .BR d ,
735 .BR i ,
736 .BR o ,
737 .BR u ,
738 .BR x ,
739 and
740 .B X
741 conversions or
742 .BR ll .
743 .P
744 The usage of
745 .B q
746 is not the same as on 4.4BSD,
747 as it may be used in float conversions equivalently to
748 .BR L .
749 .SH EXAMPLES
750 To use the dynamic allocation conversion specifier, specify
751 .B m
752 as a length modifier (thus
753 .B %ms
754 or
755 .BR %m[ \f[I]range\f[] ] ).
756 The caller must
757 .BR free (3)
758 the returned string, as in the following example:
759 .P
760 .in +4n
761 .EX
762 char *p;
763 int n;
764 \&
765 errno = 0;
766 n = sscanf(str, "%m[a\-z]", &p);
767 if (n == 1) {
768 printf("read: %s\[rs]n", p);
769 free(p);
770 } else if (errno != 0) {
771 perror("sscanf");
772 } else {
773 fprintf(stderr, "No matching characters\[rs]n");
774 }
775 .EE
776 .in
777 .P
778 As shown in the above example, it is necessary to call
779 .BR free (3)
780 only if the
781 .BR sscanf ()
782 call successfully read a string.
783 .SH SEE ALSO
784 .BR getc (3),
785 .BR printf (3),
786 .BR setlocale (3),
787 .BR strtod (3),
788 .BR strtol (3),
789 .BR strtoul (3)