252 lines
6.0 KiB
Groff
252 lines
6.0 KiB
Groff
.\" @(#)scanf.3s 6.1 (Berkeley) 5/15/85
|
|
.\"
|
|
.TH SCANF 3 "May 15, 1985"
|
|
.AT 3
|
|
.SH NAME
|
|
scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf \- formatted input conversion
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <stdio.h>
|
|
#include <stdarg.h>
|
|
|
|
int scanf(const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
|
|
int fscanf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
|
|
int sscanf(const char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIpointer\fP\fR] ...\fP)
|
|
int vscanf(const char *\fIformat\fP, va_list \fIargs\fP)
|
|
int vfscanf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP)
|
|
int vsscanf(const char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP)
|
|
.SH DESCRIPTION
|
|
.B Scanf
|
|
reads from the standard input stream
|
|
.BR stdin .
|
|
.B Fscanf
|
|
reads from the named input
|
|
.IR stream .
|
|
.B Sscanf
|
|
reads from the character string
|
|
.IR s .
|
|
Each function reads characters, interprets
|
|
them according to a format, and stores the results in its arguments.
|
|
Each expects as arguments
|
|
a control string
|
|
.IR format ,
|
|
described below,
|
|
and a set of
|
|
.I pointer
|
|
arguments
|
|
indicating where the converted input should be stored.
|
|
.PP
|
|
The
|
|
.B v*scanf
|
|
functions can be used to make functions like the first three by using the
|
|
.BR stdarg (3)
|
|
method to process the argument pointers.
|
|
.PP
|
|
The
|
|
control string
|
|
usually contains
|
|
conversion specifications, which are used to direct interpretation
|
|
of input sequences.
|
|
The control string may contain:
|
|
.TP 4
|
|
1.
|
|
Blanks, tabs or newlines,
|
|
which match optional white space in the input.
|
|
.TP 4
|
|
2.
|
|
An ordinary character (not %) which must match
|
|
the next character of the input stream.
|
|
.TP 4
|
|
3.
|
|
Conversion specifications, consisting of the
|
|
character
|
|
.BR % ,
|
|
an optional assignment suppressing character
|
|
.BR * ,
|
|
an optional numerical maximum field width, and a conversion
|
|
character.
|
|
.PP
|
|
A conversion specification directs the conversion of the
|
|
next input field; the result
|
|
is placed in the variable pointed to by the corresponding argument,
|
|
unless assignment suppression was
|
|
indicated by
|
|
.BR * .
|
|
An input field is defined as a string of non-space characters;
|
|
it extends to the next inappropriate character or until the field
|
|
width, if specified, is exhausted.
|
|
.PP
|
|
The conversion character indicates the interpretation of the
|
|
input field; the corresponding pointer argument must
|
|
usually be of a restricted type.
|
|
The following conversion characters are legal:
|
|
.TP 4
|
|
.B %
|
|
a single `%' is expected
|
|
in the input at this point;
|
|
no assignment is done.
|
|
.TP 4
|
|
.B d
|
|
a decimal integer is expected;
|
|
the corresponding argument should be an integer pointer.
|
|
.TP 4
|
|
.B o
|
|
an octal integer is expected;
|
|
the corresponding argument should be a integer pointer.
|
|
.TP 4
|
|
.B x
|
|
a hexadecimal integer is expected;
|
|
the corresponding argument should be an integer pointer.
|
|
.ti -0.2i
|
|
.TP 4
|
|
.B s
|
|
a character string is expected;
|
|
the corresponding argument should be a character pointer
|
|
pointing to an array of characters large enough to accept the
|
|
string and a terminating `\e0', which will be added.
|
|
The input field is terminated by a space character
|
|
or a newline.
|
|
.TP 4
|
|
.B c
|
|
a character is expected; the
|
|
corresponding argument should be a character pointer.
|
|
The normal skip over space characters is suppressed
|
|
in this case;
|
|
to read the next non-space character, try
|
|
`%1s'.
|
|
If a field width is given, the corresponding argument
|
|
should refer to a character array, and the
|
|
indicated number of characters is read.
|
|
.TP 4
|
|
.B efg
|
|
a floating point number is expected;
|
|
the next field is converted accordingly and stored through the
|
|
corresponding argument, which should be a pointer to a
|
|
.BR float .
|
|
The input format for
|
|
floating point numbers is
|
|
an optionally signed
|
|
string of digits
|
|
possibly containing a decimal point, followed by an optional
|
|
exponent field consisting of an E or e followed by an optionally signed integer.
|
|
.TP 4
|
|
.B [
|
|
indicates a string not to be delimited by space characters.
|
|
The left bracket is followed by a set of characters and a right
|
|
bracket; the characters between the brackets define a set
|
|
of characters making up the string.
|
|
If the first character
|
|
is not circumflex (\|^\|), the input field
|
|
is all characters until the first character not in the set between
|
|
the brackets; if the first character
|
|
after the left bracket is ^, the input field is all characters
|
|
until the first character which is in the remaining set of characters
|
|
between the brackets.
|
|
The corresponding argument must point to a character array.
|
|
.PP
|
|
The conversion characters
|
|
.BR d ,
|
|
.B o
|
|
and
|
|
.B x
|
|
may be capitalized or preceded by
|
|
.B l
|
|
to indicate that a pointer to
|
|
.B long
|
|
rather than to
|
|
.B int
|
|
is in the argument list.
|
|
Similarly, the conversion characters
|
|
.BR e ,
|
|
.B f
|
|
or
|
|
.B g
|
|
may be capitalized or
|
|
preceded by
|
|
.B l
|
|
to indicate a pointer to
|
|
.B double
|
|
rather than to
|
|
.BR float .
|
|
The conversion characters
|
|
.BR d ,
|
|
.B o
|
|
and
|
|
.B x
|
|
may be preceded by
|
|
.B h
|
|
to indicate a pointer to
|
|
.B short
|
|
rather than to
|
|
.BR int .
|
|
.PP
|
|
The
|
|
.B scanf
|
|
functions return the number of successfully matched and assigned input
|
|
items.
|
|
This can be used to decide how many input items were found.
|
|
The constant
|
|
.SM
|
|
.B EOF
|
|
is returned upon end of input; note that this is different
|
|
from 0, which means that no conversion was done;
|
|
if conversion was intended, it was frustrated by an
|
|
inappropriate character in the input.
|
|
.PP
|
|
For example, the call
|
|
.IP "\&" 10
|
|
int i; float x; char name[50];
|
|
.br
|
|
scanf("%d%f%s", &i, &x, name);
|
|
.PP
|
|
with the input line
|
|
.IP
|
|
25 54.32E\(mi1 thompson
|
|
.PP
|
|
will assign to
|
|
.B i
|
|
the value
|
|
25,
|
|
.B x
|
|
the value 5.432, and
|
|
.B name
|
|
will contain `\fBthompson\e0\fP' .
|
|
Or,
|
|
.IP
|
|
int i; float x; char name[50];
|
|
.br
|
|
scanf("%2d%f%*d%[1234567890]", &i, &x, name);
|
|
.PP
|
|
with input
|
|
.IP
|
|
56789 0123 56a72
|
|
.PP
|
|
will assign 56 to
|
|
.BR i ,
|
|
789.0 to
|
|
.BR x ,
|
|
skip `0123',
|
|
and place the string `56\e0' in
|
|
.BR name .
|
|
The next call to
|
|
.B getchar
|
|
will return `a'.
|
|
.SH "SEE ALSO"
|
|
.BR atof (3),
|
|
.BR getc (3),
|
|
.BR printf (3),
|
|
.BR stdarg (3).
|
|
.SH DIAGNOSTICS
|
|
The
|
|
.B scanf
|
|
functions return
|
|
.SM
|
|
.B EOF
|
|
on end of input,
|
|
and a short count for missing or illegal data items.
|
|
.SH BUGS
|
|
The success of literal matches and suppressed
|
|
assignments is not directly
|
|
determinable.
|