sscanf man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

scanf(3)							      scanf(3)

NAME
       scanf, fscanf, sscanf - Convert formatted input

SYNOPSIS
       #include <stdio.h>

       int scanf(
	       const char *format,
	       [,pointer]...  ); int fscanf(
	       FILE *stream,
	       const char *format,
	       [,pointer]...  ); int sscanf(
	       const char *string,
	       const char *format,
	       [,pointer]...  );

       If  the pointer parameter identifies an object of type wchar_t (see the
       Description section), source files should include either	 <sys/types.h>
       or  <stddef.h> before <stdio.h> to maintain portability across all sys‐
       tems that conform to current versions of ANSI,  ISO,  or	 X/Open	 stan‐
       dards.

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       fscanf(), scanf(), sscanf():  ISO C, XPG4, XPG4-UNIX

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Specifies  the  format conversion.  Specifies the input stream.	Speci‐
       fies input to be read.  Points to the location to store the interpreted
       data.

DESCRIPTION
       The  scanf(),  fscanf(),	 and  sscanf()	functions read character data,
       interpret it according to a format, and	store  the  converted  results
       into  specified memory locations. The format parameter contains conver‐
       sion specifications used to interpret the input. The pointer parameters
       specify where to store the interpreted data.

       The  functions  read their input from the following sources: Reads from
       standard input (stdin).	Reads from the stream parameter.   Reads  from
       the character string specified by the string parameter.

       If  the	length	of  an	input  item is zero, these functions return an
       error.  This error indicates a matching failure unless end-of-file,  an
       encoding error, or a read error prevented input from a stream, in which
       case the error indicates input failure.

       If there are insufficient arguments for format, the function's behavior
       is undefined. If format is exhausted while arguments remain, the excess
       arguments are evaluated as always but are otherwise ignored.

       These functions truncate leading zeroes (before	a  decimal  point,  if
       any).  If  a  string value exceeds its formatted type destination limit
       (as defined by the machine architecture), the return value will be  the
       corresponding  MIN  or  MAX  value for the type, as appropriate, and an
       errno ERANGE value will be set.

       The format parameter can contain	 the  following	 items:	 A  conversion
       specification that directs the conversion of the next input field. Con‐
       version specifications start with a % (percent sign).  Any  white-space
       character  (as  determined  by  the  isspace() function) that matches 0
       (zero) or more white-space characters in the input stream.  Any charac‐
       ter  except % (percent sign) or a white-space character that must match
       the next character in the input stream.

       The input stream is broken into fields based on	the  following:	 White
       space

	      All conversion specifications except %c, %C, and %[ ignore lead‐
	      ing white space and  consider  the  first	 trailing  white-space
	      character as a field delimiter.  Invalid character

	      If  the  input  stream contains a character that is not allowed,
	      this invalid character delimits the field and is	considered  to
	      be the first character of the next field.	 Maximum width

	      If the conversion specification includes a maximum width and the
	      field is not terminated by white space or an invalid  character,
	      the  field is terminated when that character position is reached
	      in the input stream.

   Conversion Specifications
       Each conversion specification in the format parameter has the following
       syntax: The character % (percent sign).

	      The  scanf()  functions  can handle a format string that enables
	      the system to process elements of the pointer list  in  variable
	      order.  In  such a case, the normal conversion character % (per‐
	      cent sign) is replaced by %digit$, where digit is a decimal num‐
	      ber in the range from 1 to NL_ARGMAX. Conversion is then applied
	      to the specified pointer, not to the next unused	pointer.  This
	      feature  provides	 for  the  definition  of format strings in an
	      order appropriate to specific languages.	If the variable order‐
	      ing  feature  is	used, it must be specified for all conversions
	      except for conversion specifications that	 do  not  have	corre‐
	      sponding	pointers (conversion specifications with the * (aster‐
	      isk) assignment suppression and %%  conversion  specifications).
	      If  more	than  one  conversion specification specifies the same
	      digit, the results of the function are undefined.	 The  optional
	      assignment suppression character * (asterisk).  An optional dec‐
	      imal digit string that specifies the maximum  field  width.   An
	      optional	h  or  l indicating the size of the receiving variable
	      for some conversion specifiers, as follows: An h followed	 by  a
	      d, i, o, u, or x conversion specifier indicates that the receiv‐
	      ing variable will be treated as a short int  or  unsigned	 short
	      int.   An	 l followed by a d, i, o, u, or x conversion specifier
	      indicates that the receiving variable will be treated as a  long
	      int  or unsigned long int.  An l followed by an e, f, or g indi‐
	      cates that the receiving variable will be treated	 as  a	double
	      instead  of  a  float.  An L followed by an e, f, or g indicates
	      that the receiving variable will be treated  as  a  long	double
	      instead of a float.  An l followed by a c, s, or [scanset] indi‐
	      cates that the receiving variable will  be  treated  as  wchar_t
	      instead of char.	A conversion code character that specifies the
	      type of conversion to be applied: Accepts a  single  %  (percent
	      sign)  input  at	this point; no assignment is done.  Accepts an
	      optionally signed decimal integer, whose format is the  same  as
	      expected	for the subject sequence of strtol() with the value 10
	      for the base argument. The pointer parameter should be an	 inte‐
	      ger  pointer.   Accepts  an  optionally  signed decimal integer,
	      whose format is the same as expected for the subject sequence of
	      strtol()	with  the  value  0 for the base argument. The pointer
	      parameter should be an integer  pointer.	 Accepts  an  unsigned
	      decimal  integer;	 the  pointer  parameter should be an unsigned
	      integer pointer.	Accepts an octal integer; the pointer  parame‐
	      ter  should  be an integer pointer.  Accepts a hexadecimal inte‐
	      ger;  the	 pointer  parameter  should  be	 an  integer  pointer.
	      Accepts  a  floating-point  number.  The next field is converted
	      accordingly and  stored  through	the  corresponding  parameter,
	      which  should  be	 a  pointer  to	 a float. The input format for
	      floating-point numbers is a string of digits, with the following
	      optional	characteristics:  It can be a signed value.  It can be
	      an exponential value, containing a decimal point followed by  an
	      exponent	field,	which  consists of an E or an e followed by an
	      optionally signed integer.  It can be one of the special	values
	      INF,  NaNQ, or NaNS. This value is translated into the ANSI/IEEE
	      value for infinity, quiet NaN, or signaling  NaN,	 respectively.
	      Matches an unsigned hexadecimal long integer, the same as the %p
	      conversion of the printf() function. The corresponding  argument
	      should be a pointer to a pointer to void.	 No input is consumed.
	      The corresponding argument is a pointer to an integer into which
	      is  written  the number of characters read from the input stream
	      by this function. The assignment count returned at  the  comple‐
	      tion  of	this function is not incremented.  Accepts a string of
	      bytes that are not white-space  characters.  [ISO C]  (When  the
	      current  locale  supports	 shift-state encoding, skipping white-
	      space characters may result in redundant shift sequences.)

	      If no l qualifier is present, the pointer parameter should point
	      to  an  array  of	 characters that is large enough to accept the
	      converted sequence of characters,	 along	with  the  terminating
	      null  byte  automatically	 appended by the function. When inter‐
	      preting the input string, the function considers	a  white-space
	      character	 as  the delimiter of each input field and generates a
	      string of char values as output. If a field width is given,  the
	      function	assumes that pointer refers to a single-byte character
	      array, and only the specified number of char values is read from
	      the input string.

	      [ISO C]  If an l qualifier is present, the input is treated as a
	      sequence of multibyte characters	that  begins  in  the  initial
	      shift state. The function converts each multibyte character to a
	      wide-character as if by a call to the mbrtowc()  function,  with
	      the  conversion  state described by an mbstate_t object initial‐
	      ized to zero before the first multibyte character is  converted.
	      The  corresponding  pointer should point to a wchar_t array that
	      is large enough to accept the converted sequence of wide-charac‐
	      ters, plus the terminating null wide-character that is automati‐
	      cally added by the function.   Accepts  a	 string	 of  multibyte
	      characters  and  converts them as if by a call to the mbstowcs()
	      function. The pointer parameter should be a pointer to an	 array
	      of wchar_t. The array must be large enough to accept the string,
	      along with the terminating null wide-character that is automati‐
	      cally  added  by the function. The function treats a white-space
	      character as the delimiter of each field in the input string and
	      generates	 a  string  of	wchar_t as output. If the S conversion
	      specifier includes a field width, the behavior of the conversion
	      is  undefined.   Accepts a sequence of characters, the number of
	      which is specified by the field width (1 if no  field  width  is
	      specified).

	      If  the  l  qualifier is not present, the corresponding argument
	      should be a character array large enough to accept the converted
	      sequence.	 The function does not append a terminating null char‐
	      acter to this sequence.

	      [ISO C]  If the l qualifier is present, the corresponding	 argu‐
	      ment  is	a  sequence of multibyte characters that begins in the
	      initial shift state. The function converts each multibyte	 char‐
	      acter  as	 if by a call to the mbrtowc() function, with the con‐
	      version state described by an mbstate_t  object  initialized  to
	      zero  before  conversion	of  the first multibyte character. The
	      corresponding argument should be a pointer to the first  element
	      of  a wchar_t array that is large enough to accept the resulting
	      sequence of wide-characters.  The function  does	not  append  a
	      terminating null wide-character to this sequence.

	      The  c  directive	 suppresses  the normal skip over white space;
	      therefore, use %1s instead of %1c to  read  the  next  nonwhite-
	      space  character.	  Accepts  a  single  character or a series of
	      characters and converts to wchar_t type.	If there is  no	 field
	      width or a field width of 1 in the conversion specification, one
	      character is accepted and the  pointer  parameter	 should	 be  a
	      wchar_t  pointer.	 If there is a field width greater than 1, the
	      indicated number of characters  are  accepted  and  the  pointer
	      parameter	 should	 be an array of wchar_t.  The normal skip over
	      white space is suppressed. Use %1S rather than %1C to  read  the
	      next  nonwhite-space character.  Accepts as input the characters
	      included	in  the	 scanset.  The	scanset	 parameter  explicitly
	      defines  the  characters that are accepted in the string data as
	      those enclosed within [ ] (square brackets).

	      If the l qualifier is not	 present,  the	corresponding  pointer
	      parameter	 should point to an array of char that is large enough
	      to contain both the converted sequence and the terminating  null
	      character that is automatically added by the function.

	      [ISO C]  If  the l qualifier is present, the input is handled as
	      a sequence of multibyte characters that begins  in  the  initial
	      shift  state.  The function converts each multibyte character as
	      if by a call to the  mbrtowc()  function,	 with  the  conversion
	      state  described	by  an	mbstate_t  object  initialized to zero
	      before conversion of the first multibyte character.  The	corre‐
	      sponding	pointer	 parameter  should  be	a pointer to a wchar_t
	      array that is large enough to accept both the converted sequence
	      and  the	terminating  null wide-character that is automatically
	      added by the function.

	      The [scanset] directive suppresses the normal skip over  leading
	      white space.

	      A	 scanset  in  the  form of [^scanset] is an exclusive scanset;
	      that is, the ^ (circumflex) serves as a complement operator  and
	      the characters in scanset are not accepted as input.

	      Conventions  used in the construction of the scanset are as fol‐
	      lows: You can represent a range of characters by	the  construct
	      First-Last.  Thus,  you  can  express [0123456789] as [0-9]. The
	      First parameter must be lexically less than or  equal  to	 Last;
	      otherwise,  the - (dash) stands for itself. The dash also stands
	      for itself whenever it is the first or the last character in the
	      scanset.	You can include the ] (right bracket) as an element of
	      the scanset if it is the first character of the scanset. In this
	      case,  the  right bracket is not interpreted as the bracket that
	      closes the scanset. If the scanset is an exclusive scanset,  the
	      ]	 character is preceded by the ^ (circumflex) character to make
	      the ] an element of the scanset.

       The conversion specification syntax is summarized by the following syn‐
       opsis:

       %[digit$][*][width][sizecode]convcode

       The results from the conversion are placed in *pointer unless you spec‐
       ify assignment suppression with an * (asterisk). Assignment suppression
       provides	 a  way	 to describe an input field that is to be skipped. The
       input field is a string of nonwhite-space characters. It extends to the
       next inappropriate character or until the field width, if specified, is
       exhausted.

       The conversion code indicates how to interpret  the  input  field.  The
       corresponding  pointer must usually be of a restricted type. You should
       not specify the pointer parameter for a suppressed field.

       All *scanf() functions end at the end of the file, at the  end  of  the
       control	string,	 or when an input character conflicts with the control
       string. If the function ends with an input character conflict, the con‐
       flicting character is not read from the input stream.

       Unless  there  is a match in the control string, these functions do not
       read trailing white space (including a newline character).

       The success of literal matches and  suppressed  assignments  cannot  be
       directly	 determined.  The *scanf() functions return only the number of
       successfully matched and assigned input items.

