| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
enable_extended_FILE_stdio(3C)
posix_spawnattr_getschedparam(3C)
posix_spawnattr_getschedpolicy(3C)
posix_spawnattr_getsigdefault(3C)
posix_spawnattr_getsigignore_np(3C)
posix_spawnattr_getsigmask(3C)
posix_spawnattr_setschedparam(3C)
posix_spawnattr_setschedpolicy(3C)
posix_spawnattr_setsigdefault(3C)
posix_spawnattr_setsigignore_np(3C)
posix_spawnattr_setsigmask(3C)
posix_spawn_file_actions_addclose(3C)
posix_spawn_file_actions_addclosefrom_np(3C)
posix_spawn_file_actions_adddup2(3C)
posix_spawn_file_actions_addopen(3C)
posix_spawn_file_actions_destroy(3C)
posix_spawn_file_actions_init(3C)
pthread_attr_getdetachstate(3C)
pthread_attr_getinheritsched(3C)
pthread_attr_getschedparam(3C)
pthread_attr_getschedpolicy(3C)
pthread_attr_setdetachstate(3C)
pthread_attr_setinheritsched(3C)
pthread_attr_setschedparam(3C)
pthread_attr_setschedpolicy(3C)
pthread_barrierattr_destroy(3C)
pthread_barrierattr_getpshared(3C)
pthread_barrierattr_setpshared(3C)
pthread_condattr_getpshared(3C)
pthread_condattr_setpshared(3C)
pthread_cond_reltimedwait_np(3C)
pthread_key_create_once_np(3C)
pthread_mutexattr_getprioceiling(3C)
pthread_mutexattr_getprotocol(3C)
pthread_mutexattr_getpshared(3C)
pthread_mutexattr_getrobust(3C)
pthread_mutexattr_setprioceiling(3C)
pthread_mutexattr_setprotocol(3C)
pthread_mutexattr_setpshared(3C)
pthread_mutexattr_setrobust(3C)
pthread_mutex_getprioceiling(3C)
pthread_mutex_reltimedlock_np(3C)
pthread_mutex_setprioceiling(3C)
pthread_rwlockattr_destroy(3C)
pthread_rwlockattr_getpshared(3C)
pthread_rwlockattr_setpshared(3C)
pthread_rwlock_reltimedrdlock_np(3C)
pthread_rwlock_reltimedwrlock_np(3C)
pthread_rwlock_timedrdlock(3C)
pthread_rwlock_timedwrlock(3C)
rctlblk_get_enforced_value(3C)
- convert formatted wide-character input
#include <stdio.h>#include <wchar.h>intfwscanf(FILE *restrictstream,const wchar_t *restrictformat,...);
intwscanf(const wchar_t *restrictformat,...);
intswscanf(const wchar_t *restricts,const wchar_t *restrictformat,...);
#include <stdarg.h>#include <stdio.h>#include <wchar.h>intvfwscanf(FILE *restrictstream,const wchar_t *restrictformat,va_listarg);
intvswcanf(const wchar_t *restrictws,const wchar_t *restrictformat,va_listarg);
intvwscanf(const wchar_t *restrictformat,va_listarg);
Thefwscanf() function reads from the named inputstream.
Thewscanf() function reads from the standard input streamstdin.
Theswscanf() function reads from the wide-character strings.
Thevfwscanf(),vswscanf(), andvwscanf() functions are equivalent to thefwscanf(),swscanf(),andwscanf() functions, respectively, except that instead of being called with a variablenumber of arguments, they are called with an argument list as definedby the <stdarg.h> header . These functions do not invoke theva_end()macro. Applications using these functions should callva_end(ap) afterwards to clean up.
Each function reads wide-characters, interprets them according to a format, and storesthe results in its arguments. Each expects, as arguments, a control wide-characterstringformat described below, and a set ofpointer arguments indicating where theconverted input should be stored. The result is undefined if there areinsufficient arguments for the format. If the format is exhausted while argumentsremain, the excess arguments are evaluated but are otherwise ignored.
Conversions can be applied to thenth argument after theformat inthe argument list, rather than to the next unused argument. In thiscase, the conversion wide-character% (see below) is replaced by the sequence%n$, wheren is a decimal integer in the range [1,NL_ARGMAX].This feature provides for the definition of format wide-character strings that selectarguments in an order appropriate to specific languages. In format wide-character strings containingthe%n$ form of conversion specifications, it is unspecified whether numbered argumentsin the argument list can be referenced from the format wide-characterstring more than once.
Theformat can contain either form of a conversion specification, that is,% or%n$, but the two forms cannot normally be mixed withina singleformat wide-character string. The only exception to this is that%%or%* can be mixed with the%n$ form.
Thefwscanf() function in all its forms allows for detection of alanguage-dependent radix character in the input string, encoded as a wide-character value. The radix character is defined in the program's locale (categoryLC_NUMERIC). In the POSIX locale, or in a locale where the radix characteris 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 morewhite-space wide-characters (space, tab, newline, vertical-tab or form-feed characters); an ordinarywide-character (neither% nor a white-space character); or a conversion specification. Each conversionspecification is introduced by a% or the sequence%n$ after whichthe following appear in sequence:
An optional assignment-suppressing character*.
An optional non-zero decimal integer that specifies the maximum field width.
An option length modifier that specifies the size of the receiving object.
A conversion specifier wide-character that specifies the type of conversion to be applied. The valid conversion wide-characters are described below.
Thefwscanf() functions execute each directive of the format in turn. If a directive fails, as detailed below, the function returns. Failuresare 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 byreading input until no more valid input can be read, or upto the first wide-character which is not a white-space wide-character, whichremains unread.
A directive that is an ordinary wide-character is executed as follows. Thenext wide-character is read from the input and compared with the wide-characterthat comprises the directive; if the comparison shows that they are notequivalent, the directive fails, and the differing and subsequent wide-characters remain unread.
A directive that is a conversion specification defines a set of matchinginput sequences, as described below for each conversion wide-character. A conversionspecification is executed in the following steps:
Input white-space wide-characters (as specified byiswspace(3C)) are skipped, unless the conversionspecification includes a[,c, orn conversion character.
An item is read from the input unless the conversion specification includesann conversion wide-character. The length of the item read is limitedto any specified maximum field width. In Solaris default mode, the inputitem is defined as the longest sequence of input wide-characters that forms amatching sequence. In some cases,fwscanf() might need to read several extrawide-characters beyond the end of the input item to find the endof a matching sequence. In C99/SUSv3 mode, the input item is definedas the longest sequence of input wide-characters that is, or is a prefixof, a matching sequence. With this definition,fwscanf() need only read atmost one wide-character beyond the end of the input item. Therefore, inC99/SUSv3 mode, some sequences that are acceptable towcstod(3C),wcstol(3C), and similarfunctions are unacceptable tofwscanf(). In either mode,fwscanf() attempts to push backany excess bytes read usingungetc(3C). Assuming all such attempts succeed, thefirst wide-character, if any, after the input item remains unread. If the lengthof the input item is 0, the conversion fails. This condition isa matching failure unless end-of-file, an encoding error, or a read errorprevented input from the stream, in which case it is an inputfailure.
Except in the case of a% conversion wide-character, the input item(or, in the case of a%n conversion specification, the count ofinput 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 theconversion specification fails; this condition is a matching failure. Unless assignment suppressionwas indicated by a*, the result of the conversion is placedin the object pointed to by the first argument following theformat argumentthat has not already received a conversion result if the conversion specificationis introduced by%, or in thenth argument if introduced bythe wide-character sequence%n$. If this object does not have an appropriatetype, or if the result of the conversion cannot be represented inthe space provided, the behavior is undefined.
The length modifiers and their meanings are:
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tosigned char orunsigned char.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer toshort orunsigned short.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tolong orunsigned long; that a followinga,A,e,E,f,F,g, orG conversion specifier applies to an argument with type pointer todouble; or that a followingc,s, or[ conversion specifier applies to an argument with type pointer towchar_t.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tolong long orunsigned long long.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tointmax_t oruintmax_t.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer tosize_t or the corresponding signed integer type.
Specifies that a followingd,i,o,u,x,X, orn conversion specifier applies to an argument with type pointer toptrdiff_t or the correspondingunsigned type.
Specifies that a followinga,A,e,E,f,F,g, orG conversion specifier applies to an argument with type pointer tolong double.
If a length modifier appears with any conversion specifier other than asspecified above, the behavior is undefined.
The following conversion wide-characters are valid:
Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence ofwcstol(3C) with the value 10 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer toint.
Matches an optionally signed integer, whose format is the same as expected for the subject sequence ofwcstol(3C) with 0 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer toint.
Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence ofwcstoul(3C) with the value 8 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence ofwcstoul(3C) with the value 10 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence ofwcstoul(3C) with the value 16 for thebase argument. In the absence of a size modifier, the corresponding argument must be a pointer tounsigned int.
Matches an optionally signed floating-point number, whose format is the same as expected for the subject sequence ofwcstod(3C). In the absence of a size modifier, the corresponding argument must be a pointer tofloat. Thee,f, andg specifiers match hexadecimal floating point values only in C99/SUSv3 (seestandards(5)) mode, but thea specifier always matches hexadecimal floating point values.
These conversion specifiers match any subject sequence accepted bystrtod(3C), including the INF, INFINITY, NAN, and NAN(n-char-sequence) forms. The result of the conversion is the same as that of callingstrtod() (orstrtof() orstrtold()) with the matching sequence, including the raising of floating point exceptions and the setting oferrno toERANGE, if applicable.
Matches a sequence of non white-space wide-characters. If nol (ell) qualifier is present, characters from the input field are converted as if by repeated calls to thewcrtomb(3C) function, with the conversion state described by anmbstate_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 ofwchar_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 (thescanset). If nol (ell) qualifier is present, wide-characters from the input field are converted as if by repeated calls to thewcrtomb() function, with the conversion state described by anmbstate_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.
If anl (ell) qualifier is present, the corresponding argument must be a pointer to an array ofwchar_t large enough to accept the sequence and the terminating null wide-character, which will be added automatically.
The conversion specification includes all subsequent widw characters in theformat string up to and including the matching right square bracket (]). The wide-characters between the square brackets (thescanlist) 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 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 indicates a range of characters to be matched.
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 nol (ell) qualifier is present, wide-characters from the input field are converted as if by repeated calls to thewcrtomb() function, with the conversion state described by anmbstate_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. No null character is added.
Otherwise, the corresponding argument must be a pointer to an array ofwchar_t large enough to accept the sequence. No null wide-character is added.
Matches the set of sequences that is the same as the set of sequences that is produced by the%p conversion of the correspondingfwprintf(3C) functions. The corresponding argument must be a pointer to a pointer tovoid. 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.
No input is consumed. The corresponding argument must be a pointer to the integer into which is to be written the number of wide-characters read from the input so far by this call to thefwscanf() functions. Execution of a%n conversion specification does not increment the assignment count returned at the completion of execution of the function.
Same aslc.
Same asls.
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 charactersA,E,F,G, andX are also validand behave the same as, respectively,a,e,f,g, andx.
If end-of-file is encountered during input, conversion is terminated. If end-of-file occursbefore any wide-characters matching the current conversion specification (except for%n) havebeen read (other than leading white-space, where permitted), execution of the current conversionspecification terminates with an input failure. Otherwise, unless execution of thecurrent conversion specification is terminated with a matching failure, execution of thefollowing conversion specification (if any) is terminated with an input failure.
Reaching the end of the string inswscanf() is equivalent to encounteringend-of-file forfwscanf().
If conversion terminates on a conflicting input, the offending input is leftunread in the input. Any trailing white space (including newline) is leftunread unless matched by a conversion specification. The success of literal matchesand suppressed assignments is only directly determinable via the %n conversion specification.
Thefwscanf() andwscanf() functions may mark thest_atime field of thefile associated withstream for update. Thest_atime field will be markedfor update by the first successful execution offgetc(3C),fgetwc(3C),fgets(3C),fgetws(3C),fread(3C),getc(3C),getwc(3C),getchar(3C),getwchar(3C),gets(3C),fscanf(3C) orfwscanf() usingstream that returnsdata not supplied by a prior call toungetc(3C).
Upon successful completion, these functions return the number of successfully matched andassigned input items; this number can be 0 in the event ofan early matching failure. If the input ends before the firstmatching failure or conversion, EOF is returned. If a read error occursthe error indicator for the stream is set, EOF is returned, anderrno is set to indicate the error.
For the conditions under which thefwscanf() functions will fail and mayfail, refer tofgetwc(3C).
In addition,fwscanf() may fail if:
Input byte sequence does not form a valid character.
There are insufficient arguments.
In format strings containing the% form of conversion specifications, each argumentin the argument list is used exactly once.
Example 1wscanf() 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 ton the value 3, toi the value 25,tox the value 5.432, andname 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 toi, 789.0 tox, skip 0123, and placethe string 56\0 inname. The next call togetchar(3C) will returnthe charactera.
Seeattributes(5) for descriptions of the following attributes:
|
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)
The behavior of the conversion specifier “%%” has changed for all ofthe functions described on this manual page. Previously the “%%” specifier accepteda “%” character from input only if there were no preceding whitespacecharacters. The new behavior accepts “%” even if there are preceding whitespacecharacters. This new behavior now aligns with the description on this manualpage and in various standards. If the old behavior is desired, theconversion specification “%*[%]” can be used.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |