vswscanf_s(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

vswscanf_s(3c)

Standard C Library Functions                                       fwscanf(3C)



NAME
       fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf - convert format‐
       ted wide-character input
       fwscanf_s, wscanf_s, swscanf_s,  vfwscanf_s,  vwscanf_s,  vswscanf_s  -
       convert formatted wide-character input with additional safety checks

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);


       #define __STDC_WANT_LIB_EXT1__ 1
       #include <stdio.h>
       #include <wchar.h>

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


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


       #define __STDC_WANT_LIB_EXT1__ 1
       #include <stdarg.h>
       #include <wchar.h>

       int vswscanf_s(const wchar_t *restrict s, const wchar_t *restrict format,
           va_list arg);


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


       #define __STDC_WANT_LIB_EXT1__ 1
       #include <wchar.h>

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


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

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 similar 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) afterward 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 speci‐
       fication is introduced by a % or the sequence %n$ after which the  fol‐
       lowing 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. 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 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(7))  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 conversion
                  is the same as that of calling strtod() (or strtof() or str‐
                  told()) 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 automat‐
                  ically.

                  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-charac‐
                  ter, which will be added automatically.

                  The conversion specification includes  all  subsequent  wide
                  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 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  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).

   C11 Bounds Checking Interfaces
       The fwscanf_s(), wscanf_s(),  swscanf_s(),  vwscanf_s(),  vfwscanf_s(),
       and  vswscanf_s()  functions are part of the C11 bounds checking inter‐
       faces specified in the C11 standard, Annex K. They are similar to their
       respective  non-bounds  checking interfaces, except for providing addi‐
       tional checks on the parameters passed and explicit runtime-constraints
       as  defined in the C11 standard. See runtime_constraint_handler(3C) and
       INCITS/ISO/IEC 9899:2011.

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, or in the case of the bounds checking
       interfaces,  a  runtime-constraint  violation  is  detected,   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(7) for descriptions of the following attributes:


       tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE  TYPEAT‐
       TRIBUTE  VALUE  _  Interface  StabilityCommitted  _ MT-LevelSee below _
       StandardSee standards(7).



       The fwscanf(), wscanf(), swscanf(), vfwscanf(),  vwscanf(),  and  vsws‐
       canf() functions can be used safely in multithreaded applications.


       The  fwscanf_s(),  wscanf_s(),  swscanf_s(), vfwscanf_s(), vwscanf_s(),
       and vswscanf_s() functions cannot be used  safely  in  a  multithreaded
       application  due  to  the runtime constraint handler. For more informa‐
       tion, see the runtime_constraint_handler(3C) man page.

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(7),   standards(7),   runtime_constraint_han‐
       dler(3C)

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.



Oracle Solaris 11.4               11 May 2021                      fwscanf(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3