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

FreeBSD Manual Pages

  
 
  

home | help
scanf(3C)		 Standard C Library Functions		     scanf(3C)

NAME
       scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf - convert formatted in-
       put

SYNOPSIS
       #include	<stdio.h>

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

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

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

       #include	<stdarg.h>
       #include	<stdio.h>

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

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

       int vsscanf(const char *s, const	char *format, va_list arg);

DESCRIPTION
       The scanf() function reads from the standard input stream stdin.

       The fscanf() function reads from	the named input	stream.

       The sscanf() function reads from	the string s.

       The vscanf(), vfscanf(),	and vsscanf() functions	are equivalent to  the
       scanf(),	 fscanf(),  and	 sscanf() functions, respectively, except that
       instead of being	called with a variable number of arguments,  they  are
       called  with  an	argument list as defined by the	<stdarg.h> header (see
       stdarg(3HEAD)). These functions do not invoke the va_end()  macro.  Ap-
       plications  using  these	functions should call va_end(ap) afterwards to
       clean up.

       Each function reads bytes, interprets them according to a  format,  and
       stores the results in its arguments. Each expects, as arguments,	a con-
       trol string format described below, and a set of	pointer	arguments  in-
       dicating	 where the converted input should be stored. The result	is un-
       defined if there	are insufficient arguments for the format. If the for-
       mat is exhausted	while arguments	remain,	the excess arguments are eval-
       uated but are otherwise ignored.

       Conversions can be applied to the nth argument after the	format in  the
       argument	 list,	rather than to the next	unused argument. In this case,
       the conversion character	% (see below) is replaced by the sequence %n$,
       where  n	is a decimal integer in	the range [1, NL_ARGMAX]. This feature
       provides	for the	definition of format strings that select arguments  in
       an  order appropriate to	specific languages. In format strings contain-
       ing the %n$  form  of  conversion  specifications,  it  is  unspecified
       whether	numbered arguments in the argument list	can be referenced from
       the format string more than once.

       The format can contain either form of a conversion specification,  that
       is,  % or %n$, but the two forms	cannot normally	be mixed within	a sin-
       gle format string. The only exception to	this is	that %%	or %*  can  be
       mixed with the %n$ form.

       The  scanf()  function  in all its forms	allows for detection of	a lan-
       guage-dependent radix character in the input string.  The radix charac-
       ter  is	defined	 in the	program's locale (category LC_NUMERIC).	In the
       POSIX locale, or	in a locale where the radix character is not  defined,
       the radix character defaults to a period	(.).

       The  format  is a character string, beginning and ending	in its initial
       shift state, if any, composed of	zero or	more directives.  Each	direc-
       tive is composed	of one of the following:

	  o  one  or  more white-space characters (space, tab, newline,	verti-
	     cal-tab or	form-feed characters);

	  o  an	ordinary character (neither % nor a white-space	character); or

	  o  a conversion specification.

   Conversion Specifications
       Each conversion specification is	introduced by the character %  or  the
       character sequence %n$, after which the following appear	in sequence:

	  o  An	optional assignment-suppressing	character *.

	  o  An	 optional  non-zero decimal integer that specifies the maximum
	     field width.

	  o  An	optional size modifier h, l (ell), ll (ell ell), or L indicat-
	     ing  the  size of the receiving object. The conversion characters
	     d,	i, and n must be preceded by h if the  corresponding  argument
	     is	 a  pointer  to	 short	int rather than	a pointer to int, by l
	     (ell) if it is a pointer to long int, or by ll (ell ell) if it is
	     a	pointer	to long	long int. Similarly, the conversion characters
	     o,	u, and x must be preceded by h if the  corresponding  argument
	     is	 a  pointer to unsigned	short int rather than a	pointer	to un-
	     signed int, by l (ell) if it is a pointer to unsigned  long  int,
	     or	 by ll (ell ell) if it is a pointer to unsigned	long long int.
	     The conversion characters e, f, and g must	be preceded by l (ell)
	     if	 the corresponding argument is a pointer to double rather than
	     a pointer to float, or by L if it is a pointer  to	 long  double.
	     Finally, the conversion characters	c, s, and [ must be precede by
	     l (ell) if	the corresponding argument is  a  pointer  to  wchar_t
	     rather  than  a pointer to	a character type. If an	h, l (ell), ll
	     (ell ell),	or L appears with any other conversion character,  the
	     behavior is undefined.

	  o  A	conversion  character that specifies the type of conversion to
	     be	applied. The valid conversion characters are described below.

       The scanf() functions execute each directive of the format in turn.  If
       a  directive  fails, as detailed	below, the function returns.  Failures
       are described as	input failures (due to	the  unavailability  of	 input
       bytes) or matching failures (due	to inappropriate input).

       A  directive composed of	one or more white-space	characters is executed
       by reading input	until no more valid input can be read, or  up  to  the
       first byte which	is not a white-space character which remains unread.

       A  directive  that is an	ordinary character is executed as follows. The
       next byte is read from the input	and compared with the byte  that  com-
       prises the directive; if	the comparison shows that they are not equiva-
       lent, the directive fails, and the differing and	subsequent  bytes  re-
       main unread.

       A  directive that is a conversion specification defines a set of	match-
       ing input sequences, as described below for each	conversion  character.
       A conversion specification is executed in the following steps:

       Input white-space characters (as	specified by isspace(3C)) are skipped,
       unless the conversion specification includes a [, c, C, or n conversion
       character.

       An item is read from the	input, unless the conversion specification in-
       cludes an n conversion character. An input item is defined as the long-
       est  sequence  of input bytes (up to any	specified maximum field	width,
       which may be measured in	characters or bytes dependent on  the  conver-
       sion character) which is	an initial subsequence of a matching sequence.
       The first byte, if any, after the input item  remains  unread.  If  the
       length of the input item	is 0, the execution of the conversion specifi-
       cation fails; this condition is a matching failure, unless end-of-file,
       an  encoding error, or a	read error prevented input from	the stream, in
       which case it is	an input failure.

       Except in the case of a % conversion character, the input item (or,  in
       the case	of a %n	conversion specification, the count of input bytes) is
       converted to a type appropriate to the conversion character. If the in-
       put  item  is  not a matching sequence, the execution of	the conversion
       specification fails; this condition is a	matching failure.  Unless  as-
       signment	suppression was	indicated by a *, the result of	the conversion
       is placed in the	object pointed to by the first argument	following  the
       format  argument	 that  has not already received	a conversion result if
       the conversion specification is introduced by %,	or in the nth argument
       if  introduced  by  the character sequence %n$. If this object does not
       have an appropriate type, or if the result of the conversion cannot  be
       represented in the space	provided, the behavior is undefined.

   Conversion Characters
       The following conversion	characters are valid:

       d     Matches an	optionally signed decimal integer, whose format	is the
	     same as expected for the subject sequence of strtol(3C) with  the
	     value  10	for  the base argument.	In the absence of a size modi-
	     fier, the corresponding argument must be a	pointer	to int.

       i     Matches an	optionally signed integer, whose format	is the same as
	     expected for the subject sequence of strtol() with	0 for the base
	     argument. In the absence of a size	 modifier,  the	 corresponding
	     argument must be a	pointer	to int.

       o     Matches  an  optionally signed octal integer, whose format	is the
	     same as expected for the subject sequence of strtoul(3C) with the
	     value 8 for the base argument. In the absence of a	size modifier,
	     the corresponding argument	must be	a pointer to unsigned int.

       u     Matches an	optionally signed decimal integer, whose format	is the
	     same  as  expected	for the	subject	sequence of strtoul() with the
	     value 10 for the base argument. In	the absence of	a  size	 modi-
	     fier,  the	 corresponding	argument must be a pointer to unsigned
	     int.

       x     Matches an	optionally signed hexadecimal integer, whose format is
	     the  same	as expected for	the subject sequence of	strtoul() with
	     the value 16 for the base argument. In the	absence	of a size mod-
	     ifier,  the  corresponding	argument must be a pointer to unsigned
	     int.

       e,f,g Matches an	optionally signed floating-point number, whose	format
	     is	 the  same as expected for the subject sequence	of strtod(3C).
	     In	the absence of a size  modifier,  the  corresponding  argument
	     must be a pointer to float.

	     If	the  printf(3C)	family of functions generates character	string
	     representations for infinity and NaN (a 7858 symbolic entity  en-
	     coded in floating-point format) to	support	the ANSI/IEEE Std 754:
	     1985 standard, the	 scanf() family	of  functions  will  recognize
	     them as input.

       s     Matches  a	sequence of bytes that are not white-space characters.
	     The corresponding argument	must be	a pointer to the initial  byte
	     of	 an  array of char, signed char, or unsigned char large	enough
	     to	accept the sequence and	a  terminating	null  character	 code,
	     which will	be added automatically.

	     If	 an  l	(ell) qualifier	is present, the	input is a sequence of
	     characters	that begins in the initial shift state.	 Each  charac-
	     ter  is converted to a wide-character as if by a call to the mbr-
	     towc(3C) function,	with the conversion state described by an  mb-
	     state_t  object initialized to zero before	the first character is
	     converted.	 The corresponding argument must be a  pointer	to  an
	     array of wchar_t large enough to accept the sequence and the ter-
	     minating null  wide-character, which will be added	automatically.

       [     Matches a non-empty sequence of characters	from a set of expected
	     characters	 (the scanset).	The normal skip	over white-space char-
	     acters is suppressed in this  case.  The  corresponding  argument
	     must be a pointer to the initial byte of an array of char,	signed
	     char, or unsigned char large enough to accept the sequence	and  a
	     terminating null byte, which will be added	automatically.

	     If	 an  l	(ell) qualifier	is present, the	input is a sequence of
	     characters	that begins in the initial shift state.	 Each  charac-
	     ter  in  the sequence is converted	to a wide-character as if by a
	     call to the mbrtowc() function, with  the	conversion  state  de-
	     scribed  by  an  mbstate_t	 object	initialized to zero before the
	     first character is	converted.  The	corresponding argument must be
	     a	pointer	 to an array of	wchar_t	large enough to	accept the se-
	     quence and	the terminating	null  wide-character,  which  will  be
	     added automatically.

	     The  conversion  specification includes all subsequent characters
	     in	the format string up  to  and  including  the  matching	 right
	     square  bracket  (]).  The	characters between the square brackets
	     (the scanlist) comprise the scanset, unless the  character	 after
	     the  left	square	bracket	is a circumflex	(^), in	which case the
	     scanset contains all characters that do not appear	in  the	 scan-
	     list  between the circumflex and the right	square bracket.	If the
	     conversion	specification begins with [] or	[^], the right	square
	     bracket  is  included  in	the scanlist and the next right	square
	     bracket is	the matching right square bracket that ends  the  con-
	     version  specification;  otherwise	the first right	square bracket
	     is	the one	that ends the conversion specification.	If a -	is  in
	     the scanlist and is not the first character, nor the second where
	     the first character is a ^, nor the last character, it  indicates
	     a range of	characters to be matched.

       c     Matches  a	 sequence of characters	of the number specified	by the
	     field width (1 if no field	width is  present  in  the  conversion
	     specification).  The  corresponding argument must be a pointer to
	     the initial byte of an array of char, signed  char,  or  unsigned
	     char  large enough	to accept the sequence.	No null	byte is	added.
	     The normal	skip over white-space characters is suppressed in this
	     case.

	     If	 an  l	(ell) qualifier	is present, the	input is a sequence of
	     characters	that begins in the initial shift state.	 Each  charac-
	     ter  in  the sequence is converted	to a wide-character as if by a
	     call to the mbrtowc() function, with  the	conversion  state  de-
	     scribed  by  an  mbstate_t	 object	initialized to zero before the
	     first character is	converted.  The	corresponding argument must be
	     a	pointer	 to an array of	wchar_t	large enough to	accept the re-
	     sulting sequence of wide-characters.  No null  wide-character  is
	     added.

       p     Matches  the  set of sequences that is the	same as	the set	of se-
	     quences that is produced by the %p	conversion of the  correspond-
	     ing  printf(3C)  functions.  The corresponding argument must be a
	     pointer to	a pointer to void. If the input	item is	a  value  con-
	     verted  earlier  during  the  same	program	execution, the pointer
	     that results will compare equal to	that value; otherwise the  be-
	     havior of the %p conversion is undefined.

       n     No	 input	is  consumed.  The  corresponding  argument  must be a
	     pointer to	the integer into which is to be	written	the number  of
	     bytes  read  from	the  input  so far by this call	to the scanf()
	     functions.	Execution of a %n conversion  specification  does  not
	     increment the assignment count returned at	the completion of exe-
	     cution of the function.

       C     Same as lc.

       S     Same as ls.

       %     Matches a single %; no conversion or assignment occurs. The  com-
	     plete conversion specification must be %%.

       If a conversion specification is	invalid, the behavior is undefined.

       The  conversion	characters  E,	G, and X are also valid	and behave the
       same as,	respectively, e, g, and	x.

       If end-of-file is encountered during input, conversion  is  terminated.
       If  end-of-file occurs before any bytes matching	the current conversion
       specification (except for %n) have been read (other than	leading	white-
       space characters, where permitted), execution of	the current conversion
       specification terminates	with an	input failure.	Otherwise, unless exe-
       cution  of  the	current	 conversion specification is terminated	with a
       matching	failure, execution of the following  conversion	 specification
       (if any)	is terminated with an input failure.

       Reaching	 the end of the	string in sscanf() is equivalent to encounter-
       ing end-of-file for fscanf().

       If conversion terminates	on a conflicting input,	the offending input is
       left  unread  in	the input. Any trailing	white space (including newline
       characters) is left unread unless matched by  a	conversion  specifica-
       tion. The success of literal matches and	suppressed assignments is only
       directly	determinable via the %n	conversion specification.

       The fscanf() and	scanf()	functions may mark the st_atime	field  of  the
       file  associated	 with  stream  for  update. The	st_atime field will be
       marked for update by  the  first	 successful  execution	of  fgetc(3C),
       fgets(3C),  fread(3C),  fscanf(),  getc(3C),  getchar(3C), gets(3C), or
       scanf() using stream that returns data not supplied by a	prior call  to
       ungetc(3C).

RETURN VALUES
       Upon  successful	 completion, these functions return the	number of suc-
       cessfully matched and assigned input items; this	number can be 0	in the
       event of	an early matching failure.  If the input ends before the first
       matching	failure	or conversion, EOF is returned.
	If a read error	occurs the error indicator for the stream is set,  EOF
       is returned, and	errno is set to	indicate the error.

ERRORS
       For  the	conditions under which the scanf() functions will fail and may
       fail, refer to fgetc(3C)	or fgetwc(3C).

       In addition, fscanf() may fail if:

       EILSEQ
	     Input byte	sequence does not form a valid character.

       EINVAL
	     There are insufficient arguments.

USAGE
       If the application calling the scanf() functions	 has  any  objects  of
       type  wint_t  or	 wchar_t, it must also include the header <wchar.h> to
       have these objects defined.

EXAMPLES
       Example 1: 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 Hamster

       will assign to n	the value 3, to	i the value 25,	to x the value	5.432,
       and name	will contain the string	Hamster.

       Example 2: The call:

       int i; float x; char name[50];
       (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);

       with input:

       56789 0123 56a72

       will  assign  56	to i, 789.0 to x, skip 0123, and place the string 56\0
       in name.	The next call to getchar(3C) will return the character a.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |MT-Safe			   |
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       fgetc(3C), fgets(3C), fgetwc(3C), fread(3C),  isspace(3C),  printf(3C),
       setlocale(3C), stdarg(3HEAD), strtod(3C), strtol(3C), strtoul(3C), wcr-
       tomb(3C), ungetc(3C), attributes(5)

SunOS 5.9			  3 May	2001			     scanf(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO

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

home | help