.TH scanf() "" "" "STDIO Function (libc)"
.PC "Accept and format input"
.B "#include <stdio.h>"
\fBint scanf(\fIformat, arg1, .\^.\^. argN\fB)\fR
\fBchar *\fIformat\^\fB; [data type] *\fIarg1, .\^.\^. \fB*\fIargN\^\fB;\fR
.PP
.B scanf()
reads the standard input, and uses the string
.I format
to specify a format for each
.I arg1
through
.IR argN ,
each of which must be a pointer.
.PP
.B scanf()
reads one character at a time from
.IR format ;
white space characters are ignored.
The percent sign character \*(Ql%\*(Qr
marks the beginning of a conversion specification.
\*(Ql%\*(Qr may be followed by characters that indicate the width of the
input field and the type of conversion to be done.
.PP
.B scanf()
reads the standard input until the return key is pressed.
Inappropriate characters are thrown away; e.g.,
it will not try to write an alphabetic character into
an \fBint\fR.
.PP
.B scanf()
returns the number of arguments filled.
It returns EOF if no arguments can be filled or if an error occurs.
.SH "Modifiers"
The following modifiers can be used within the conversion string:
.IP \fB1.\fR 0.3i
An asterisk \*(Ql*\*(Qr, which tells
.B scanf
to skip the next conversion; that is, read the next
token but do not write it into the corresponding argument.
.IP \fB2.\fR
A decimal integer, which tells
.B scanf
the maximum width of the next field being read.
How the field width is used varies among conversion specifier.
See the table of specifiers below for more information.
.IP \fB3.\fR
One of the three modifiers
.BR h ,
.BR l ,
or
.BR L ,
whose use is described below.
.SH Modifiers
The following three modifiers may be used before a conversion
specifier:
.IP \fBh\fR
When used before the conversion specifiers
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
or
.BR X ,
it specifies that the corresponding
argument points to a \fBshort int\fR or an \fBunsigned short int\fR.
When used before
.BR n ,
it indicates that the corresponding
argument points to a \fBshort int\fR.
In implementations where \fBshort int\fR and \fBint\fR are synonymous,
it is not needed.
However, it is useful in writing portable code.
.IP \fBl\fR
When used before the conversion specifiers
.BR e ,
.BR E ,
.BR f ,
.BR F ,
or
.BR G ,
it indicates that the corresponding argument points to a
\fBdouble\fR rather than a
.BR float .
.IP \fBL\fR
When used before the conversion specifiers
.BR e ,
.BR E ,
.BR f ,
.BR F ,
or
.BR G ,
it indicates that the corresponding argument points to a
\fBlong double\fR rather than a
.BR float .
.SH "Conversion Specifiers"
.B scanf()
recognizes the following conversion specifiers:
.IP \fBc\fR 0.3i
Assign the next input character to the next
.IR arg ,
which should be of type \fBchar *\fR.
The field width specifies the number of characters
(default, one).
.B scanf()
does not write a null character at the end of the array it creates.
This specifier forces
.B scanf()
to read and store white-space characters
and numerals, as well as letters.
.IP \fBd\fR
Convert the token to a decimal integer.
The format should be
equivalent to that expected by the function \fBstrtol()\fR with
a base argument of ten.
The corresponding argument should point to an \fBint\fR.
.IP \fBD\fR
Assign the decimal integer from the next input field to the next
.IR arg ,
which should be of type \fBlong\fR *\fR.
.IP \fBe\fR
Convert the token to a floating-point number.
The format of the
token should be that expected by the function \fBstrtod()\fR for
a floating-point number that uses exponential notation.
The corresponding argument should point to a
.B float
if no modifiers are present, to a
.B double
if the
.B l
modifier is present, or to a
.B "long double"
if the
.B L
modifier is present.
.IP \fBE\fR
Same as
.BR e .
Prior to release 4.2 of \*(CO, this conversion specifier converted the
token to a
.BR double .
This change has been made to conform to the ANSI Standard, and may require
that some code be rewritten.
.IP \fBf\fR
Convert the token to a floating-point number.
The format of the
token should be that expected by the function \fBstrtod()\fR for
a floating-point number that uses decimal notation.
The corresponding argument should point to a \fBdouble\fR.
.IP \fBg\fR
Convert the token to a floating-point number.
The format of the
token should of that expected by the function \fBstrtod()\fR for
a floating-point number that uses either exponential notation or
decimal notation.
The corresponding argument should point to a
.B float
if no modifiers are present, to a
.B double
if the
.B l
modifier is present, or to a
.B "long double"
if the
.B L
modifier is present.
.IP \fBG\fR
Same as
.BR g .
.IP \fBi\fR
Convert the token to a decimal integer.
The format should be
equivalent to that expected by the function \fBstrtol()\fR with
a base argument of zero.
The corresponding argument should point to an \fBint\fR.
.IP \fBn\fR
Do not read any text.
Write into the corresponding argument the number of characters that
.B scanf()
has read up to this point.
The corresponding argument should point to an \fBint\fR.
.IP \fBo\fR
Assign the octal integer from the next input field to the next
.IR arg ,
which should be of type \fBint *\fR.
.IP \fBO\fR
Assign the octal integer from the next input field to the next
.IR arg ,
which should be of type \fBlong *\fR.
.IP \fBp\fR
The ANSI standard states that the behavior of the \fB%p\fR
conversion specificer is implementation-specific.
Under \*(CO, \fB%p\fR converts a strings of digits in hexadecimal
notation into an address.
For example, in the code
.DM
	char buf[] = "0x7FFFFDBC";
	char *foo;
	...
	sscanf(buf, "%p", &foo);
.DE
.IP
the \fB%p\fR specifier
reads the contents of \fBbuf\fR and turns them into an address, which it
then uses to initialize the pointer \fBfoo\fR.
You can use the \fB%p\fR specifier to turn back into an address the output
of
.BR printf() 's
\fB%p\fR specifier.
Please note that abuse of this specifier can create all manner of fascinating
bugs within your programs:
.IR "Caveat utilitor" .
.IP \fBr\fR
The next argument points to an array of new arguments that may be used
recursively.
The first argument of the list is a \fBchar *\fR that contains a new format
string.
When the list is exhausted, the routine continues from where it left off in
the original format string.
.IP \fBs\fR
Assign the string from the next input field to the next
.IR arg ,
which should be of type \fBchar *\fR.
The array to which the
.B "char *"
points should be long enough to accept the string and a
terminating null character.
.IP \fBu\fR
Convert the token to an unsigned integer.
The format should be
equivalent to that expected by the function \fBstrtoul()\fR with
a base argument of ten.
See \fBstrtoul\fR for more information.
The corresponding argument should point to an \fBunsigned int\fR.
.IP \fBx\fR
Convert the token from hexadecimal notation to a signed integer.
The format should be equivalent to that expected by the
function \fBstrtol\fR with a base argument of 16.
See the Lexicon entry for \fBstrtol()\fR for more information.
The corresponding argument should point to an \fBunsigned int\fR.
.IP \fBX\fR
Same as
.BR x .
Prior to release 4.2 of \*(CO,
.B X
meant the same as the current
.BR lx ;
that is, the corresponding argument points to a
.B long
instead of an
.BR int .
This has been changed to conform to the ANSI Standard, and may require
that some code be rewritten.
.PP
It is important to remember that \fBscanf()\fR reads up, but not through,
the newline character:
the newline remains in the standard input device's buffer
until you dispose of it somehow.
Programmers have been known to
forget to empty the buffer before calling
\fBscanf()\fR a second time, which leads to unexpected results.
.SH Example
The following example uses \fBscanf()\fR in a brief dialogue with the user.
.DM
#include <stdio.h>
.sp \n(pDu
main()
{
	int left, right;
.DE
.DM
	printf("No. of fingers on your left hand:  ");
	/* force message to appear on screen */
	fflush(stdout);
	scanf("%d", &left);
.DE
.DM
	/* eat newline char */
	while(getchar() != '\en')
		;
.DE
.DM
	printf("No. of fingers on your right hand:  ");
	fflush(stdout);
	scanf("%d", &right);
.DE
.DM
	/* again, eat newline */
	while(getchar() != '\en')
		;
.DE
.DM	
	printf("You've %d left fingers, %d right, & %d total\en",
		left, right, left+right);
}
.DE
.SH "See Also"
.Xr "fscanf()," fscanf
.Xr "libc," libc
.Xr "sscanf()" sscanf
.br
\*(AS, \(sc7.9.6.4
.br
\*(PX Standard, \(sc8.1
.SH Notes
Because C does not perform type checking, it is essential that
an argument match its specification.
For that reason,
.B scanf()
is best used to process only data that
you are certain are in the correct data format.
Rather than use
.B scanf()
to obtain a string from the keyboard:
we recommend that you use
.B gets()
to obtain the string, and use
.B strtok()
or
.B sscanf()
to parse it.
