Debian Codegraph @

upstream/debian-unstable/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 2026-02-16 "Linux man-pages 6.18"
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 .BI w N
366 A following integer conversion corresponds to
367 an integer of a width of
368 .I N
369 bits
370 (C23).
371 .TP
372 .B z
373 As for
374 .BR h ,
375 but the next pointer is
376 a pointer to a
377 .IR size_t .
378 This modifier was introduced in C99.
379 .P
380 The following
381 .I "conversion specifiers"
382 are available:
383 .TP
384 .B %
385 Matches a literal \[aq]%\[aq].
386 That is,
387 .B %\&%
388 in the format string matches a
389 single input \[aq]%\[aq] character.
390 No conversion is done (but initial white space characters are discarded),
391 and assignment does not occur.
392 .TP
393 .B d
394 Matches an optionally signed decimal integer;
395 the next pointer must be
396 a pointer to
397 .IR int .
398 .\" .TP
399 .\" .B D
400 .\" Equivalent to
401 .\" .IR ld ;
402 .\" this exists only for backward compatibility.
403 .\" (Note: thus only in libc4
404 .\" In libc5 and glibc the
405 .\" .B %D
406 .\" is silently ignored, causing old programs to fail mysteriously.)
407 .TP
408 .B i
409 Matches an optionally signed integer;
410 the next pointer must be
411 a pointer to
412 .IR int .
413 The integer is read in base 16 if it begins with
414 .I 0x
415 or
416 .IR 0X ,
417 in base 8 if it begins with
418 .IR 0 ,
419 and in base 10 otherwise.
420 Only characters that correspond to the base are used.
421 .TP
422 .B o
423 Matches an unsigned octal integer;
424 the next pointer must be
425 a pointer to
426 .IR "unsigned int" .
427 .TP
428 .B u
429 Matches an unsigned decimal integer;
430 the next pointer must be
431 a pointer to
432 .IR "unsigned int" .
433 .TP
434 .B x
435 Matches an unsigned hexadecimal integer
436 (that may optionally begin with a prefix of
437 .I 0x
438 or
439 .IR 0X ,
440 which is discarded);
441 the next pointer must be
442 a pointer to
443 .IR "unsigned int" .
444 .TP
445 .B X
446 Equivalent to
447 .BR x .
448 .TP
449 .B f
450 Matches an optionally signed floating-point number;
451 the next pointer must be
452 a pointer to
453 .IR float .
454 .TP
455 .B e
456 Equivalent to
457 .BR f .
458 .TP
459 .B g
460 Equivalent to
461 .BR f .
462 .TP
463 .B E
464 Equivalent to
465 .BR f .
466 .TP
467 .B a
468 (C99) Equivalent to
469 .BR f .
470 .TP
471 .B s
472 Matches a sequence of non-white-space characters;
473 the next pointer must be
474 a pointer to
475 the initial element of a character array
476 that is long enough to hold
477 the input sequence and the terminating null byte (\[aq]\[rs]0\[aq]),
478 which is added automatically.
479 The input string stops at white space or at the maximum field width,
480 whichever occurs first.
481 .TP
482 .B c
483 Matches a sequence of characters whose length is specified by the
484 .I maximum field width
485 (default 1);
486 the next pointer must be
487 a pointer to
488 .IR char ,
489 and there must be enough room for all the characters
490 (no terminating null byte is added).
491 The usual skip of leading white space is suppressed.
492 To skip white space first, use an explicit space in the format.
493 .\" glibc commit 2b16c76609350ec887d49afd4447743da38f7fab
494 This conversion only succeeds
495 if the number of characters specified by the maximum field
496 can be matched.
497 .TP
498 .B \&[
499 Matches a nonempty sequence of characters from the specified set of
500 accepted characters;
501 the next pointer must be
502 a pointer to
503 .IR char ,
504 and there must be enough room for all the characters in the string,
505 plus a terminating null byte.
506 The usual skip of leading white space is suppressed.
507 The string is to be made up of characters in (or not in) a particular set;
508 the set is defined by the characters between the open bracket
509 .B [
510 character and a close bracket
511 .B ]
512 character.
513 The set
514 .I excludes
515 those characters if the first character after the open bracket is a
516 circumflex
517 .RB ( \[ha] ).
518 To include a close bracket in the set,
519 make it the first character after the open bracket or the circumflex;
520 any other position will end the set.
521 The hyphen character
522 .B \-
523 is also special;
524 when placed between two other characters,
525 it adds all intervening characters to the set.
526 To include a hyphen,
527 make it the last character before the final close bracket.
528 For instance,
529 .B [\[ha]]0\-9\-]
530 means
531 the set "everything except close bracket, zero through nine, and hyphen".
532 The string ends with the appearance of a character not in the
533 (or, with a circumflex, in)
534 set
535 or when the field width runs out.
536 .TP
537 .B p
538 Matches a pointer value (as printed by
539 .B %p
540 in
541 .BR printf (3));
542 the next pointer must be
543 a pointer to a pointer to
544 .IR void .
545 .TP
546 .B n
547 Nothing is expected;
548 instead,
549 the number of characters consumed thus far from the input
550 is stored through the next pointer,
551 which must be
552 a pointer to
553 .IR int ,
554 or variant whose size matches the
555 (optionally) supplied integer length modifier.
556 This is
557 .I not
558 a conversion and does
559 .I not
560 increase the count returned by the function.
561 The assignment can be suppressed with the
562 .B *
563 assignment-suppression character, but the effect on the
564 return value is undefined.
565 Therefore
566 .B %*n
567 conversions should not be used.
568 .SH RETURN VALUE
569 On success, these functions return the number of input items
570 successfully matched and assigned;
571 this can be fewer than provided for,
572 or even zero, in the event of an early matching failure.
573 .P
574 The value
575 .B EOF
576 is returned if the end of input is reached before either the first
577 successful conversion or a matching failure occurs.
578 .SH ERRORS
579 .TP
580 .B EILSEQ
581 Input byte sequence does not form a valid character.
582 .TP
583 .B EINVAL
584 Not enough arguments;
585 or
586 .I format
587 is NULL.
588 .TP
589 .B ENOMEM
590 Out of memory.
591 .SH ATTRIBUTES
592 For an explanation of the terms used in this section, see
593 .BR attributes (7).
594 .TS
595 allbox;
596 lbx lb lb
597 l l l.
598 Interface Attribute Value
599 T{
600 .na
601 .nh
602 .BR sscanf (),
603 .BR vsscanf ()
604 T} Thread safety MT-Safe locale
605 .TE
606 .SH STANDARDS
607 C11, POSIX.1-2008.
608 .SH HISTORY
609 C89, POSIX.1-2001.
610 .P
611 The
612 .B q
613 specifier is the 4.4BSD notation for
614 .IR "long long" ,
615 while
616 .B ll
617 or the usage of
618 .B L
619 in integer conversions is the GNU notation.
620 .P
621 The Linux version of these functions is based on the
622 .I GNU
623 .I libio
624 library.
625 Take a look at the
626 .BR info (1)
627 documentation of
628 .I GNU
629 .I libc (glibc-1.08)
630 for a more concise description.
631 .SH NOTES
632 .SS The 'a' assignment-allocation modifier
633 Originally, the GNU C library supported dynamic allocation for string inputs
634 (as a nonstandard extension) via the
635 .B a
636 character.
637 (This feature is present at least as far back as glibc 2.0.)
638 Thus, one could write the following to have
639 .BR sscanf ()
640 allocate a buffer for a string,
641 with a pointer to that buffer being returned in
642 .IR *buf :
643 .P
644 .in +4n
645 .EX
646 char *buf;
647 sscanf(str, "%as", &buf);
648 .EE
649 .in
650 .P
651 The use of the letter
652 .B a
653 for this purpose was problematic, since
654 .B a
655 is also specified by the ISO C standard as a synonym for
656 .B f
657 (floating-point input).
658 POSIX.1-2008 instead specifies the
659 .B m
660 modifier for assignment allocation (as documented in DESCRIPTION, above).
661 .P
662 Note that the
663 .B a
664 modifier is not available if the program is compiled with
665 .I gcc\~\-std=c99
666 or
667 .I gcc\~\-D_ISOC99_SOURCE
668 (unless
669 .B _GNU_SOURCE
670 is also specified), in which case the
671 .B a
672 is interpreted as a specifier for floating-point numbers (see above).
673 .P
674 Support for the
675 .B m
676 modifier was added to glibc 2.7,
677 and new programs should use that modifier instead of
678 .BR a .
679 .P
680 As well as being standardized by POSIX, the
681 .B m
682 modifier has the following further advantages over
683 the use of
684 .BR a :
685 .IP \[bu] 3
686 It may also be applied to
687 .B %c
688 conversion specifiers (e.g.,
689 .BR %3mc ).
690 .IP \[bu]
691 It avoids ambiguity with respect to the
692 .B %a
693 floating-point conversion specifier (and is unaffected by
694 .I gcc\~\-std=c99
695 etc.).
696 .SH BUGS
697 .SS Numeric conversion specifiers
698 Use of the numeric conversion specifiers produces undefined behavior
699 for invalid input.
700 See
701 .UR https:\://port70.net/\:%7Ensz/\:c/\:c11/\:n1570.html\:#7.21.6.2p10
702 C11 7.21.6.2/10
703 .UE .
704 This is a bug in the ISO C standard,
705 and not an inherent design issue with the API.
706 However,
707 current implementations are not safe from that bug,
708 so it is not recommended to use them.
709 Instead,
710 programs should use functions such as
711 .BR strtol (3)
712 to parse numeric input.
713 Alternatively,
714 mitigate it by specifying a maximum field width.
715 .SS Nonstandard modifiers
716 These functions are fully C99 conformant, but provide the
717 additional modifiers
718 .B q
719 and
720 .B a
721 as well as an additional behavior of the
722 .B L
723 and
724 .B ll
725 modifiers.
726 The latter may be considered to be a bug, as it changes the
727 behavior of modifiers defined in C99.
728 .P
729 Some combinations of the type modifiers and conversion
730 specifiers defined by C99 do not make sense
731 (e.g.,
732 .BR "%Ld" ).
733 While they may have a well-defined behavior on Linux, this need not
734 to be so on other systems.
735 Therefore it usually is better to use
736 modifiers that are not defined by C99 at all, that is, use
737 .B q
738 instead of
739 .B L
740 in combination with
741 .BR d ,
742 .BR i ,
743 .BR o ,
744 .BR u ,
745 .BR x ,
746 and
747 .B X
748 conversions or
749 .BR ll .
750 .P
751 The usage of
752 .B q
753 is not the same as on 4.4BSD,
754 as it may be used in float conversions equivalently to
755 .BR L .
756 .SH EXAMPLES
757 To use the dynamic allocation conversion specifier, specify
758 .B m
759 as a length modifier (thus
760 .B %ms
761 or
762 .BR %m[ \f[I]range\f[] ] ).
763 The caller must
764 .BR free (3)
765 the returned string, as in the following example:
766 .P
767 .in +4n
768 .EX
769 char *p;
770 int n;
771 \&
772 errno = 0;
773 n = sscanf(str, "%m[a\-z]", &p);
774 if (n == 1) {
775 printf("read: %s\[rs]n", p);
776 free(p);
777 } else if (errno != 0) {
778 perror("sscanf");
779 } else {
780 fprintf(stderr, "No matching characters\[rs]n");
781 }
782 .EE
783 .in
784 .P
785 As shown in the above example, it is necessary to call
786 .BR free (3)
787 only if the
788 .BR sscanf ()
789 call successfully read a string.
790 .SH SEE ALSO
791 .BR getc (3),
792 .BR printf (3),
793 .BR setlocale (3),
794 .BR strtod (3),
795 .BR strtol (3),
796 .BR strtoul (3)