fwscanf man page on SmartOS

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

FWSCANF(3C)							   FWSCANF(3C)

NAME
       fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf - convert format‐
       ted wide-character input

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

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

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

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

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

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

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

       int vwscanf(const wchar_t *restrict 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(), vswscanf(), and vwscanf() functions are	equivalent  to
       the  fwscanf(), swscanf(), and wscanf() functions, 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 .
       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 according to a
       format, and stores the results in its arguments. Each expects, as argu‐
       ments,  a  control  wide-character string format described below, and a
       set of pointer arguments indicating 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 specification,  that
       is,  % or %n$, but the two forms cannot normally be mixed within a sin‐
       gle 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 lan‐
       guage-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	direc‐
       tives.  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 character); or a conversion specification. Each  conversion
       specification  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 max‐
		  imum field width.

	   o	  An  option  length  modifier	that specifies the size of the
		  receiving object.

	   o	  A conversion specifier  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 function returns.	 Fail‐
       ures 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 exe‐
       cuted 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 subsequent wide-characters remain unread.

       A directive that is a conversion specification defines a set of	match‐
       ing input sequences, as described below for each conversion  wide-char‐
       acter. A conversion specification is executed in the following steps:

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

       An item is read from the	 input	unless	the  conversion	 specification
       includes an n conversion wide-character. The length of the item read is
       limited to any specified maximum field width. In Solaris default	 mode,
       the input item is defined as the longest sequence of input wide-charac‐
       ters that forms a matching sequence. In	some  cases,  fwscanf()	 might
       need  to read several extra wide-characters beyond the end of the input
       item to find the end of a matching sequence.  In	 C99/SUSv3  mode,  the
       input  item is defined as the longest sequence of input wide-characters
       that is, or is a prefix of, a matching sequence. With this  definition,
       fwscanf()  need	only read at most one wide-character beyond the end of
       the input item. Therefore, in C99/SUSv3 mode, some sequences  that  are
       acceptable  to  wcstod(3C), wcstol(3C), and similar functions are unac‐
       ceptable to fwscanf(). In either mode, fwscanf() attempts to push  back
       any excess bytes read using ungetc(3C). Assuming all such attempts suc‐
       ceed, the first wide-character, if any, after the  input	 item  remains
       unread.	If  the	 length	 of the input item is 0, the conversion 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 specification, 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 exe‐
       cution 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 conversion specification is	intro‐
       duced  by %, or in the nth argument 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 pro‐
       vided, the behavior is undefined.

       The length modifiers and their meanings are:

       hh
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to signed char or unsigned char.

       h
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to short or unsigned short.

       l (ell)
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to long or unsigned long; that a	 following  a,
		       A,  e, E, f, F, g, or G conversion specifier applies to
		       an argument with type pointer to double; or that a fol‐
		       lowing  c,  s,  or [ conversion specifier applies to an
		       argument with type pointer to wchar_t.

       ll (ell-ell)
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to long long or unsigned long long.

       j
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to intmax_t or uintmax_t.

       z
		       Specifies that a following d, i, o, u, x, X, or n  con‐
		       version	specifier  applies  to	an  argument with type
		       pointer to size_t or the corresponding  signed  integer
		       type.

       t
		       Specifies  that a following d, i, o, u, x, X, or n con‐
		       version specifier applies  to  an  argument  with  type
		       pointer	to  ptrdiff_t  or  the	corresponding unsigned
		       type.

       L
		       Specifies that a following a, A, e, E, f, F,  g,	 or  G
		       conversion  specifier  applies to an argument with type
		       pointer to long double.

       If a length modifier appears with any conversion specifier  other  than
       as specified above, 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 format  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 for‐
		  mat  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.

       a,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	corre‐
		  sponding  argument must be a pointer to float. The e, f, and
		  g specifiers match hexadecimal floating point values only in
		  C99/SUSv3  (see  standards(5))  mode,	 but  the  a specifier
		  always matches hexadecimal floating point values.

		  These	 conversion  specifiers	 match	any  subject  sequence
		  accepted  by	strtod(3C),  including the INF, INFINITY, NAN,
		  and NAN(n-char-sequence) forms.  The result of  the  conver‐
		  sion is the same as that of calling strtod() (or strtof() or
		  strtold()) with the matching sequence, including the raising
		  of  floating	point  exceptions  and the setting of errno to
		  ERANGE, if applicable.

       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  wcr‐
		  tomb(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 character 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() func‐
		  tion,	 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 character array large enough to accept the sequence and
		  the  terminating  null  character, which will be added auto‐
		  matically.

		  If an l (ell) qualifier is present, the corresponding	 argu‐
		  ment	must  be a pointer to an array of wchar_t large enough
		  to accept the sequence and the terminating null   wide-char‐
		  acter, which will be added automatically.

		  The  conversion  specification  includes all subsequent widw
		  characters in the format string  up  to  and	including  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  con‐
		  tains all wide-characters that do not appear in the scanlist
		  between the circumflex and the right square bracket. If  the
		  conversion  specification  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 conversion
		  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 indi‐
		  cates a range of characters to be matched.

       c
		  Matches  a  sequence of wide-characters of the number speci‐
		  fied 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  initial‐
		  ized	to  zero before the first wide-character is converted.
		  The corresponding argument must be a pointer to a  character
		  array	 large enough to accept the sequence.  No null charac‐
		  ter 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 cor‐
		  responding fwprintf(3C) functions. The  corresponding	 argu‐
		  ment	must  be  a pointer to a pointer to void. If the input
		  item is a value converted earlier during  the	 same  program
		  execution,  the  pointer  that results will compare equal to
		  that value; otherwise 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 written the  num‐
		  ber  of  wide-characters  read from the input so far by this
		  call to the fwscanf() functions. Execution of a  %n  conver‐
		  sion	specification  does not increment 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 A, E, F, G, and X are also valid and behave
       the same as, respectively, a, e, f, 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 conver‐
       sion specification terminates with an input failure.  Otherwise, unless
       execution  of the current conversion specification is terminated 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 encounter‐
       ing end-of-file for fwscanf().

       If conversion terminates on a conflicting input, the offending input is
       left  unread in the input. Any trailing white space (including newline)
       is left unread unless matched by a conversion specification.  The  suc‐
       cess  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	 successful  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 suc‐
       cessfully 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 attributes:

       ┌────────────────────┬───────────────────┐
       │  ATTRIBUTE TYPE    │  ATTRIBUTE VALUE	│
       ├────────────────────┼───────────────────┤
       │Interface Stability │ Committed		│
       ├────────────────────┼───────────────────┤
       │MT-Level	    │ MT-Safe		│
       ├────────────────────┼───────────────────┤
       │Standard	    │ See standards(5). │
       └────────────────────┴───────────────────┘

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),	strtod(3C),   wcrtomb(3C),   wcstod(3C),   wcstol(3C),
       wcstoul(3C), attributes(5), standards(5)

NOTES
       The  behavior  of  the conversion specifier "%%" has changed for all of
       the functions described on this manual page. Previously the "%%" speci‐
       fier  accepted a "%" character from input only if there were no preced‐
       ing whitespace characters.  The new behavior accepts "%" even if	 there
       are  preceding whitespace characters. This new behavior now aligns with
       the description on this manual page and in various  standards.  If  the
       old  behavior  is  desired, the conversion specification "%*[%]" can be
       used.

				 Jul 10, 2008			   FWSCANF(3C)
[top]

List of man pages available for SmartOS

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