RESTRICTIONS
       Currently, the Tru64 UNIX product does not  include  locales  that  use
       shift-state encoding. Some sections of this reference page refer to the
       mb_state object or describe behavior that is dependent  on  shift-state
       encoding.  This	information  is	 included only for your convenience in
       developing portable applications that run on multiple  platforms,  some
       of which may supply locales that do use shift-state encoding.

RETURN VALUES
       The scanf(), fscanf(), and sscanf() functions return the number of suc‐
       cessfully matched and assigned input items. This number can be 0 (zero)
       if  there was an early conflict between an input character and the con‐
       trol string. If the input ends before the first conflict or conversion,
       the functions return EOF (End-of-File).

ERRORS
       The  fscanf()  function	fails  if  the	stream is unbuffered or if the
       stream's buffer needs to be flushed and the  function  call  causes  an
       underlying read() or lseek() to be invoked and that operation fails. In
       addition, the scanf(), fscanf(), and sscanf() functions	set  errno  to
       the corresponding value for the following conditions: [Tru64 UNIX]  The
       O_NONBLOCK option is set for the	 underlying  stream  and  the  process
       would  be  delayed  by  the  read  operation.   [Tru64  UNIX]  The file
       descriptor underlying the stream is not a valid file descriptor	or  is
       not  open  for  reading.	 The input byte sequence does not form a valid
       character.  [Tru64 UNIX]	 The read operation was interrupted by a  sig‐
       nal  that  was  caught  and no data was transferred.  [Tru64 UNIX]  The
       call is attempting to read from the process's controlling terminal  and
       either  the  process  group  is	orphaned or the process is ignoring or
       blocking the SIGTTIN  signal.   [Tru64  UNIX]  Insufficient  memory  is
       available  for the operation.  [Tru64 UNIX]  One or more of the follow‐
       ing errors: The result would exceed the system-defined limits or	 cause
       an  overflow  (value too large) or an underflow (value too small).  The
       magnitude of x is such that  total  or  partial	loss  of  significance
       resulted.

SEE ALSO
       Functions: atof(3), atoi(3), getc(3), getwc(3), mbstowcs(3), mbtowc(3),
       printf(3), wprintf(3), wscanf(3)

       Standards: standards(5)

								      scanf(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net