Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SCANF(3)		 BSD Library Functions Manual		      SCANF(3)

NAME
     scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf --	input format conver-
     sion

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <stdio.h>

     int
     scanf(const char *format, ...);

     int
     fscanf(FILE *stream, const	char *format, ...);

     int
     sscanf(const char *str, const char	*format, ...);

     #include <stdarg.h>

     int
     vscanf(const char *format,	va_list	ap);

     int
     vsscanf(const char	*str, const char *format, va_list ap);

     int
     vfscanf(FILE *stream, const char *format, va_list ap);

DESCRIPTION
     The scanf() family	of functions scans input according to a	format as de-
     scribed below.  This format may contain conversion	specifiers; the	re-
     sults from	such conversions, if any, are stored through the pointer argu-
     ments.  The scanf() function reads	input from the standard	input stream
     stdin, fscanf() reads input from the stream pointer stream, and sscanf()
     reads its input from the character	string pointed to by str.  The
     vfscanf() function	is analogous to	vfprintf(3) and	reads input from the
     stream pointer stream using a variable argument list of pointers (see
     stdarg(3)).  The vscanf() function	scans a	variable argument list from
     the standard input	and the	vsscanf() function scans it from a string;
     these are analogous to the	vprintf() and vsprintf() functions respec-
     tively.  Each successive pointer argument must correspond properly	with
     each successive conversion	specifier (but see `suppression' below).  All
     conversions are introduced	by the % (percent sign)	character.  The	format
     string may	also contain other characters.	White space (such as blanks,
     tabs, or newlines)	in the 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 char-
     acter.  Scanning also stops when an input conversion cannot be made (see
     below).

CONVERSIONS
     Following the % character introducing a conversion	there may be a number
     of	flag characters, as follows:

     *	     Suppresses	assignment.  The conversion that follows occurs	as
	     usual, but	no pointer is used; the	result of the conversion is
	     simply discarded.

     h	     Indicates that the	conversion will	be one of dioux	or n and the
	     next pointer is a pointer to a short int (rather than int).

     l	     Indicates either that the conversion will be one of dioux or n
	     and the next pointer is a pointer to a long int (rather than
	     int), or that the conversion will be one of efg and the next
	     pointer is	a pointer to double (rather than float).

     L	     Indicates that the	conversion will	be efg and the next pointer is
	     a pointer to long double.	(This type is not implemented; the L
	     flag is currently ignored.)

     q	     Indicates either that the conversion will be one of dioux or n
	     and the next pointer is a pointer to a long long int (rather than
	     int),

     In	addition to these flags, there may be an optional maximum field	width,
     expressed as a decimal integer, between the % and the conversion.	If no
     width is given, a default of `infinity' is	used (with one exception, be-
     low); 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.

     The following conversions are available:

     %	   Matches a literal `%'.  That	is, `%%' in the	format string matches
	   a single input `%' character.  No conversion	is done, and assign-
	   ment	does not occur.

     d	   Matches an optionally signed	decimal	integer; the next pointer must
	   be a	pointer	to int.

     D	   Equivalent to ld; this exists only for backwards compatibility.

     i	   Matches an optionally signed	integer; the next pointer must be a
	   pointer to 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 oth-
	   erwise.  Only characters that correspond to the base	are used.

     o	   Matches an octal integer; the next pointer must be a	pointer	to
	   unsigned int.

     O	   Equivalent to lo; this exists for backwards compatibility.

     u	   Matches an optionally signed	decimal	integer; the next pointer must
	   be a	pointer	to unsigned int.

     x	   Matches an optionally signed	hexadecimal integer; the next pointer
	   must	be a pointer to	unsigned int.

     X	   Equivalent to lx; this violates the ISO/IEC 9899:1990 ("ISO C90"),
	   but is backwards compatible with previous UNIX systems.

     f	   Matches an optionally signed	floating-point number; the next
	   pointer must	be a pointer to	float.

     e	   Equivalent to f.

     g	   Equivalent to f.

     E	   Equivalent to lf; this violates the ISO/IEC 9899:1990 ("ISO C90"),
	   but is backwards compatible with previous UNIX systems.

     F	   Equivalent to lf; this exists only for backwards compatibility.

     s	   Matches a sequence of non-white-space characters; the next pointer
	   must	be a pointer to	char, and the array must be large enough to
	   accept all the sequence and the terminating NUL character.  The in-
	   put string stops at white space or at the maximum field width,
	   whichever occurs first.

     c	   Matches a sequence of width count characters	(default 1); the next
	   pointer must	be a pointer to	char, and there	must be	enough room
	   for all the characters (no terminating NUL is added).  The usual
	   skip	of leading white space is suppressed.  To skip white space
	   first, use an explicit space	in the format.

     [	   Matches a nonempty sequence of characters from the specified	set of
	   accepted characters;	the next pointer must be a pointer to char,
	   and there must be enough room for all the characters	in the string,
	   plus	a terminating 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 [ character	and a close bracket ] charac-
	   ter.	 The set excludes those	characters if the first	character af-
	   ter the open	bracket	is a circumflex	^.  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 - is also special;	when placed between two	other charac-
	   ters, 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'.  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.

     p	   Matches a pointer value (as printed by `%p' in printf(3)); the next
	   pointer must	be a pointer to	void.

     n	   Nothing is expected;	instead, the number of characters consumed
	   thus	far from the input is stored through the next pointer, which
	   must	be a pointer to	int.  This is not a conversion,	although it
	   can be suppressed with the *	flag.

     For backwards compatibility, other	conversion characters (except `\0')
     are taken as if they were `%d' or,	if uppercase, `%ld', and a `conver-
     sion' of `%\0' causes an immediate	return of EOF.	The F and X conver-
     sions will	be changed in the future to conform to the ANSI	C standard,
     after which they will act like f and x respectively.

RETURN VALUES
     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 fail-
     ure.  Zero	indicates that,	while there was	input available, no conver-
     sions were	assigned; typically this is due	to an invalid input character,
     such as an	alphabetic character for a `%d'	conversion.  The value EOF is
     returned if an input failure occurs before	any conversion such as an end-
     of-file occurs.  If an error or end-of-file occurs	after conversion has
     begun, the	number of conversions which were successfully completed	is re-
     turned.

SEE ALSO
     getc(3), printf(3), strtod(3), strtol(3), strtoul(3)

STANDARDS
     The functions fscanf(), scanf(), and sscanf() conform to ISO/IEC
     9899:1990 ("ISO C90").

HISTORY
     The functions vscanf(), vsscanf() and vfscanf() are new to	this release.

BUGS
     The current situation with	%F and %X conversions is unfortunate.

     All of the	backwards compatibility	formats	will be	removed	in the future.

     Numerical strings are truncated to	512 characters;	for example, %f	and %d
     are implicitly %512f and %512d.

BSD			       December	11, 1993			   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | CONVERSIONS | RETURN VALUES | SEE ALSO | STANDARDS | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=scanf&sektion=3&manpath=FreeBSD+4.5-RELEASE>

home | help