sc

Algorithms for Image Processing and Computer Vision Source Code

@c ----------------------------------------------------------------------
@node scanf, stdio
@heading @code{scanf}
@subheading Syntax

@example
#include <stdio.h>

int scanf(const char *format, @dots{});
@end example

@subheading Description

This function scans formatted text from @code{stdin} and stores it in
the variables pointed to by the arguments.  @xref{scanf}

The format string contains regular characters which much match the input
exactly as well as a conversion specifiers, which begin with a percent
symbol.  Any whitespace in the format string matches zero or more of any
whitespace characters in the input.  Thus, a single space may match a
newline and two tabs in the input.  All conversions except @code{c} and
@code{[} also skip leading whitespace automatically.  Each conversion
specifier contains the following fields:

@itemize @bullet

@item

An asterisk (@code{*}) which indicates that the input should be
converted according to the conversion spec, but not stored anywhere. 

@item

A width specifier, which specifies the maximum number of input
characters to use in the conversion. 

@item

An optional conversion qualifier, which may be @code{h} to specify
@code{short}, @code{l} to specify long ints, or @code{L} to specify
long doubles.

@item

The conversion type specifier:

@table @code

@item c

Copy the next character (or @var{width} characters) to the given buffer.

@item d

Convert the input to a signed integer.

@item e
@item E
@itemx f
@itemx g
@itemx G

Convert the input to a floating point number.

@item i

Convert the input, determining base automatically by the presence of
@code{0x} or @code{0} prefixes.  @xref{strtol}

@item n

Store the number of characters scanned so far into the integer pointed
to. 

@item o

Convert the input to a signed integer, using base 8.

@item p

Convert the input to a pointer.  This is like using the @code{x} format. 

@item s

Copy the input to the given string, skipping leading whitespace and
copying non-whitespace characters up to the next whitespace.  The string
stored is then @code{NULL}-terminated. 

@item u

Convert the input to an unsigned integer.

@item x
@itemx X

Convert the input to an unsigned integer, using base 16.

@item [@dots{}]

Like the @code{c} format, except only certain characters are copied. 
The characters between the brackets determine which characters are
allowed, and thus when the copying stops.  These characters may be
regular characters (example: @code{[abcd]}) or a range of characters
(example: @code{[a-d]}).  If the first character is a caret (@code{^}),
then the set specifies the set of characters that do not get copied
(i.e.  the set is negated).  To specify that the set contains a
close-bracket (@code{]}), list that as the first regular character. 

@item %

This must match a percent character in the input. 

@end table

@end itemize

Most conversions make use of @code{strtol} or @code{strtoul} to perform
the actual conversions. 

@subheading Return Value

The number of items successfully scanned.

@subheading Example

@example
int x, y;
char buf[100];
scanf("%d %d %s", &x, &y, buf);

/* read to end-of-line */
scanf("%d %[^\n]\n", &x, buf);
/* read letters only */
scanf("[a-zA-Z]", buf);
@end example