fwscanf man page on Tru64

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

wscanf(3)							     wscanf(3)

NAME
       wscanf, fwscanf, swscanf - Convert formatted wide-character input

SYNOPSIS
       #include <wchar.h> #include <stdio.h>

       int wscanf(
	       const wchar_t *format,
	       [,pointer] ...  ); int fwscanf(
	       FILE *stream,
	       const wchar_t *format,
	       [,pointer] ...  ); int swscanf(
	       const wchar_t *wstr,
	       const wchar_t *format,
	       [,pointer] ...  );

LIBRARY
       Standard C Library (libc)

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

       fwscanf(), swscanf(), wscanf():	XSH5.0

       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 a wide-character string to be read.	 Points	 to  the  location  to
       store the interpreted data.

DESCRIPTION
       The  wscanf(),  fwscanf(),  and swscanf() functions read wide-character
       data, interpret it according  to a  format,  and	 store	the  converted
       results into specified memory  locations. The format parameter contains
       conversion specifications  used to interpret  the  input.  The  pointer
       parameters specify  where to store the interpreted data.

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

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

       The  format  parameter  can  contain  the following items: A conversion
       specification that directs the conversion of  the   next	 input	field.
       Conversion  specifications  start  with a % (percent sign).  Any white-
       space wide character (as determined by the  iswspace()  function)  that
       matches	0  (zero)  or  more  white-space  wide characters in the input
       stream.	Any wide character except % (percent sign)  or	a  white-space
       wide  character	that   must match the next wide 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 %[scanset]
	      ignore leading  white space  and	consider  the  first  trailing
	      white-space  wide character to  delimit the field.  Invalid wide
	      character

	      If the input stream contains  a  wide  character	that  is   not
	      allowed,	this  invalid wide character delimits the field and is
	      considered the first wide 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	  wide
	      character,  then	when that character position is reached in the
	      input  stream, the field is terminated.

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

	      The wscanf(), fwscanf(), and swscanf() functions can also 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 % (percent sign) is replaced	  by  %digit$,
	      where  digit  is	a  decimal  number  in	the  range  from  1 to
	      NL_ARGMAX. Conversion is then  applied to the specified pointer,
	      rather  than  to the next unused pointer.	 This feature provides
	      for the definition of format strings in an  order appropriate to
	      specific	languages.  If the  variable ordering feature is used,
	      it must be specified for all  conversions except for  conversion
	      specifications that do not have  corresponding pointers (conver‐
	      sion specifications with the * (asterisk) assignment suppression
	      and  %% conversion specifications).  If more than one conversion
	      specification specifies the same digit, the results of the func‐
	      tion are undefined.  The optional assignment suppression charac‐
	      ter * (asterisk).	 An optional decimal digit string that	speci‐
	      fies 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, an i, or an n conversion spec‐
	      ifier indicates that  the	 receiving  variable  is  treated   as
	      unsigned	short int; whereas an h followed by an o, a u, or an x
	      conversion specifier indicates that the  receiving  variable  is
	      treated  as short int.  An l followed by a d, an i, or an n con‐
	      version specifier	 indicates  that  the  receiving  variable  is
	      treated  as long int; whereas an l followed by  an o, a u, or an
	      x conversion specifier indicates that the receiving variable  is
	      treated  as  unsigned  long  int.	 An l followed by a e, f, or g
	      indicates that the  receiving  variable  is  treated  as	double
	      instead  of  float.   An l followed by a c, an s, or a [scanset]
	      conversion specifier indicates that the receiving	 variable   is
	      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. The complete conversion specification is  %%.   Accepts  a
	      decimal  integer	whose  format  is the same as expected for the
	      subject sequence of the wcstol() function with the value	10 for
	      the  base	 argument;  the pointer parameter should be an integer
	      pointer.	Accepts a decimal integer whose format is the same  as
	      expected for the	subject sequence of the wcstol() function with
	      the value	 0 for the base argument; the pointer parameter should
	      be  an  integer  pointer.	 Accepts an unsigned or signed decimal
	      integer; the pointer parameter should  be	 an  unsigned  integer
	      pointer.	 Accepts  an  octal  integer; in the absence of a size
	      modifier,	 the pointer parameter must  be	 an  unsigned  integer
	      pointer.	 Accepts  a  hexadecimal  integer; in the absence of a
	      size modifier,  the pointer parameter must be an unsigned	 inte‐
	      ger  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 for‐
	      mat  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  fol‐
	      lowed  by an exponent field, which consists of an E or an e fol‐
	      lowed 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 inte‐
	      ger, the same as	the %p conversion of the  wprintf()  function.
	      The  corresponding argument will be a pointer to void.  No input
	      is consumed. The corresponding argument  is   a  pointer	to  an
	      integer  into  which  is	written	 the number of wide characters
	      read from the input stream so far by this function.  The assign‐
	      ment   count  returned at the completion of this function is not
	      incremented.  Accepts a string of	 nonwhite-space	 wide  charac‐
	      ters.  The  pointer parameter should be a pointer that points to
	      an array of  wide characters large enough to  accept  the	 wide-
	      character	  string  with	 a  terminating	 null  wide  character
	      appended.	 The input field ends with  a white-space wide charac‐
	      ter. A string of wchar_t values is  output.  If a field width is
	      given, pointer refers to a wide-character	 array, and the	 indi‐
	      cated  number  of	 wchar_t  values is read.  Accepts a string of
	      wide characters.	The pointer parameter should be	 a pointer  to
	      an  array	 of wchar_t. The array must be large  enough to accept
	      the wide-character string with a	terminating null wide  charac‐
	      ter  appended.   The  input  field  ends with a white-space wide
	      character. A  string of wchar_t is output. If the	 S  conversion
	      specifier	  has a field width, the behavior of the conversion is
	      undefined.  Accepts a series of wide characters  of  the	number
	      specified	 by  the   field width (1 if the directive contains no
	      field width).

	      If the l qualifier is present, the corresponding	argument  must
	      be   a  pointer to the initial element of a character array that
	      is  large enough to accept the sequence. A null  wide  character
	      is  not  added to the array.  If the l qualifier is not present,
	      the function converts input wide characters as  if  by  repeated
	      calls  to	 the  wcrtomb()	 function,  with  the conversion state
	      described by an mbstate_t object initialized to zero before  the
	      first  wide character is converted.  A null byte is not added to
	      the array.  Because the normal skip over white  space   is  sup‐
	      pressed,	use  %1s  rather  than %1c to read the next  nonwhite-
	      space wide character.  Accepts as input one or  more  characters
	      in multibyte format  and converts to wchar_t type (as is done by
	      the mbstowcs() or mbsrtowcs() function).	If there is  no	 field
	      width  or	 a  field width of 1 in the conversion	specification,
	      the conversion result is one  wide  character  and  the  pointer
	      parameter	 should	 be  a wchar_t pointer.	 If the field width is
	      greater than 1, the conversion result contains no more  than the
	      indicated	 number	 of  wide characters and the pointer parameter
	      should be a wchar_t array. This array  must be large  enough  to
	      accept the conversion result, which does not include a terminat‐
	      ing  null wide character.	 Because the normal  skip  over	 white
	      space   is  suppressed, use %1S rather than %1C to read the next
	      nonwhite-space character.	 Accepts as input the wide  characters
	      included	in   the  scanset.  The	 scanset  parameter explicitly
	      defines the  wide characters that are  accepted  in  the	string
	      data  as those enclosed  within [	 ] (square brackets). The cor‐
	      responding pointer parameter  should be  an  array  of  wchar_t.
	      The  leading  white space that is normally skipped over is  sup‐
	      pressed. A scanset in the form of	 [^scanset]  is	 an  exclusive
	      scanset: the ^ (circumflex) serves as a complement  operator and
	      the following characters in the scanset  are   not  accepted  as
	      input.  Conventions used in the construction of the scanset fol‐
	      low: 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 the last
	      parameter,   or  else the - (dash) stands for itself. The - also
	      stands for itself	 whenever it is the first or the last  charac‐
	      ter 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,  it is not interpreted as the bracket
	      that closes  the	scanset.   If  the  scanset  is	 an  exclusive
	      scanset,	the ] is  preceded by the ^ (circumflex) to make the ]
	      an element of the scanset.  The corresponding pointer  parameter
	      must  point  to a	 wide-character array large enough to hold the
	      data field and that ends with a null wide character. The	termi‐
	      nating null is added automatically.

       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  suppres‐
       sion 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 wide 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.

       A  wscanf()  function ends at the end  of the file, the end of the con‐
       trol string, or when an input wide character  conflicts with  the  con‐
       trol  string.  If  wscanf() ends with an input wide character conflict,
       the conflicting wide character is not read from the input stream.

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

       The  success  of	 literal matches and suppressed assignments cannot  be
       directly determined. The wscanf() function returns the number  of  suc‐
       cessfully matched and assigned input items.

RESTRICTIONS
       Currently,  the	operating system does not provide any locales that use
       shift-state  encoding.  Therefore,   restartable	 conversion  functions
       (such  mbsrtowcs())  that  use  the mbstate_t object do not differ from
       their nonrestartable counterparts.  Information related to  shift-state
       encoding	 is  included  in this reference page  for your convenience in
       porting applications to other platforms,	 some  of  which  may  provide
       locales with shift-state encoding.

RETURN VALUES
       The  wscanf(), fwscanf(),  or swscanf() function returns the  number of
       successfully matched and assigned input items. This number   can	 be  0
       (zero)  if  there was an early conflict between an input wide character
       and the control string.	If the input ends before  the  first  conflict
       or conversion, the function returns EOF (End-of-File).

ERRORS
       The fwscanf() function fails if either the stream is unbuffered, or the
       stream's buffer needed to be flushed  and the function call  caused  an
       underlying  read()  or  lseek() to be invoked and that operation fails.
       In addition,  if	 the  any  of  the  following  conditions  occur,  the
       wscanf(),  fwscanf(),  and swscanf(), functions set errno to the corre‐
       sponding value: The O_NONBLOCK option is set for the underlying	stream
       and   the  process  would  be  delayed by the read operation.  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
       wide character.	The read operation was interrupted by  a  signal  that
       was  caught  and	 no   data  was	 transferred.	A  physical  I/O error
       occurred, or  the process is in a background process  group  attempting
       to  read	  from	its  controlling  terminal, and either	the process is
       ignoring or blocking  the  SIGTTIN  signal  or  the  process  group  is
       orphaned.  Insufficient memory is available for the operation.

SEE ALSO
       Functions: fopen(3), getwc(3), printf(3), scanf(3), wprintf(3)

       Standards: standards(5)

								     wscanf(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

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