*** UNIX MANUAL PAGE BROWSER ***

wscanf(3) Library Functions Manual wscanf(3) NAME wscanf, fwscanf, swscanf - Converts formatted wide-character input LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <wchar.h> int wscanf( const wchar_t *format [,pointer]...); #include <stdio.h> #include <wchar.h> int fwscanf( FILE *stream, const wchar_t *format, [,pointer]...); int swscanf( const wchar_t *wstr, const wchar_t *format, [,pointer]...); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: fwscanf(), swscanf(), wscanf(): ISO C Refer to the standards(5) reference page for more information about in- dustry 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 re- sults into specified memory locations. The format parameter contains conversion specifications used to interpret the input. The pointer pa- rameters 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 behavior is undefined. If format is exhausted while arguments remain, the ex- cess 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. Con- version 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] ig- nore leading white space and consider the first trailing white- space wide character to delimit the field. Invalid wide charac- ter If the input stream contains a wide character that is not al- lowed, 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 char- acter, 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). [Digital] 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 un- signed 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 in- dicates 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 spec- ifies 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 in- teger whose format is the same as expected for the subject se- quence 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 in- teger 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 integer pointer. Accepts a floating-point number. The next field is converted accord- ingly and stored through the corresponding parameter, which should be a pointer to a float. The input format for floating- point numbers is a string of digits, with the following optional characteristics: It can be a signed value. It can be an expo- nential value, containing a decimal point followed by an expo- nent field, which consists of an E or an e followed by an op- tionally signed integer. [Digital] It can be one of the spe- cial 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 integer, the same as the %p conversion of the wprintf() function. The corre- sponding argument will be a pointer to void. No input is con- sumed. 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 assignment count returned at the completion of this function is not incremented. Accepts a string of nonwhite-space wide characters. 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 character. A string of wchar_t val- ues is output. If a field width is given, pointer refers to a wide-character array, and the indicated number of wchar_t values is read. [Digital] 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 character appended. The in- put 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 suppressed, use %1s rather than %1c to read the next nonwhite-space wide character. [Digital] Accepts as input one or more characters in multibyte format and converts to wchar_t type (as is done by the mb- stowcs() or mbsrtowcs() function). If there is no field width or a field width of 1 in the conversion specification, the con- version 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 terminating 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 corresponding pointer parameter should be an array of wchar_t. The leading white space that is normally skipped over is suppressed. 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 follow: You can repre- sent 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 character 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 pre- ceded 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 terminating 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 control string, or when an input wide character conflicts with the control 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 di- rectly determined. The wscanf() function returns the number of success- fully matched and assigned input items. RESTRICTIONS Currently, the DIGITAL UNIX product 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 lo- cales 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 [Digital] The fwscanf() function fails if either the stream is un- buffered, or the stream's buffer needed to be flushed and the function call caused an underlying read() or lseek() to be invoked and that op- eration fails. In addition, if the any of the following conditions oc- cur, the wscanf(), fwscanf(), and swscanf(), functions set errno to the corresponding value: [Digital] The O_NONBLOCK flag is set for the un- derlying stream and the process would be delayed by the read operation. [Digital] The file descriptor underlying the stream is not a valid file descriptor or is not open for reading. [Digital] The input byte sequence does not form a valid wide character. [Digital] The read op- eration was interrupted by a signal that was caught and no data was transferred. [Digital] The call is attempting to read from the process's controlling terminal and either the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. [Digi- tal] Insufficient memory is available for the operation. RELATED INFORMATION Functions: fopen(3), getwc(3), printf(3), scanf(3), wprintf(3) Standards: standards(5) delim off wscanf(3)