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

FreeBSD Manual Pages

  
 
  

home | help
scanf(3C)							     scanf(3C)

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

SYNOPSIS
       #include	<stdio.h>

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

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

       int sscanf(const	char *restrict s, const	char *restrict 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);

       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 .
       These functions do not invoke the va_end()  macro.  Applications	 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, vertical-
	    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 option length modifier that specifies the size of the receiving
	    object.

	 o  A conversion specifier character that specifies the	type  of  con-
	    version  to	 be  applied.  The valid conversion characters are de-
	    scribed 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. The length of the item	read  is  lim-
       ited  to	any specified maximum field width, which is interpreted	in ei-
       ther characters or bytes	depending on the conversion character. In  So-
       laris  default  mode, the input item is defined as the longest sequence
       of input	bytes that forms a matching sequence. In some  cases,  scanf()
       might need to read several extra	characters beyond the end of the input
       item to find the	end of a matching sequence. In C99/SUSv3 mode, the in-
       put  item is defined as the longest sequence of input bytes that	is, or
       is a prefix of, a matching sequence. With this definition, scanf() need
       only  read  at  most  one  character  beyond the	end of the input item.
       Therefore, in C99/SUSv3 mode, some sequences  that  are	acceptable  to
       strtod(3C),  strtol(3C),	 and  similar  functions  are  unacceptable to
       scanf().	In either mode,	scanf()	attempts to push back any excess bytes
       read  using  ungetc(3C).	 Assuming all such attempts succeed, the first
       byte, if	any, after the input item remains unread. If the length	of the
       input  item  is	0,  the	conversion fails. This condition is a matching
       failure unless end-of-file, an encoding error, or  a  read  error  pre-
       vented 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.

   Length Modifiers
       The length modifiers and	their meanings are:

       hh	       Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to signed char or unsigned char.

       h	       Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to short	or unsigned short.

       l (ell)	       Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to long or unsigned long; that a	 following  a,
		       A,  e, E, f, F, g, or G conversion specifier applies to
		       an argument with	type pointer to	double;	or that	a fol-
		       lowing  c,  s,  or [ conversion specifier applies to an
		       argument	with type pointer to wchar_t.

       ll (ell-ell)    Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to long long or unsigned	long long.

       j	       Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to intmax_t or uintmax_t.

       z	       Specifies that a	following d, i,	o, u, x, X, or n  con-
		       version	specifier  applies  to	an  argument with type
		       pointer to size_t or the	corresponding  signed  integer
		       type.

       t	       Specifies  that a following d, i, o, u, x, X, or	n con-
		       version specifier applies  to  an  argument  with  type
		       pointer	to  ptrdiff_t  or  the	corresponding unsigned
		       type.

       L	       Specifies that a	following a, A,	e, E, f, F,  g,	 or  G
		       conversion  specifier  applies to an argument with type
		       pointer to long double.

       If a length modifier appears with any conversion	specifier  other  than
       as specified above, 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	 modifier,  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  str-
		       tol() 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 for-
		       mat 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 argu-
		       ment 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	 modifier,  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	 modifier,  the	 corresponding
		       argument	must be	a pointer to unsigned int.

       a,e,f,g	       Matches an optionally signed floating-point number, in-
		       finity, or NaN, 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. The e, f,	and g specifiers match
		       hexadecimal floating point  values  only	 in  C99/SUSv3
		       (see  standards(5))  mode,  but	the a specifier	always
		       matches hexadecimal floating point values.

		       These conversion	specifiers match any subject  sequence
		       accepted	 by  strtod(3C),  including the	INF, INFINITY,
		       NAN, and	NAN(n-char-sequence) forms.  The result	of the
		       conversion  is the same as that of calling strtod() (or
		       strtof()	or strtold()) with the matching	sequence,  in-
		       cluding	the  raising  of floating point	exceptions and
		       the setting of errno to ERANGE, if applicable.

       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 se-
		       quence and a terminating	 null  character  code,	 which
		       will be added automatically.

		       If  an l	(ell) qualifier	is present, the	input is a se-
		       quence of characters that begins	in the	initial	 shift
		       state.  Each character is converted to a	wide-character
		       as if by	a call to the mbrtowc(3C) function,  with  the
		       conversion  state described by an mbstate_t object ini-
		       tialized	to zero	before the  first  character  is  con-
		       verted.	 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.

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

		       If  an l	(ell) qualifier	is present, the	input is a se-
		       quence of characters that begins	in the	initial	 shift
		       state.	Each character in the sequence is converted to
		       a wide-character	as if by a call	to the mbrtowc() func-
		       tion,  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	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  be-
		       tween  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 conversion
		       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	speci-
		       fied by the field width (1 if no	field width is present
		       in the conversion specification). The corresponding ar-
		       gument must be a	pointer	to the initial byte of an  ar-
		       ray of char, signed char, or unsigned char large	enough
		       to accept the sequence. No null byte is added. The nor-
		       mal  skip  over white-space characters is suppressed in
		       this case.

		       If an l (ell) qualifier is present, the input is	a  se-
		       quence  of  characters that begins in the initial shift
		       state.  Each character in the sequence is converted  to
		       a wide-character	as if by a call	to the mbrtowc() func-
		       tion, 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 resulting	sequence  of  wide-characters.
		       No null wide-character is added.

       p	       Matches	the  set  of sequences that is the same	as the
		       set of sequences	that is	produced by the	%p  conversion
		       of  the	corresponding printf(3C) functions. The	corre-
		       sponding	argument must be a pointer  to	a  pointer  to
		       void.  If  the  input item is a value converted earlier
		       during the same program execution, the pointer that re-
		       sults  will  compare equal to that value; otherwise the
		       behavior	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 con-
		       version specification does not increment	the assignment
		       count  returned	at  the	completion of execution	of the
		       function.

       C	       Same as lc.

       S	       Same as ls.

       %	       Matches a single	%; no conversion or assignment occurs.
		       The complete conversion specification must be %%.

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

       The  conversion	characters A, E, F, G, and X are also valid and	behave
       the same	as, respectively, a, e,	f, 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).

       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.

       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.

       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.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

       fgetc(3C), fgets(3C), fgetwc(3C), fread(3C),  isspace(3C),  printf(3C),
       setlocale(3C),	strtod(3C),   strtol(3C),   strtoul(3C),  wcrtomb(3C),
       ungetc(3C), attributes(5), standards(5)

				  24 Mar 2004			     scanf(3C)

NAME | SYNOPSIS | USAGE

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

home | help