.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93
.\"
.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
-.\" modified to resemble the GNU libio setup used in the Linux libc
+.\" modified to resemble the GNU libio setup used in the Linux libc
.\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de
.\" Modified, aeb, 970121
+.\" 2005-07-14, mtk, added description of %n$ form; various text
+.\" incorporated from the GNU C library documentation ((C) The
+.\" Free Software Foundation); other parts substantially rewritten.
.\"
-.TH SCANF 3 1995-11-01 "LINUX MANPAGE" "Linux Programmer's Manual"
+.\" 2008-06-23, mtk
+.\" Add ERRORS section.
+.\" Document the 'a' and 'm' modifiers for dynamic string allocation.
+.\"
+.TH SCANF 3 2020-04-11 "GNU" "Linux Programmer's Manual"
.SH NAME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.na
-.BI "int scanf(const char *" format ", ..." );
-.br
-.BI "int fscanf(FILE *" stream ", const char *" format ", ..." );
-.br
-.BI "int sscanf(const char *" str ", const char *" format ", ..." );
-.sp
+.PP
+.BI "int scanf(const char *" format ", ...);"
+.BI "int fscanf(FILE *" stream ", const char *" format ", ...);"
+.BI "int sscanf(const char *" str ", const char *" format ", ...);"
+
.B #include <stdarg.h>
+.PP
.BI "int vscanf(const char *" format ", va_list " ap );
-.br
.BI "int vsscanf(const char *" str ", const char *" format ", va_list " ap );
-.br
.BI "int vfscanf(FILE *" stream ", const char *" format ", va_list " ap );
+.fi
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.ad l
+.PP
+.BR vscanf (),
+.BR vsscanf (),
+.BR vfscanf ():
+.RS 4
+_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
.ad
+.RE
.SH DESCRIPTION
The
-.B scanf
-family of functions scans input according to a
+.BR scanf ()
+family of functions scans input according to
.I format
-as described below. This format may contain
-.IR "conversion specifiers" ;
-the results from such conversions, if any, are stored through the
+as described below.
+This format may contain
+.IR "conversion specifications" ;
+the results from such conversions, if any,
+are stored in the locations pointed to by the
+.I pointer
+arguments that follow
+.IR format .
+Each
+.I pointer
+argument must be of a type that is appropriate for the value returned
+by the corresponding conversion specification.
+.PP
+If the number of conversion specifications in
+.I format
+exceeds the number of
+.I pointer
+arguments, the results are undefined.
+If the number of
.I pointer
-arguments. The
-.B scanf
+arguments exceeds the number of conversion specifications, then the excess
+.I pointer
+arguments are evaluated, but are otherwise ignored.
+.PP
+The
+.BR scanf ()
function reads input from the standard input stream
.IR stdin ,
-.B fscanf
+.BR fscanf ()
reads input from the stream pointer
.IR stream ,
and
-.B sscanf
+.BR sscanf ()
reads its input from the character string pointed to by
.IR str .
.PP
The
-.B vfscanf
+.BR vfscanf ()
function is analogous to
.BR vfprintf (3)
and reads input from the stream pointer
using a variable argument list of pointers (see
.BR stdarg (3).
The
-.B vscanf
+.BR vscanf ()
function scans a variable argument list from the standard input and the
-.B vsscanf
+.BR vsscanf ()
function scans it from a string; these are analogous to the
-.B vprintf
+.BR vprintf (3)
and
-.B vsprintf
+.BR vsprintf (3)
functions respectively.
.PP
-Each successive
-.I pointer
-argument must correspond properly with each successive conversion specifier
-(but see `suppression' below). All conversions are introduced by the
-.B %
-(percent sign) character. The
+The
.I format
-string may also contain other characters. White space (such as blanks,
-tabs, or newlines) in the
+string consists of a sequence of
+.I directives
+which describe how to process the sequence of input characters.
+If processing of a directive fails, no further input is read, and
+.BR scanf ()
+returns.
+A "failure" can be either of the following:
+.IR "input failure" ,
+meaning that input characters were unavailable, or
+.IR "matching failure" ,
+meaning that the input was inappropriate (see below).
+.PP
+A directive is one of the following:
+.TP
+\(bu
+A sequence of white-space characters (space, tab, newline, etc.; see
+.BR isspace (3)).
+This directive matches any amount of white space,
+including none, in the input.
+.TP
+\(bu
+An ordinary character (i.e., one other than white space or \(aq%\(aq).
+This character must exactly match the next character of input.
+.TP
+\(bu
+A conversion specification,
+which commences with a \(aq%\(aq (percent) character.
+A sequence of characters from the input is converted according to
+this specification, and the result is placed in the corresponding
+.I pointer
+argument.
+If the next item of input does not match the conversion specification,
+the conversion fails\(emthis is a
+.IR "matching failure" .
+.PP
+Each
+.I conversion specification
+in
.I format
-string match any amount of white space, including none, in the input.
-Everything else matches only itself. Scanning stops when an input
-character does not match such a format character. Scanning also stops when
-an input conversion cannot be made (see below).
-.SH CONVERSIONS
-Following the
-.B %
-character introducing a conversion there may be a number of
-.I flag
-characters, as follows:
+begins with either the character \(aq%\(aq or the character sequence
+"\fB%\fP\fIn\fP\fB$\fP"
+(see below for the distinction) followed by:
.TP
-.B *
-Suppresses assignment. The conversion that follows occurs as usual, but no
-pointer is used; the result of the conversion is simply discarded.
-.TP
-.B a
-(glibc) Indicates that the conversion will be
-.BR s ,
-the needed memory space for the string will be malloc'ed and
-the pointer to it will be assigned to the
-.I char
-pointer variable, which does not have to be initialized before.
-This flag does not exist in
-.IR "ANSI C"
-(C89) and has a different meaning in C99.
+\(bu
+An optional \(aq*\(aq assignment-suppression character:
+.BR scanf ()
+reads input as directed by the conversion specification,
+but discards the input.
+No corresponding
+.I pointer
+argument is required, and this specification is not
+included in the count of successful assignments returned by
+.BR scanf ().
.TP
-.B a
-(C99) Equivalent to
-.BR f .
+\(bu
+For decimal conversions, an optional quote character (\(aq).
+This specifies that the input number may include thousands'
+separators as defined by the
+.BR LC_NUMERIC
+category of the current locale.
+(See
+.BR setlocale (3).)
+The quote character may precede or follow the \(aq*\(aq
+assignment-suppression character.
+.TP
+\(bu
+An optional \(aqm\(aq character.
+This is used with string conversions
+.RI ( %s ,
+.IR %c ,
+.IR %[ ),
+and relieves the caller of the
+need to allocate a corresponding buffer to hold the input: instead,
+.BR scanf ()
+allocates a buffer of sufficient size,
+and assigns the address of this buffer to the corresponding
+.I pointer
+argument, which should be a pointer to a
+.I "char\ *"
+variable (this variable does not need to be initialized before the call).
+The caller should subsequently
+.BR free (3)
+this buffer when it is no longer required.
+.TP
+\(bu
+An optional decimal integer which specifies the
+.IR "maximum field width" .
+Reading of characters stops either when this maximum is reached or
+when a nonmatching character is found, whichever happens first.
+Most conversions discard initial white space characters (the exceptions
+are noted below),
+and these discarded characters don't count toward the maximum field width.
+String input conversions store a terminating null byte (\(aq\e0\(aq)
+to mark the end of the input;
+the maximum field width does not include this terminator.
+.TP
+\(bu
+An optional
+.IR "type modifier character" .
+For example, the
+.B l
+type modifier is used with integer conversions such as
+.B %d
+to specify that the corresponding
+.I pointer
+argument refers to a
+.I "long int"
+rather than a pointer to an
+.IR int .
+.TP
+\(bu
+A
+.I "conversion specifier"
+that specifies the type of input conversion to be performed.
+.PP
+The conversion specifications in
+.I format
+are of two forms, either beginning with \(aq%\(aq or beginning with
+"\fB%\fP\fIn\fP\fB$\fP".
+The two forms should not be mixed in the same
+.I format
+string, except that a string containing
+"\fB%\fP\fIn\fP\fB$\fP"
+specifications can include
+.B %%
+and
+.BR %* .
+If
+.I format
+contains \(aq%\(aq
+specifications, then these correspond in order with successive
+.I pointer
+arguments.
+In the
+"\fB%\fP\fIn\fP\fB$\fP"
+form (which is specified in POSIX.1-2001, but not C99),
+.I n
+is a decimal integer that specifies that the converted input should
+be placed in the location referred to by the
+.IR n -th
+.I pointer
+argument following
+.IR format .
+.SS Conversions
+The following
+.I "type modifier characters"
+can appear in a conversion specification:
.TP
.B h
Indicates that the conversion will be one of
-.B dioux
-or
-.B n
+\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP
and the next pointer is a pointer to a
-.I short int
+.I short int
+or
+.I unsigned short int
(rather than
.IR int ).
.TP
+.B hh
+As for
+.BR h ,
+but the next pointer is a pointer to a
+.I signed char
+or
+.IR "unsigned char" .
+.TP
+.B j
+As for
+.BR h ,
+but the next pointer is a pointer to an
+.I intmax_t
+or a
+.IR uintmax_t .
+This modifier was introduced in C99.
+.TP
.B l
Indicates either that the conversion will be one of
-.B dioux
-or
-.B n
+\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP
and the next pointer is a pointer to a
-.I long int
+.I long int
+or
+.I unsigned long int
(rather than
.IR int ),
or that the conversion will be one of
-.B efg
+\fBe\fP, \fBf\fP, or \fBg\fP
and the next pointer is a pointer to
.I double
(rather than
.IR float ).
-Specifying two
+Specifying two
.B l
-flags is equivalent to the
-.B L
-flag.
+characters is equivalent to
+.BR L .
+If used with
+.B %c
+or
+.BR %s ,
+the corresponding parameter is considered
+as a pointer to a wide character or wide-character string respectively.
+.\" This use of l was introduced in Amendment 1 to ISO C90.
.TP
.B L
Indicates that the conversion will be either
-.B efg
+\fBe\fP, \fBf\fP, or \fBg\fP
and the next pointer is a pointer to
-.IR "long double"
-or the conversion will be
-.B dioux
+.I "long double"
+or the conversion will be
+\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP
and the next pointer is a pointer to
.IR "long long" .
-(Note that long long is not an
-.I ANSI C
-type. Any program using this will not be portable to all
-architectures).
+.\" MTK, Jul 05: The following is no longer true for modern
+.\" ANSI C (i.e., C99):
+.\" (Note that long long is not an
+.\" ANSI C
+.\" type. Any program using this will not be portable to all
+.\" architectures).
.TP
.B q
-equivalent to L.
-This flag does not exist in
-.IR "ANSI C" .
-.PP
-In addition to these flags, there may be an optional maximum field width,
-expressed as a decimal integer, between the
-.B %
-and the conversion. If no width is given, a default of `infinity' is used
-(with one exception, below); otherwise at most this many characters are
-scanned in processing the conversion. Before conversion begins, most
-conversions skip white space; this white space is not counted against the
-field width.
+equivalent to
+.BR L .
+This specifier does not exist in ANSI C.
+.TP
+.B t
+As for
+.BR h ,
+but the next pointer is a pointer to a
+.IR ptrdiff_t .
+This modifier was introduced in C99.
+.TP
+.B z
+As for
+.BR h ,
+but the next pointer is a pointer to a
+.IR size_t .
+This modifier was introduced in C99.
.PP
-The following conversions are available:
+The following
+.I "conversion specifiers"
+are available:
.TP
.B %
-Matches a literal `%'. That is, `%\&%' in the format string matches a
-single input `%' character. No conversion is done, and assignment does not
-occur.
+Matches a literal \(aq%\(aq.
+That is,
+.B %\&%
+in the format string matches a
+single input \(aq%\(aq character.
+No conversion is done (but initial white space characters are discarded),
+and assignment does not occur.
.TP
.B d
Matches an optionally signed decimal integer;
the next pointer must be a pointer to
.IR int .
-.TP
-.B D
-Equivalent to
-.BR ld ;
-this exists only for backwards compatibility.
-(Note: thus only in libc4. In libc5 and glibc the %D is
-silently ignored, causing old programs to fail mysteriously.)
+.\" .TP
+.\" .B D
+.\" Equivalent to
+.\" .IR ld ;
+.\" this exists only for backward compatibility.
+.\" (Note: thus only in libc4
+.\" In libc5 and glibc the
+.\" .B %D
+.\" is silently ignored, causing old programs to fail mysteriously.)
.TP
.B i
Matches an optionally signed integer; the next pointer must be a pointer to
.IR int .
-The integer is read in base 16 if it begins with `0x' or `0X', in base 8 if
-it begins with `0', and in base 10 otherwise. Only characters that
-correspond to the base are used.
+The integer is read in base 16 if it begins with
+.I 0x
+or
+.IR 0X ,
+in base 8 if it begins with
+.IR 0 ,
+and in base 10 otherwise.
+Only characters that correspond to the base are used.
.TP
.B o
Matches an unsigned octal integer; the next pointer must be a pointer to
.IR "unsigned int" .
.TP
.B x
-Matches an unsigned hexadecimal integer; the next pointer must
+Matches an unsigned hexadecimal integer
+(that may optionally begin with a prefix of
+.I 0x
+or
+.IR 0X ,
+which is discarded); the next pointer must
be a pointer to
.IR "unsigned int" .
.TP
Equivalent to
.BR f .
.TP
+.B a
+(C99) Equivalent to
+.BR f .
+.TP
.B s
-Matches a sequence of non-white-space characters; the next pointer must be
-a pointer to
-.IR char ,
-and the array must be large enough to accept all the sequence and the
-terminating
-.B NUL
-character. The input string stops at white space or at the maximum field
+Matches a sequence of non-white-space characters;
+the next pointer must be a pointer to the initial element of a
+character array that is long enough to hold the input sequence and
+the terminating null byte (\(aq\e0\(aq), which is added automatically.
+The input string stops at white space or at the maximum field
width, whichever occurs first.
.TP
.B c
-Matches a sequence of
-.I width
-count characters (default 1); the next pointer must be a pointer to
+Matches a sequence of characters whose length is specified by the
+.I maximum field width
+(default 1); the next pointer must be a pointer to
.IR char ,
-and there must be enough room for all the characters (no terminating
-.B NUL
-is added). The usual skip of leading white space is suppressed. To skip
-white space first, use an explicit space in the format.
+and there must be enough room for all the characters
+(no terminating null byte is added).
+The usual skip of leading white space is suppressed.
+To skip white space first, use an explicit space in the format.
.TP
.B \&[
Matches a nonempty sequence of characters from the specified set of
accepted characters; the next pointer must be a pointer to
.IR char ,
and there must be enough room for all the characters in the string, plus a
-terminating
-.B NUL
-character. The usual skip of leading white space is suppressed. The
-string is to be made up of characters in (or not in) a particular set; the
-set is defined by the characters between the open bracket
+terminating null byte.
+The usual skip of leading white space is suppressed.
+The string is to be made up of characters in (or not in) a particular set;
+the set is defined by the characters between the open bracket
.B [
character and a close bracket
.B ]
-character. The set
+character.
+The set
.I excludes
those characters if the first character after the open bracket is a
circumflex
-.BR ^ .
+.RB ( ^ ).
To include a close bracket in the set, make it the first character after
the open bracket or the circumflex; any other position will end the set.
The hyphen character
.B \-
is also special; when placed between two other characters, it adds all
-intervening characters to the set. To include a hyphen, make it the last
-character before the final close bracket. For instance, `[^]0\-9-\]' means
-the set `everything except close bracket, zero through nine, and hyphen'.
+intervening characters to the set.
+To include a hyphen, make it the last
+character before the final close bracket.
+For instance,
+.B [^]0\-9\-]
+means
+the set "everything except close bracket, zero through nine, and hyphen".
The string ends with the appearance of a character not in the (or, with a
circumflex, in) set or when the field width runs out.
.TP
.B p
-Matches a pointer value (as printed by `%p' in
-.BR printf (3);
+Matches a pointer value (as printed by
+.B %p
+in
+.BR printf (3));
the next pointer must be a pointer to a pointer to
.IR void .
.TP
.IR int .
This is
.I not
-a conversion, although it can be suppressed with the
+a conversion and does
+.I not
+increase the count returned by the function.
+The assignment can be suppressed with the
.B *
-flag.
-The C standard says: `Execution of a %n directive does not increment
-the assignment count returned at the completion of execution'
-but the Corrigendum seems to contradict this. Probably it is wise
-not to make any assumptions on the effect of %n conversions on
-the return value.
-
+assignment-suppression character, but the effect on the
+return value is undefined.
+Therefore
+.B %*n
+conversions should not be used.
+.SH RETURN VALUE
+On success, these functions return the number of input items
+successfully matched and assigned;
+this can be fewer than provided for,
+or even zero, in the event of an early matching failure.
.PP
-.SH "RETURN VALUE"
-These functions return the number of input items assigned, which can be
-fewer than provided for, or even zero, in the event of a matching failure.
-A return of zero indicates that, while there was input available,
-no conversions were assigned;
-typically this is due to an invalid input character, such as an
-alphabetic character for a `%d' conversion.
-
The value
.B EOF
-is returned if the end of input is reached before the first
-successful conversion or matching failure.
+is returned if the end of input is reached before either the first
+successful conversion or a matching failure occurs.
.B EOF
-is also returned if a read error occurs,
+is also returned if a read error occurs,
in which case the error indicator for the stream (see
.BR ferror (3))
is set, and
.I errno
-is set indicate the error.
-
-If an error or end-of-file occurs after conversion has
-begun, the number of conversions which were successfully completed is
-returned.
-.SH "SEE ALSO"
-.BR getc (3),
-.BR printf (3),
-.BR strtod (3),
-.BR strtol (3),
-.BR strtoul (3)
-.SH "CONFORMING TO"
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The file descriptor underlying
+.I stream
+is marked nonblocking, and the read operation would block.
+.TP
+.B EBADF
+The file descriptor underlying
+.I stream
+is invalid, or not open for reading.
+.TP
+.B EILSEQ
+Input byte sequence does not form a valid character.
+.TP
+.B EINTR
+The read operation was interrupted by a signal; see
+.BR signal (7).
+.TP
+.B EINVAL
+Not enough arguments; or
+.I format
+is NULL.
+.TP
+.B ENOMEM
+Out of memory.
+.TP
+.B ERANGE
+The result of an integer conversion would exceed the size
+that can be stored in the corresponding integer type.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw20 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR scanf (),
+.BR fscanf (),
+.br
+.BR sscanf (),
+.BR vscanf (),
+.br
+.BR vsscanf (),
+.BR vfscanf ()
+T} Thread safety MT-Safe locale
+.TE
+.sp 1
+.SH CONFORMING TO
The functions
-.BR fscanf ,
-.BR scanf ,
+.BR fscanf (),
+.BR scanf (),
and
-.BR sscanf
-conform to ANSI X3.159-1989 (``ANSI C'').
+.BR sscanf ()
+conform to C89 and C99 and POSIX.1-2001.
+These standards do not specify the
+.B ERANGE
+error.
.PP
-The
+The
.B q
-flag is the
-.I BSD 4.4
-notation for
+specifier is the 4.4BSD notation for
.IR "long long" ,
while
.B ll
.B L
in integer conversions is the GNU notation.
.PP
-The Linux version of these functions is based on the
-.I GNU
+The Linux version of these functions is based on the
+.I GNU
.I libio
-library. Take a look at the
+library.
+Take a look at the
.I info
-documentation of
+documentation of
.I GNU
.I libc (glibc-1.08)
-for a more concise description.
+for a more concise description.
+.SH NOTES
+.SS The 'a' assignment-allocation modifier
+Originally, the GNU C library supported dynamic allocation for string inputs
+(as a nonstandard extension) via the
+.B a
+character.
+(This feature is present at least as far back as glibc 2.0.)
+Thus, one could write the following to have
+.BR scanf ()
+allocate a buffer for an input string,
+with a pointer to that buffer being returned in
+.IR *buf :
+.PP
+ char *buf;
+ scanf("%as", &buf);
+.PP
+The use of the letter
+.B a
+for this purpose was problematic, since
+.B a
+is also specified by the ISO C standard as a synonym for
+.B f
+(floating-point input).
+POSIX.1-2008 instead specifies the
+.B m
+modifier for assignment allocation (as documented in DESCRIPTION, above).
+.PP
+Note that the
+.B a
+modifier is not available if the program is compiled with
+.I "gcc \-std=c99"
+or
+.IR "gcc \-D_ISOC99_SOURCE"
+(unless
+.B _GNU_SOURCE
+is also specified), in which case the
+.B a
+is interpreted as a specifier for floating-point numbers (see above).
+.PP
+Support for the
+.B m
+modifier was added to glibc starting with version 2.7,
+and new programs should use that modifier instead of
+.BR a .
+.PP
+As well as being standardized by POSIX, the
+.B m
+modifier has the following further advantages over
+the use of
+.BR a:
+.IP * 2
+It may also be applied to
+.B %c
+conversion specifiers (e.g.,
+.BR %3mc ).
+.IP *
+It avoids ambiguity with respect to the
+.B %a
+floating-point conversion specifier (and is unaffected by
+.IR "gcc \-std=c99"
+etc.).
.SH BUGS
-All functions are fully ANSI X3.159-1989 conformant, but provide the
-additional flags
+All functions are fully C89 conformant, but provide the
+additional specifiers
.B q
and
.B a
-as well as an additional behaviour of the
+as well as an additional behavior of the
.B L
-and
-.B l
-flags. The latter may be considered to be a bug, as it changes the
-behaviour of flags defined in ANSI X3.159-1989.
+and
+.B l
+specifiers.
+The latter may be considered to be a bug, as it changes the
+behavior of specifiers defined in C89.
.PP
-Some combinations of flags defined by
-.I ANSI C
-are not making sense in
-.IR "ANSI C"
-(e.g.
+Some combinations of the type modifiers and conversion
+specifiers defined by ANSI C do not make sense
+(e.g.,
.BR "%Ld" ).
-While they may have a well-defined behaviour on Linux, this need not
-to be so on other architectures. Therefore it usually is better to use
-flags that are not defined by
-.I ANSI C
-at all, i.e. use
+While they may have a well-defined behavior on Linux, this need not
+to be so on other architectures.
+Therefore it usually is better to use
+modifiers that are not defined by ANSI C at all, that is, use
.B q
-instead of
+instead of
.B L
-in combination with
-.B diouxX
-conversions or
+in combination with
+\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP
+conversions or
.BR ll .
.PP
The usage of
.B q
-is not the same as on
-.IR "BSD 4.4" ,
-as it may be used in float conversions equivalently to
+is not the same as on 4.4BSD,
+as it may be used in float conversions equivalently to
.BR L .
+.SH EXAMPLES
+To use the dynamic allocation conversion specifier, specify
+.B m
+as a length modifier (thus
+.B %ms
+or
+\fB%m[\fP\fIrange\fP\fB]\fP).
+The caller must
+.BR free (3)
+the returned string, as in the following example:
+.PP
+.in +4n
+.EX
+char *p;
+int n;
+
+errno = 0;
+n = scanf("%m[a\-z]", &p);
+if (n == 1) {
+ printf("read: %s\en", p);
+ free(p);
+} else if (errno != 0) {
+ perror("scanf");
+} else {
+ fprintf(stderr, "No matching characters\en");
+}
+.EE
+.in
+.PP
+As shown in the above example, it is necessary to call
+.BR free (3)
+only if the
+.BR scanf ()
+call successfully read a string.
+.SH SEE ALSO
+.BR getc (3),
+.BR printf (3),
+.BR setlocale (3),
+.BR strtod (3),
+.BR strtol (3),
+.BR strtoul (3)