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

FreeBSD Manual Pages


home | help
SCANF(3V)							     SCANF(3V)

       scanf, fscanf, sscanf - formatted input conversion

       #include	<stdio.h>

       int scanf(format	 [ , pointer...	] )
       char *format;

       int fscanf(stream, format  [ , pointer... ] )
       FILE *stream;
       char *format;

       int sscanf(s, format  [ , pointer... ] )
       char *s,	*format;

       The following are provided for XPG2 compatibility:

       #define	 nl_scanf  scanf
       #define	 nl_fscanf fscanf
       #define	 nl_sscanf sscanf

       scanf()	reads  from  the  standard input stream	stdin.	fscanf() reads
       from the	named input stream.  sscanf() reads from the character	string
       s.  Each	function reads characters, interprets them according to	a for-
       mat, and	stores the results in its arguments.  Each expects,  as	 argu-
       ments,  a  control string format, described below, and a	set of pointer
       arguments indicating where the converted	input should be	 stored.   The
       results	are  undefined	in there are insufficient args for the format.
       If the format is	exhausted while	args remain, the excess	args are  sim-
       ply ignored.

       The  control  string  usually contains conversion specifications, which
       are used	to direct interpretation  of  input  sequences.	  The  control
       string may contain:

	      o	 White-space characters	(SPACE,	TAB, or	NEWLINE) which,	except
		 in two	cases described	below, cause input to be  read	up  to
		 the next non-white-space character.
	      o	 An  ordinary  character  (not `%'), which must	match the next
		 character of the input	stream.
	      o	 Conversion specifications, consisting of the character	`%' or
		 the  character	 sequence %digit$, an optional assignment sup-
		 pressing character `*', an optional numerical	maximum	 field
		 width,	 an  optional  l (ell) or h indicating the size	of the
		 receiving variable, and a conversion code.

       Conversion specifications are introduced	by  the	 character  %  or  the
       character  sequence  %digit$.   A  conversion specification directs the
       conversion of the next input field; the result is placed	in  the	 vari-
       able  pointed  to by the	corresponding argument,	unless assignment sup-
       pression	was indicated by `*'.  The suppression of assignment  provides
       a  way  of  describing an input field which is to be skipped.  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.  For all descriptors except ``[''  and  ``c'',  white	 space
       leading an input	field is ignored.

       The  conversion	character  indicates  the  interpretation of the input
       field; the corresponding	pointer	argument must  usually	be  of	a  re-
       stricted	 type.	 For a suppressed field, no pointer argument is	given.
       The following conversion	characters are legal:

	      %	     A single %	is expected in the input at this point;	no as-
		     signment is done.
	      d	     A decimal integer is expected; the	corresponding argument
		     should be an integer pointer.
	      u	     An	unsigned decimal integer is expected; the  correspond-
		     ing argument should be an unsigned	integer	pointer.
	      o	     An	 octal integer is expected; the	corresponding argument
		     should be an integer pointer.
	      x	     A hexadecimal integer is expected;	the corresponding  ar-
		     gument should be an integer pointer.
	      i	     An	integer	is expected; the corresponding argument	should
		     be	an integer pointer.  It	will store the	value  of  the
		     next input	item interpreted according to C	conventions: a
		     leading ``0'' implies octal;  a  leading  ``0x''  implies
		     hexadecimal; otherwise, decimal.
	      n	     Stores in an integer argument the total number of charac-
		     ters (including white space) that have  been  scanned  so
		     far since the function call. No input is consumed.
	      e,f,g  A	floating  point	 number	is expected; the next field is
		     converted accordingly and stored through the  correspond-
		     ing  argument, which should be a pointer to a float.  The
		     input format for floating point numbers is	 as  described
		     for string_to_decimal(3), with fortran_conventions	zero.
	      s	     A	character  string is expected; the corresponding argu-
		     ment should be a character	pointer	pointing to  an	 array
		     of	 characters  large  enough  to accept the string and a
		     terminating \0, which will	be added  automatically.   The
		     input field is terminated by a white space	character.
	      c	     A	character  is  expected;  the  corresponding  argument
		     should be a character  pointer.   The  normal  skip  over
		     white  space is suppressed	in this	case; to read the next
		     non-space character, use %1s.  If a field width is	given,
		     the  corresponding	 argument  should refer	to a character
		     array, and	the indicated number of	characters is read.
	      [	     Indicates string data; the	normal skip over leading white
		     space  is	suppressed.  The left bracket is followed by a
		     set of characters,	which we will call the scanset,	and  a
		     right bracket; the	input field is the maximal sequence of
		     input characters consisting entirely of characters	in the
		     scanset.	The  circumflex	 (^),  when  it	appears	as the
		     first character in	the scanset, serves  as	 a  complement
		     operator  and  redefines  the  scanset  as	the set	of all
		     characters	not contained in the remainder of the  scanset
		     string.  There are	some conventions used in the construc-
		     tion of the scanset.  A range of characters may be	repre-
		     sented by the construct first-last, thus [0123456789] may
		     be	expressed [0-9].  Using	this convention, first must be
		     lexically	less  than  or equal to	last, or else the dash
		     will stand	for itself.  The dash will also	stand for  it-
		     self  whenever  it	 is the	first or the last character in
		     the scanset.  To include the right	square bracket	as  an
		     element of	the scanset, it	must appear as the first char-
		     acter (possibly preceded by a circumflex) of the scanset,
		     and in this case it will not be syntactically interpreted
		     as	the closing bracket.  The corresponding	argument  must
		     point  to a character array large enough to hold the data
		     field and the terminating \0, which will be  added	 auto-
		     matically.	  At  least  one character must	match for this
		     conversion	to be considered successful.

       The conversion characters d, u, o, x, and i may be preceded by l	 or  h
       to indicate that	a pointer to long or to	short rather than to int is in
       the argument list.  Similarly, the conversion characters	e,  f,	and  g
       may  be	preceded by l to indicate that a pointer to double rather than
       to float	is in the argument list.  The l	or h modifier is  ignored  for
       other conversion	characters.

       Avoid  this  common error: because printf(3V) does not require that the
       lengths of conversion descriptors and actual parameters	match,	coders
       sometimes  are  careless	with the scanf() functions.  But converting %f
       to &double or %lf to &float does	not work; the results are quite	incor-

       scanf() conversion terminates at	EOF, at	the end	of the control string,
       or when an input	character conflicts with the control string.   In  the
       latter  case,  the  offending  character	 is  left  unread in the input

       scanf() returns the number of successfully matched and  assigned	 input
       items;  this  number  can be zero in the	event of an early conflict be-
       tween an	input character	and the	control	string.	 The constant  EOF  is
       returned	upon end of input. Note: this is different from	0, which means
       that no conversion was done; if conversion was intended,	it  was	 frus-
       trated by an inappropriate character in the input.

       If  the	input ends before the first conflict or	conversion, EOF	is re-
       turned.	If the input ends after	the first conflict or conversion,  the
       number of successfully matched items is returned.

       Conversions  can	 be  applied to	the nth	argument in the	argument list,
       rather than the next unused argument.  In  this	case,  the  conversion
       character  %  (see  below)  is  replaced	by the sequence	%digit$, where
       digit is	a decimal integer n in the range [1,9],	giving the position of
       the argument in the argument list.  This	feature	provides for the defi-
       nition of format	strings	that select arguments in an order  appropriate
       to specific languages.

       The  format  string  can	contain	either form of a conversion specifica-
       tion, that is % or %digit$, although the	 two  forms  cannot  be	 mixed
       within a	single format string.

       All  forms  of  the scanf() functions allow for the detection of	a lan-
       guage dependent radix character in the input string. The	radix  charac-
       ter  is	defined	by the program's locale	(category LC_NUMERIC).	In the
       "C" locale, or in a locale where	the radix character  is	 not  defined,
       the radix character defaults to `.'.

       FORMFEED	is allowed as a	white space character in control strings.

       XPG2  requires  that  nl_scanf,	nl_fscanf  and nl_sscanf be defined as
       scanf, fscanf and sscanf, respectively for backward compatibility.

       If any items are	converted, scanf(), fscanf() and sscanf()  return  the
       number  of  items converted successfully.  This number may smaller than
       the number of items requested.  If no items are converted, these	 func-
       tions  return  0.   scanf(), fscanf() and sscanf() return EOF on	end of

       The call:
	      int i, n;	float x; char name[50];
	      n	= scanf("%d%f%s", &i, &x, name);

       with the	input line:
	      25 54.32E-1 thompson

       will assign to n	the value 3, to	i the value 25,	to x the value	5.432,
       and name	will contain thompson\0.  Or:
	      int i, j;	float x; char name[50];
	      (void) scanf("%i%2d%f%*d %[0-9]",	&j, &i,	&x, name);

       with input:

	      011 56789	0123 56a72

       will  assign  9	to  j,	56  to i, 789.0	to x, skip 0123, and place the
       string 56\0 in name.  The next call to getchar()	 (see  getc(3V))  will
       return a.  Or:
	      int i, j,	s, e; char name[50];
	      (void) scanf("%i %i %n%s%n", &i, &j, &s, name, &e);

       with input:
	      0x11 0xy johnson

       will  assign  17	 to  i,	 0 to j, 6 to s, will place the	string xy\0 in
       name, and will assign 8 to e.  Thus, the	length of name is e - s	 =  2.
       The next	call to	getchar() (see getc(3V)) will return a SPACE.

       getc(3V),  printf(3V),  setlocale(3V), stdio(3V), string_to_decimal(3),

       Trailing	white space  (including	 a  NEWLINE)  is  left	unread	unless
       matched in the control string.

       The  success  of	 literal matches and suppressed	assignments is not di-
       rectly determinable.

				21 January 1990			     SCANF(3V)


Want to link to this manual page? Use this URL:

home | help