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

FreeBSD Manual Pages

  
 
  

home | help
scanf(3S)							     scanf(3S)

NAME
       scanf,  fscanf,	sscanf	- formatted input conversion, read from	stream
       file

SYNOPSIS
DESCRIPTION
       reads from the standard input stream stdin.

       reads from the named input stream.

       reads from the character	string s.

       Each function reads characters, interprets them according to  the  con-
       trol  string format argument, and stores	the results in its pointer ar-
       guments.	 If there are insufficient arguments for the format,  the  be-
       havior  is  undefined.	If the format is exhausted while arguments re-
       main, the excess	arguments are ignored.	The  control  string  contains
       conversion specifications and other characters used to direct interpre-
       tation of input sequences.  The control string contains:

	      o	 White-space characters	(blanks, tabs, newlines, or formfeeds)
		 that  cause  input  to	be read	up to the next non-white-space
		 character (except in two cases	described below).

	      o	 An ordinary character (not that must match the	next character
		 of the	input stream.

	      o	 Conversion specifications, consisting of the character	an op-
		 tional	assignment suppressing character an optional numerical
		 maximum-field	width,	an optional (ell), (ell	ell), or indi-
		 cating	the size of the	receiving variable, and	 a  conversion
		 code.

	      o	 The conversion	specification can alternatively	be prefixed by
		 the character sequence	instead	of the character where n is  a
		 decimal  integer  in the range	is defined in The construction
		 indicates that	the value of the next input  field  should  be
		 placed	 in  the  nth argument,	rather than to the next	unused
		 one.  The two forms of	introducing  a	conversion  specifica-
		 tion,	and  must  not	be mixed within	a single format	string
		 with the following exception: Skip fields (see	below) can  be
		 designated as or In the latter	case, n	is ignored.

       Unless  the  specification contains the conversion character (described
       below), a conversion specification directs the conversion of  the  next
       input field.  The result	of a conversion	specification is placed	in the
       variable	to which the corresponding argument points,  unless  indicates
       assignment  suppression.	  Assignment suppression provides a way	to de-
       scribe an input field 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 white space leading an input field	is ig-
       nored.

       The conversion code indicates the interpretation	of  the	 input	field;
       the corresponding pointer argument must be of a restricted type.	 For a
       suppressed field, no pointer argument is	given.	The following  conver-
       sion codes are legal:

	      A	single	  is  expected	in the input at	this point; no assign-
			  ment is done.

	      A	decimal	integer	is expected;
			  the corresponding  argument  should  be  an  integer
			  pointer.

	      An unsigned decimal integer is expected;
			  the corresponding argument should be an unsigned in-
			  teger	pointer.

	      An octal integer is expected;
			  the corresponding argument should be an unsigned in-
			  teger	pointer.

	      A	hexadecimal integer is expected;
			  the corresponding argument should be an unsigned in-
			  teger	pointer.  The and  conversion  characters  are
			  equivalent.

	      An integer is expected;
			  the  corresponding  argument	should	be  an integer
			  pointer.  The	value of the next input	 item,	inter-
			  preted according to C	conventions, will be stored; a
			  leading implies octal, a leading  implies  hexadeci-
			  mal; otherwise, decimal is assumed.

	      An	  type	is expected; the corresponding argument	should
			  be an	pointer	which is the 80-bit  IEEE-754  double-
			  extended type	in the Itanium architecture; should be
			  used with the	floating-point specifiers and

	      Cause the	total number of	bytes (including white space)
			  scanned since	the function call to  be  stored;  the
			  corresponding	argument should	be an integer pointer.
			  No input is consumed.	  The  function	 return	 value
			  does	not  include  assignments in the count of suc-
			  cessfully matched and	assigned input items.

	      A	floating-point number is expected;
			  the next field is converted accordingly  and	stored
			  through  the corresponding argument, which should be
			  a pointer to a float.	 The input format  for	float-
			  ing-point  numbers is	an optionally signed string of
			  digits, possibly containing a	radix character,  fol-
			  lowed	by an optional exponent	field consisting of an
			  or an	followed by an optional	or space, followed  by
			  an  integer.	 For  IPF  only, hexadecimal floating-
			  point	input also is accepted:	the format is  an  op-
			  tionally signed string of hexadecimal	digits,	possi-
			  bly containing a radix character, followed by	an op-
			  tional  binary  exponent field (indicating the power
			  of two by  which  the	 significand  part  is	to  be
			  scaled) consisting of	a or a followed	by an optional
			  or space, followed by	a decimal integer.   The  con-
			  version  characters  and behave the same as, respec-
			  tively, and The and  conversions  will  convert  the
			  string (case insensitive) or the string (case	insen-
			  sitive) to the appropriate floating  point  infinity
			  value	 (single,  double,  or quadruple precision, as
			  specified by	the  conversion	 precision  modifier).
			  The  and  conversions	 will convert the string (case
			  insensitive) to the appropriate floating point value
			  (single,  double,  or	quadruple precision, as	speci-
			  fied by the conversion precision modifier).

	      A	character is expected;
			  the corresponding argument  should  be  a  character
			  pointer.   The  normal skip-over-white-space is sup-
			  pressed in this case;	to  read  the  next  non-space
			  character, use If a field width is given, the	corre-
			  sponding argument refers to a	character  array;  the
			  indicated number of characters is read.

			  If an	(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 con-
			  verted to a wide-character as	if by a	 call  to  the
			  function,  with the conversion state described by an
			  object initialized to	zero before the	first  charac-
			  ter  is  converted.  The corresponding argument must
			  be a pointer to an array of large enough  to	accept
			  the  resulting sequence of wide-characters.  No null
			  wide-character  is  added.   The  normal  skip-over-
			  white-space  is suppressed in	this case; to read the
			  next non-space character, use	If a  field  width  is
			  given,  the  corresponding argument refers to	a wide
			  character array; the indicated number	of  characters
			  is read and converted.

	      Same as

	      A	 character  string  is	expected;  the	corresponding argument
	      should be
			  a character pointer pointing to an array of  charac-
			  ters	large enough to	accept the string and a	termi-
			  nating which	is  added  automatically.   The	 input
			  field	 is  terminated	 by  a	white-space character.
			  cannot read a	null string.

			  If an	(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 function, with the
			  conversion state described by	an object  initialized
			  to  zero  before  the	 first character is converted.
			  The corresponding argument must be a pointer	to  an
			  array	of large enough	to accept the sequence and the
			  terminating null wide-character, which will be added
			  automatically.   The	input field is terminated by a
			  white-space character.  cannot read a	null string.

	      Same as

	      Indicates	string data and	 the  normal  skip-over-leading-white-
	      space
			  is  suppressed.   The	 left bracket is followed by a
			  set of characters, called 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 com-
			  plement  operator  and  redefines the	scanset	as the
			  set of all characters	contained in the remainder  of
			  the  scanset	string.	  Construction	of the scanset
			  follows certain conventions.	A range	of  characters
			  may  be represented by the construct first-last, en-
			  abling [0123456789] to be  expressed	[0-9].	 Using
			  this	convention,  first must	be lexically less than
			  or equal to last; otherwise, the dash	stands for it-
			  self.	  The  dash  also stands for itself when 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  character
			  (possibly  preceded by a circumflex) of the scanset,
			  in which case	it will	not be	interpreted  syntacti-
			  cally	as the closing bracket.	 The corresponding ar-
			  gument must point to a character array large	enough
			  to hold the data field and the terminating which are
			  added	automatically.	At least  one  character  must
			  match	for this conversion to succeed.

			  If an	(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 con-
			  verted to a wide-character as	if by a	 call  to  the
			  function,  with the conversion state described by an
			  object initialized to	zero before the	first  charac-
			  ter  is  converted.  The corresponding argument must
			  be a pointer to an array of large enough  to	accept
			  the  sequence	 and the terminating null wide-charac-
			  ter, which will be added automatically.

	      A	sequence of unsigned hexadecimal numbers is expected.
			  This sequence	may  be	 produced  by  the  conversion
			  character  of	 The corresponding argument shall be a
			  pointer to a pointer to into which the value	repre-
			  sented  by  the hexadecimal sequence is stored.  The
			  behavior of this conversion is undefined for any in-
			  put item other than a	value converted	earlier	during
			  the same program execution.

       The conversion characters and can be preceded by	or to indicate that  a
       pointer	to a or	rather than to an is in	the argument list.  Similarly,
       the conversion characters and can be preceded by	or to indicate that  a
       pointer	to or rather than to an	is in the argument list.  Finally, the
       conversion characters and can be	preceded by  or	 to  indicate  that  a
       pointer to a or rather than to a	is in the argument list.  The or modi-
       fier is ignored for other conversion characters.

       The functions terminate their conversions 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 stream.

EXTERNAL INFLUENCES
   Locale
       The  category  determines  the  interpretation  of  ordinary characters
       within format strings as	single and/or  multi-byte  characters.	 Field
       width  is  given	in terms of bytes.  Characters received	from the input
       stream are interpreted as single- or multi-byte	characters  as	deter-
       mined  by the category and the field width is decremented by the	length
       of the character.

       The category determines the radix character expected  within  floating-
       point numbers.

   International Code Set Support
       Single- and multi-byte character	code sets are supported.

RETURN VALUES
       If  the	input ends before the first conflict or	conversion, EOF	is re-
       turned.	Otherwise, these functions return the number  of  successfully
       assigned	 input items.  This number is a	short count, or	even zero if a
       conflict	ensues between an input	character and the control string.

ERRORS
       and fail	if data	needs to be read into the stream's buffer, and:
	      [EAGAIN] The O_NONBLOCK flag is set for the file descriptor  un-
	      derlying stream and the process would be delayed in the read op-
	      eration.

	      [EBADF]
		     The file descriptor underlying stream is not a valid file
		     descriptor	open for reading.

	      [EINTR]
		     The read operation	was terminated due to the receipt of a
		     signal, and either	no data	was transferred	or the	imple-
		     mentation does not	report partial transfer	for this file.

	      [EIO]  The  process  is  a member	of a background	process	and is
		     attempting	to read	from its controlling terminal, and ei-
		     ther  the	process	 is ignoring or	blocking the signal or
		     the process group of the process is orphaned.

	      [EILSEQ]
		     The data obtained from the	input stream does not  form  a
		     valid wide	character.

       Additional values can be	set by the underlying function (see read(2)).

EXAMPLES
       The call:

       with the	input line:

       assigns	to n the value to i the	value to x the value and name contains
       Or:

       with input:

       assigns to i, to	x, skips and places the	string in name.	 The next call
       to (see getc(3S)) returns

       For  another  example,  to  create a language-independent date scanning
       routine,	use:

       For American usage, format would	point to a string:

       The input:

       would assign to month, to day and to year.

       For German usage, format	would point to a string:

       The input:

	      3	Juli 1986

       would assign to month, to day and to year.

       The success of literal matches and suppressed assignments can be	deter-
       mined  with  the	 conversion  specification.   Here  is an example that
       checks the success of literal matches:

       Here is an example that checks the success of suppressed	assignments:

APPLICATION USAGE
       After or	is applied to a	stream,	the stream becomes byte-oriented  (see
       orientation(5)).

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

       Truncation of multi-byte	characters may occur if	a field	width is  used
       with the	conversion character.

AUTHOR
       was developed by	AT&T and HP.

SEE ALSO
       getc(3S),  setlocale(3C),  printf(3S), strtod(3C), strtol(3C), orienta-
       tion(5),	thread_safety(5).

STANDARDS CONFORMANCE
								     scanf(3S)

NAME | SYNOPSIS | DESCRIPTION | EXTERNAL INFLUENCES | RETURN VALUES | ERRORS | EXAMPLES | APPLICATION USAGE | WARNINGS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help