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

FreeBSD Manual Pages


home | help
SCANF(3)		   Linux Programmer's Manual		      SCANF(3)

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

       #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);

   Feature Test	Macro Requirements for glibc (see feature_test_macros(7)):

       vscanf(), vsscanf(), vfscanf():
	   _XOPEN_SOURCE >= 600	|| _ISOC99_SOURCE ||
	   _POSIX_C_SOURCE >= 200112L;
	   or cc -std=c99

       The  scanf() family of functions	scans input according to format	as de-
       scribed below.  This format may contain conversion specifications;  the
       results	from  such  conversions,  if  any, are stored in the locations
       pointed to by the pointer arguments that	follow format.	 Each  pointer
       argument	 must  be of a type that is appropriate	for the	value returned
       by the corresponding conversion specification.

       If the number of	conversion specifications in format exceeds the	number
       of  pointer  arguments,	the  results  are undefined.  If the number of
       pointer arguments exceeds the number of conversion specifications, then
       the excess pointer arguments are	evaluated, but are otherwise ignored.

       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(3) and vsprintf(3) functions

       The format string consists of a sequence	of directives  which  describe
       how  to	process	 the sequence of input characters.  If processing of a
       directive fails,	no further input is  read,  and	 scanf()  returns.   A
       "failure"  can  be either of the	following: input failure, meaning that
       input characters	were unavailable, or matching  failure,	 meaning  that
       the input was inappropriate (see	below).

       A directive is one of the following:

       o      A	sequence of white-space	characters (space, tab,	newline, etc.;
	      see isspace(3)).	This directive matches	any  amount  of	 white
	      space, including none, in	the input.

       o      An ordinary character (i.e., one other than white	space or '%').
	      This character must exactly match	the next character of input.

       o      A	conversion specification, which	commences with a '%' (percent)
	      character.  A sequence of	characters from	the input is converted
	      according	to this	specification, and the result is placed	in the
	      corresponding  pointer argument.	If the next item of input does
	      not match	the conversion specification, the  conversion  fails--
	      this is a	matching failure.

       Each  conversion	specification in format	begins with either the charac-
       ter '%' or the character	sequence "%n$" (see below for the distinction)
       followed	by:

       o      An  optional '*' assignment-suppression character: scanf() reads
	      input as directed	by the conversion specification, but  discards
	      the  input.   No corresponding pointer argument is required, and
	      this specification is not	included in the	 count	of  successful
	      assignments returned by scanf().

       o      An optional 'm' character.  This is used with string conversions
	      (%s, %c, %[), and	relieves the caller of the need	to allocate  a
	      corresponding  buffer  to	hold the input:	instead, scanf() allo-
	      cates a buffer of	sufficient size, and assigns  the  address  of
	      this  buffer to the corresponding	pointer	argument, which	should
	      be a pointer to a	char * variable	(this variable does  not  need
	      to  be  initialized  before the call).  The caller should	subse-
	      quently free(3) this buffer when it is no	longer required.

       o      An optional decimal integer which	specifies  the	maximum	 field
	      width.   Reading of characters stops either when this maximum is
	      reached or when a	nonmatching character is found,	whichever hap-
	      pens  first.  Most conversions discard initial white space char-
	      acters (the exceptions are noted	below),	 and  these  discarded
	      characters  don't	 count toward the maximum field	width.	String
	      input conversions	store a	terminating null byte ('\0')  to  mark
	      the  end	of the input; the maximum field	width does not include
	      this terminator.

       o      An optional type modifier	character.  For	example,  the  l  type
	      modifier	is used	with integer conversions such as %d to specify
	      that the corresponding pointer argument refers  to  a  long  int
	      rather than a pointer to an int.

       o      A	 conversion specifier that specifies the type of input conver-
	      sion to be performed.

       The conversion specifications in	format are of two forms, either	begin-
       ning  with  '%'	or  beginning with "%n$".  The two forms should	not be
       mixed in	the same format	string,	except that a string containing	 "%n$"
       specifications  can include %% and %*.  If format contains '%' specifi-
       cations then these correspond in	order with  successive	pointer	 argu-
       ments.	In the "%n$" form (which is specified in POSIX.1-2001, but not
       C99), n is a decimal integer that specifies that	 the  converted	 input
       should  be placed in the	location referred to by	the n-th pointer argu-
       ment following format.

       The following type modifier characters can appear in a conversion spec-

       h      Indicates	 that  the conversion will be one of d,	i, o, u, x, X,
	      or n and the next	pointer	is a pointer to	a  short  int  or  un-
	      signed short int (rather than int).

       hh     As  for h, but the next pointer is a pointer to a	signed char or
	      unsigned char.

       j      As for h,	but the	next pointer is	a pointer to an	intmax_t or  a
	      uintmax_t.  This modifier	was introduced in C99.

       l      Indicates	 either	that the conversion will be one	of d, i, o, u,
	      x, X, or n and the next pointer is a pointer to a	 long  int  or
	      unsigned long int	(rather	than int), or that the conversion will
	      be one of	e, f, or g and the next	pointer	is a pointer to	double
	      (rather  than float).  Specifying	two l characters is equivalent
	      to L.  If	used with %c or	%s the corresponding parameter is con-
	      sidered  as  a  pointer  to  a  wide character or	wide-character
	      string respectively.

       L      Indicates	that the conversion will be either e, f, or g and  the
	      next  pointer is a pointer to long double	or the conversion will
	      be d, i, o, u, or	x and the next pointer is a  pointer  to  long

       q      equivalent to L.	This specifier does not	exist in ANSI C.

       t      As  for  h,  but	the  next pointer is a pointer to a ptrdiff_t.
	      This modifier was	introduced in C99.

       z      As for h,	but the	next pointer is	a pointer to a	size_t.	  This
	      modifier was introduced in C99.

       The following conversion	specifiers are available:

       %      Matches a	literal	'%'.  That is, %% in the format	string matches
	      a	single input '%' character.  No	conversion is done  (but  ini-
	      tial  white space	characters are discarded), and assignment 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 backward	compatibility.
	      (Note: thus only in  libc4.   In	libc5  and  glibc  the	%D  is
	      silently ignored,	causing	old programs to	fail mysteriously.)

       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
	      otherwise.  Only characters that	correspond  to	the  base  are

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

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

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

       X      Equivalent to x.

       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 f.

       a      (C99) Equivalent to f.

       s      Matches  a  sequence  of	non-white-space	 characters;  the next
	      pointer must be a	pointer	to character array that	is long	enough
	      to hold the input	sequence and the terminating null byte ('\0'),
	      which is added automatically.  The input string stops  at	 white
	      space or at the maximum field width, whichever occurs first.

       c      Matches  a  sequence  of characters whose	length is specified by
	      the maximum field	width (default 1); the next pointer must be  a
	      pointer to char, and there must be enough	room for all the char-
	      acters (no terminating null byte 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 null byte.  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 de-
	      fined by the characters between the open bracket [ character and
	      a	 close bracket ] character.  The set excludes those characters
	      if the first character after 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 spe-
	      cial; when placed	between	two other characters, it adds all  in-
	      tervening	 characters  to	the set.  To include a hyphen, make it
	      the last character before	the  final  close  bracket.   For  in-
	      stance, [^]0-9-] means the set "everything except	close bracket,
	      zero through nine, and hyphen".  The string ends	with  the  ap-
	      pearance	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 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, al-
	      though it	can be suppressed with	the  *	assignment-suppression
	      character.   The	C  standard says: "Execution of	a %n directive
	      does not increment the assignment	count returned at the  comple-
	      tion of execution" but the Corrigendum seems to contradict this.
	      Probably it is wise not to make any assumptions on the effect of
	      %n conversions on	the return value.

       These  functions	 return	the number of input items successfully matched
       and assigned, which can be fewer	than provided for, or even zero	in the
       event of	an early matching failure.

       The  value EOF is returned if the end of	input is reached before	either
       the first successful conversion or a matching failure occurs.   EOF  is
       also returned if	a read error occurs, in	which case the error indicator
       for the stream (see ferror(3)) is set, and errno	is  set	 indicate  the

       EAGAIN The file descriptor underlying stream is marked nonblocking, and
	      the read operation would block.

       EBADF  The file descriptor underlying stream is invalid,	 or  not  open
	      for reading.

       EILSEQ Input byte sequence does not form	a valid	character.

       EINTR  The read operation was interrupted by a signal; see signal(7).

       EINVAL Not enough arguments; or format is NULL.

       ENOMEM Out of memory.

       ERANGE The  result  of an integer conversion would exceed the size that
	      can be stored in the corresponding integer type.

       The functions fscanf(), scanf(),	and sscanf() conform to	 C89  and  C99
       and POSIX.1-2001.  These	standards do not specify the ERANGE error.

       The  q  specifier is the	4.4BSD notation	for long long, while ll	or the
       usage of	L in integer conversions is the	GNU notation.

       The Linux version of these functions is based on	the GNU	libio library.
       Take  a	look  at the info documentation	of GNU libc (glibc-1.08) for a
       more concise description.

       The GNU C library supported the dynamic allocation conversion specifier
       (as  a  nonstandard extension) via the a	character.  This feature seems
       to be present at	least as far back as glibc 2.0.

       It is not available if the program is compiled with gcc -std=c99	or gcc
       -D_ISOC99_SOURCE	 (unless _GNU_SOURCE is	also specified), in which case
       the a is	interpreted as a specifier  for	 floating-point	 numbers  (see

       Since version 2.7, glibc	also provides the m modifier for the same pur-
       pose as the a modifier.	The m modifier has the following advantages:

       * It may	also be	applied	to %c conversion specifiers (e.g., %3mc).

       * It avoids ambiguity with respect to the %a floating-point  conversion
	 specifier (and	is unaffected by gcc -std=c99 etc.)

       * It is specified in the	POSIX.1-2008 standard.

       All  functions  are  fully  C89	conformant, but	provide	the additional
       specifiers q and	a as well as an	additional behavior of	the  L	and  l
       specifiers.   The  latter  may be considered to be a bug, as it changes
       the behavior of specifiers defined in C89.

       Some combinations of the	type modifiers and conversion  specifiers  de-
       fined  by  ANSI C do not	make sense (e.g., %Ld).	 While they may	have a
       well-defined behavior on	Linux, this need not to	be so on other	archi-
       tectures.  Therefore it usually is better to use	modifiers that are not
       defined by ANSI C at all, that is, use q	instead	of  L  in  combination
       with d, i, o, u,	x, and X conversions or	ll.

       The usage of q is not the same as on 4.4BSD, as it may be used in float
       conversions equivalently	to L.

       To use the dynamic allocation conversion	 specifier,  specify  m	 as  a
       length  modifier	 (thus %ms or %m[range]).  The caller must free(3) the
       returned	string,	as in the following example:

	   char	*p;
	   int n;

	   errno = 0;
	   n = scanf("%m[a-z]",	&p);
	   if (n == 1) {
	       printf("read: %s\n", p);
	   } else if (errno != 0) {
	   } else {
	       fprintf(stderr, "No matching characters\n");

       As shown	in the above example, it is necessary to call free(3) only  if
       the scanf() call	successfully read a string.

       getc(3),	printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)

       This  page  is  part of release 3.53 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found	at

GNU				  2013-01-30			      SCANF(3)


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

home | help