fwscanf(3C)




NAME

     fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf - con-
     vert formatted wide-character input


SYNOPSIS

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

     int fwscanf(FILE *stream, const wchar_t *format, ...);

     int wscanf(const wchar_t *format, ...);

     int swscanf(const wchar_t *s, const wchar_t *format, ...);

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

     int vfwscanf(FILE *stream,  const wchar_t  *format,  va_list
     arg);

     int  vswcanf(const  wchar_t  *ws,  const  wchar_t   *format,
     va_list arg);

     int vswscanf(const wchar_t *format, va_list arg);


DESCRIPTION

     The fwscanf() function reads from the named input stream.

     The wscanf() function reads from the standard  input  stream
     stdin.

     The swscanf() function reads from the wide-character  string
     s.

     The  vfwscanf(),  vswcanf(),  and  vswcanf()  functions  are
     equivalent  to  the fwscanf(), swscanf(), and wscanf() func-
     tions, 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  (see
     stdarg(3HEAD)).  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 wide-characters, interprets them accord-
     ing  to  a  format, and stores the results in its arguments.
     Each expects, as arguments, a control wide-character  string
     format described below, and a set of pointer arguments indi-
     cating where the  converted  input  should  be  stored.  The
     result  is undefined if there are insufficient arguments for
     the format. If  the  format  is  exhausted  while  arguments
     remain, the excess arguments are evaluated 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 wide-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 wide-character strings that
     select  arguments  in  an  order  appropriate  to   specific
     languages.  In  format wide-character strings containing the
     %n$ form of conversion  specifications,  it  is  unspecified
     whether  numbered  arguments  in  the  argument  list can be
     referenced from the format  wide-character string more  than
     once.

     The format can contain either form of a conversion  specifi-
     cation, that is, % or %n$, but the two forms cannot normally
     be mixed within a single format wide-character string.   The
     only  exception  to  this is that %% or %* can be mixed with
     the %n$ form.

     The fwscanf() function in all its forms allows for detection
     of a language-dependent radix character in the input string,
     encoded as a wide-character value.  The  radix character  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 wide-character string composed  of  zero  or
     more  directives.  Each  directive is composed of one of the
     following: one or more white-space  wide-characters  (space,
     tab,  newline,   vertical-tab  or  form-feed characters); an
     ordinary wide-character (neither % nor a white-space charac-
     ter); or a conversion specification. Each conversion specif-
     ication is introduced by a % or the 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 optional size modifier h , l(ell), or L  indicating
           the  size  of  the  receiving  object.  The conversion
           wide-characters c, s, and [ must be precede by l (ell)
           if  the corresponding argument is a pointer to wchar_t
           rather than a pointer to a character type. The conver-
           sion wide-characters d, i, and n must be preceded by h
           if the corresponding argument is a  pointer  to  short
           int  rather than a pointer to int, or by l (ell) if it
           is a pointer to long int.  Similarly,  the  conversion
           wide-characters  o,  u, and x must be preceded by h if
           the corresponding argument is a  pointer  to  unsigned
           short int rather than a pointer to unsigned int, or by
           l (ell) if it is a pointer to unsigned long  int.  The
           conversion  wide-characters  e,  f, and g must be pre-
           ceded by l (ell) if the corresponding  argument  is  a
           pointer  to  double rather than a pointer to float, or
           by L if it is a pointer to long double.  If  an  h,  l
           (ell),  or   L appears with any other conversion wide-
           character, the behavior is undefined.

        o  A conversion wide-character that specifies the type of
           conversion  to  be applied. The valid conversion wide-
           characters are described below.

     The fwscanf() functions execute each directive of the format
     in turn.  If a directive fails, as detailed below, the func-
     tion 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  wide-
     characters  is executed by reading input until no more valid
     input can be read, or up to the first  wide-character  which
     is not a white-space  wide-character, which remains unread.

     A directive that is an ordinary wide-character  is  executed
     as  follows.  The next wide-character is read from the input
     and compared with  the  wide-character  that  comprises  the
     directive;  if  the  comparison  shows  that  they  are  not
     equivalent, the directive fails, and the differing and  sub-
     sequent wide-characters remain unread.

     A directive that is a conversion specification defines a set
     of  matching  input  sequences,  as described below for each
     conversion  wide-character. A  conversion  specification  is
     executed in the following steps:

     Input   white-space   wide-characters   (as   specified   by
     iswspace(3C))  are skipped, unless the conversion specifica-
     tion includes a [, c, or n conversion character.

     An item is  read  from  the  input,  unless  the  conversion
     specification  includes  an  n conversion wide-character. An
     input item is defined  as  the  longest  sequence  of  input
     wide-characters,  not  exceeding  any specified field width,
     which is an initial subsequence of a matching sequence.  The
     first  wide-character,  if any, after the input item remains
     unread. If the length of the input item is 0, the  execution
     of  the  conversion specification fails; this condition is a
     matching failure, unless end-of-file, an encoding error,  or
     a  read error prevented input from the stream, in which case
     it is an input failure.

     Except in the case of a  %  conversion  wide-character,  the
     input  item  (or,  in the case of a %n conversion specifica-
     tion, the count of input wide-characters) is converted to  a
     type  appropriate  to  the conversion wide-character. If the
     input item is not a matching sequence, the execution of  the
     conversion specification fails; this condition is a matching
     failure. Unless assignment 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 conver-
     sion specification is introduced by %, or in the  nth  argu-
     ment  if  introduced by the wide-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.

     The following conversion wide-characters are valid:

     d     Matches an optionally signed  decimal  integer,  whose
           format  is  the  same  as  expected  for  the  subject
           sequence of wcstol(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
           wcstol(3C) 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 wcstoul(3C) with the value 8 for the base argument.
           In  the  absence of a size modifier, the corresponding
           argument 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 wcstoul(3C) 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 wcstoul(3C) 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.

     e,f,g Matches an optionally  signed  floating-point  number,
           whose  format  is the same as expected for the subject
           sequence of wcstod(3C).  In  the  absence  of  a  size
           modifier, the corresponding argument must be a pointer
           to float.

           If the fwprintf() family of functions generates  char-
           acter  string  representations for infinity and NaN (a
           7858 symbolic entity encoded in floating-point format)
           to  support  the  ANSI/IEEE Std 754:1985 standard, the
           fwscanf() family of functions will recognize  them  as
           input.

     s     Matches a sequence of non white-space wide-characters.
           If  no  l  (ell) qualifier is present, characters from
           the input field are converted as if by repeated  calls
           to the wcrtomb(3C) function, with the conversion state
           described by an mbstate_t object initialized  to  zero
           before  the  first  wide-character  is converted.  The
           corresponding argument must be a pointer to a  charac-
           ter  array large enough to accept the sequence and the
           terminating  null   character,  which  will  be  added
           automatically.

           Otherwise,  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.

     [     Matches a non-empty sequence of wide-characters from a
           set of expected wide-characters (the scanset). If no l
           (ell) qualifier is present, wide-characters  from  the
           input  field  are converted 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.   The
           corresponding  argument must be a pointer to a charac-
           ter array large enough to accept the sequence and  the
           terminating  null   character,  which  will  be  added
           automatically.

           If an l (ell) qualifier is present, the  corresponding
           argument  must  be  a   pointer to an array of wchar_t
           large enough to accept the sequence and the  terminat-
           ing null  wide-character, which will be added automat-
           ically.

           The conversion specification includes  all  subsequent
           widw characters in the format string up to and includ-
           ing the matching right square bracket (]).  The  wide-
           characters  between the square brackets (the scanlist)
           comprise the scanset, unless the wide-character  after
           the  left square bracket is a circumflex (^), in which
           case the scanset contains all wide-characters that  do
           not  appear in the scanlist between the circumflex and
           the right square bracket. If the conversion specifica-
           tion  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 conver-
           sion specification. If a  minus-sign  (-)  is  in  the
           scanlist  and is not the first wide-character, nor the
           second where the first wide-character is a ^, nor  the
           last  wide-character,  it indicates a range of charac-
           ters to be matched.

     c     Matches a sequence of wide-characters  of  the  number
           specified  by  the field width (1 if no field width is
           present in the  conversion  specification).  If  no  l
           (ell)  qualifier  is present, wide-characters from the
           input field are converted 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.  The
           corresponding argument must be a pointer to a  charac-
           ter  array  large  enough  to accept the sequence.  No
           null character is added.

           Otherwise,  the  corresponding  argument  must  be   a
           pointer  to an array of wchar_t large enough to accept
           the sequence.  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  fwprintf(3C)  functions.   The
           corresponding  argument must be a pointer to a pointer
           to void. If the input item is a value  converted  ear-
           lier  during  the  same program execution, the pointer
           that results will compare equal to that value;  other-
           wise 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 writ-
           ten the number of wide-characters read from the  input
           so far by this call to the fwscanf() functions. Execu-
           tion of a %n conversion specification does not  incre-
           ment  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 E, G, and X  are  also  valid  and
     behave the same as, respectively, e, g, and x.

     If end-of-file is encountered during  input,  conversion  is
     terminated. If end-of-file occurs before any wide-characters
     matching the current conversion  specification  (except  for
     %n)  have  been  read (other than leading white-space, where
     permitted), execution of the current  conversion  specifica-
     tion  terminates  with  an input failure.  Otherwise, unless
     execution of the current conversion  specification  is  ter-
     minated  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 swscanf() is equivalent to
     encountering end-of-file for fwscanf().

     If conversion terminates on a conflicting input, the offend-
     ing  input  is  left unread in the input. Any trailing white
     space (including newline) is left unread unless matched by a
     conversion specification. The success of literal matches and
     suppressed assignments is only directly determinable via the
     %n conversion specification.

     The fwscanf() and wscanf() 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  suc-
     cessful   execution  of  fgetc(3C),  fgetwc(3C),  fgets(3C),
     fgetws(3C),  fread(3C),  getc(3C),  getwc(3C),  getchar(3C),
     getwchar(3C),  gets(3C),  fscanf  (3C)  or  fwscanf()  using
     stream that returns data not supplied by  a  prior  call  to
     ungetc(3C).


RETURN VALUES

     Upon  successful  completion,  these  functions  return  the
     number  of  successfully  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.


ERRORS

     For the conditions under which the fwscanf() functions  will
     fail and may fail, refer to fgetwc(3C).
     In addition, fwscanf() may fail if:

     EILSEQ
           Input byte sequence does not form a valid character.

     EINVAL
           There are insufficient arguments.


USAGE

     In format  strings  containing  the  %  form  of  conversion
     specifications,  each  argument in the argument list is used
     exactly once.


EXAMPLES

     Example 1: wscanf() example

     The call:

     int i, n; float x; char name[50];
     n = wscanf(L"%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.

     The call:

     int i; float x; char name[50];
     (void) wscanf(L"%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.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     fgetc(3C),  fgets(3C),  fgetwc(3C),  fgetws(3C),  fread(3C),
     fscanf(3C),   fwprintf(3C), getc(3C), getchar(3C), gets(3C),
     getwc(3C),   getwchar(3C),    setlocale(3C),    wcrtomb(3C),
     wcstod(3C),  wcstol(3C),  wcstoul(3C),  attributes(5), stan-
     dards(5)


Man(1) output converted with man2html