From kido@vnet.IBM.COM Mon Mar 15 03:04:06 1993 Received: from vnet.IBM.COM ([192.239.48.4]) by dkuug.dk with SMTP id AA29824 (5.65c8/IDA-1.4.4j for ); Mon, 15 Mar 1993 03:04:06 +0100 Message-Id: <199303150204.AA29824@dkuug.dk> Received: from YMTVM8 by vnet.IBM.COM (IBM VM SMTP V2R2) with BSMTP id 4025; Sun, 14 Mar 93 21:03:24 EST Date: Mon, 15 Mar 93 11:02:06 JST From: "Akio Kido" To: sc22wg15@dkuug.dk, sc22wg20@dkuug.dk, XoJIG@xopen.co.uk, sig-international@osf.org, uojlg-bse@uiap.ui.org, efischer@donald.aix.kingston.ibm.com Subject: MSE 4.5.3.4.mm X-Charset: ASCII X-Char-Esc: 29 .SK .H 4 "Formatted wide character input/output functions" .H 5 "The \*(Cwfwprintf\fP function" .HU Synopsis .Cb #include #include int fwprintf(FILE *stream, const wchar_t *format, ...); .Ce .HU Description .P The .Cf fwprintf function writes output to the stream pointed to by .Cf stream , under control of the wide string pointed to by .Cf format that specifies how subsequent arguments are converted for output. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored. The .Cf fwprintf function returns when the end of the format string is encountered. .P Note that all wide characters in the format string that are described as special in the following description (such as white space and .Cf % ) are members of the basic character set. .P The format is composed of zero or more directives: ordinary wide characters (not .Cf % ), which are converted to multibyte characters and written to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the wide character .Cf % . After the .Cf % , the following appear in sequence: .DL .LI Zero or more .I flags (in any order) that modify the meaning of the conversion specification. .LI An optional minimum .IR "field width" . If the converted value has fewer wide characters than the field width, it shall be padded with spaces (by default) on the left (or right, if the left adjustment flag, described later, has been given) to the field width. The field width takes the form of an asterisk .Cf * (described later) or a decimal integer.\*F .FS Note that .Cf 0 is taken as a flag, not as the beginning of a field width. .FE .LI An optional .I precision that gives the minimum number of digits to appear for the .Cf d , .Cf i , .Cf o , .Cf u , .Cf x , and .Cf X conversions, the number of digits to appear after the decimal-point character for .Cf e , .Cf E , and .Cf f conversions, the maximum number of significant digits for the .Cf g and .Cf G conversions, or the maximum number of wide characters to be written from a string in .Cf s conversion. The precision takes the form of a period .Cs ( .\& ) followed either by an asterisk .Cf * (described later) or by an optional decimal integer; if only the period is specified, the precision is taken as zero. If a precision appears with any other conversion specifier, the behavior is undefined. .LI An optional .Cf h specifying that a following .Cf d , .Cf i , .Cf o , .Cf u , .Cf x , or .Cf X conversion specifier applies to a .Cf short .Cf int or .Cf unsigned .Cf short .Cf int argument (the argument shall have been promoted according to the integral promotions, and its value shall be converted to .Cf short .Cf int or .Cf unsigned .Cf short .Cf int before printing); an optional .Cf h specifying that a following .Cf n conversion specifier applies to a pointer to a .Cf short .Cf int argument; an optional .Cf l (ell) specifying that a following .Cf d , .Cf i , .Cf o , .Cf u , .Cf x , or .Cf X conversion specifier applies to a .Cf long .Cf int or .Cf unsigned .Cf long .Cf int argument; an optional .Cf l specifying that a following .Cf n conversion specifier applies to a pointer to a .Cf long .Cf int argument; or an optional .Cf L specifying that a following .Cf e , .Cf E , .Cf f , .Cf g , or .Cf G conversion specifier applies to a .Cf long .Cf double argument. If an .Cf h , .Cf l , or .Cf L appears with any other conversion specifier, the behavior is undefined. .LI A wide character that specifies the type of conversion to be applied. .LE .P As noted above, a field width, or precision, or both, may be indicated by an asterisk. In this case, an .Cf int argument supplies the field width or precision. The arguments specifying field width, or precision, or both, shall appear (in that order) before the argument (if any) to be converted. A negative field width argument is taken as a .Cf - flag followed by a positive field width. A negative precision argument is taken as if the precision were omitted. .P The flag wide characters and their meanings are .VL \w'\fIspace\fRm'u .LI \*(Cw-\fR The result of the conversion shall be left-justified within the field. (It shall be right-justified if this flag is not specified.) .LI \*(Cw+\fR The result of a signed conversion shall always begin with a plus or minus sign. (It shall begin with a sign only when a negative value is converted if this flag is not specified.) .LI \fIspace\fR If the first wide character of a signed conversion is not a sign, or if a signed conversion results in no wide characters, a space shall be prefixed to the result. If the .I space and .Cf + flags both appear, the .I space flag shall be ignored. .LI \*(Cw#\fR The result is to be converted to an ``alternate form.'' For .Cf o conversion, it increases the precision to force the first digit of the result to be a zero, if necessary. For .Cf x (or .Cf X ) conversion, a nonzero result shall have .Cf 0x (or .Cf 0X ) prefixed to it. For .Cf e , .Cf E , .Cf f , .Cf g , and .Cf G conversions, the result shall always contain a decimal-point wide character, even if no digits follow it. (Normally, a decimal-point character appears in the result of these conversions only if a digit follows it.) For .Cf g and .Cf G conversions, trailing zeros shall .I not be removed from the result. For other conversions, the behavior is undefined. .LI \*(Cw0\fR For .Cf d , .Cf i , .Cf o , .Cf u , .Cf x , .Cf X , .Cf e , .Cf E , .Cf f , .Cf g , and .Cf G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed. If the .Cf 0 and .Cf - flags both appear, the .Cf 0 flag shall be ignored. For .Cf d , .Cf i , .Cf o , .Cf u , .Cf x , and .Cf X conversions, if a precision is specified, the .Cf 0 flag shall be ignored. For other conversions, the behavior is undefined. .LE .P The conversion specifiers and their meanings are .P .VL \w'\*(Cwo,u,x,Xm'u .LI \*(Cwd,i\fR The .Cf int argument is converted to signed decimal in the style .IR [\-]dddd . The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it shall be expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is no wide characters. .LI \*(Cwo,u,x,X\fR The .Cf unsigned .Cf int argument is converted to unsigned octal .Cs ( o ), unsigned decimal .Cs ( u ), or unsigned hexadecimal notation .Cs ( x or .Cf X ) in the style .IR dddd ; the letters .Cf abcdef are used for .Cf x conversion and the letters .Cf ABCDEF for .Cf X conversion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it shall be expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is no wide characters. .LI \*(Cwf\fR The .Cf double argument is converted to decimal notation in the style .IR [\-]ddd.ddd , where the number of digits after the decimal-point wide character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is zero and the .Cf # flag is not specified, no decimal-point wide character appears. If a decimal-point wide character appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. .LI \*(Cwe,E\fR The .Cf double argument is converted in the style .IR [\-]d.ddd\*(Cwe\fI\(+-dd , where there is one digit before the decimal-point wide character (which is nonzero if the argument is nonzero) and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero and the .Cf # flag is not specified, no decimal-point wide character appears. The value is rounded to the appropriate number of digits. The .Cf E conversion specifier shall produce a number with .Cf E instead of .Cf e introducing the exponent. The exponent always contains at least two digits. If the value is zero, the exponent is zero. .LI \*(Cwg,G\fR The .Cf double argument is converted in style .Cf f or .Cf e (or in style .Cf E in the case of a .Cf G conversion specifier), with the precision specifying the number of significant digits. If the precision is zero, it is taken as 1. The style used depends on the value converted; style .Cf e (or .Cf E ) shall be used only if the exponent resulting from such a conversion is less than \-4 or greater than or equal to the precision. Trailing zeros are removed from the fractional portion of the result; a decimal-point wide character appears only if it is followed by a digit. .LI \*(Cwc\fR The .Cf wchar_t argument is converted to a multibyte character and written. .LI \*(Cws\fR The argument shall be a pointer to the initial element of an array of .Cf wchar_t type. Wide characters from the array are converted to multibyte characters and written up to (but not including) a terminating null wide character; if the precision is specified, no more than that many wide characters are converted and written. If the precision is not specified or is greater than the size of the array, the array shall contain a null wide character. .LI \*(Cwp\fR The argument shall be a pointer to .Cf void . The value of the pointer is converted to a sequence of printable wide characters, in an implementation-defined manner. .LI \*(Cwn\fR The argument shall be a pointer to an integer into which is .I written the number of wide characters written to the output stream so far by this call to .Cf fwprintf . No argument is converted. .LI \*(Cw%\fR A .Cf % is written. No argument is converted. The complete conversion specification shall be .Cf %% . .LE .P If a conversion specification is invalid, the behavior is undefined.\*F .FS See ``future library directions'' (4.6.1). .FE .P If any argument is, or points to, a union or an aggregate (except for an array of .Cf wchar_t type using .Cf %s conversion, or a pointer using .Cf %p conversion), the behavior is undefined. .P In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .HU Returns .P The .Cf fwprintf function returns the number of wide characters transmitted, or a negative value if an output error occurred. .HU "Environmental limit" .P The minimum value for the maximum number of bytes produced by any single conversion shall be 509. .HU Example .P To print a date and time in the form ``Sunday, July 3, 10:02'' followed by \*(pi to five decimal places: .Cb #include #include #include /*...*/ wchar_t *weekday, *month; /* \fIpointers to wide strings\fP */ int day, hour, min; fwprintf(stdout, L"%s, %s %d, %.2d:%.2d\en", weekday, month, day, hour, min); fwprintf(stdout, L"pi = %.5f\en", 4 * atan(1.0)); .Ce .H 5 "The \*(Cwfwscanf\fP function" .HU Synopsis .Cb #include #include int fwscanf(FILE *stream, const wchar_t *format, ...); .Ce .HU Description .P The .Cf fwscanf function reads input from the stream pointed to by .Cf stream , under control of the wide string pointed to by .Cf format that specifies the admissible input sequences and how they are to be converted for assignment, using subsequent arguments as pointers to the objects to receive the converted input. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored. .P Note that all wide characters in the format string that are described as special in the following description (such as white space and .Cf % ) are members of the basic character set. .P The format is composed of zero or more directives: one or more white-space wide characters; an ordinary wide character (neither .Cf % nor a white-space wide character); or a conversion specification. Each conversion specification is introduced by a .Cf % . After the .Cf % , the following appear in sequence: .DL .LI An optional assignment-suppressing wide character .Cf * . .LI An optional nonzero decimal integer that specifies the maximum field width. .LI An optional .Cf h , .Cf l (ell) or .Cf L indicating the size of the receiving object. The conversion specifiers .Cf d , .Cf i , and .Cf n shall be preceded by .Cf h if the corresponding argument is a pointer to .Cf short .Cf int rather than a pointer to .Cf int , or by .Cf l if it is a pointer to .Cf long .Cf int . Similarly, the conversion specifiers .Cf o , .Cf u , and .Cf x shall be preceded by .Cf h if the corresponding argument is a pointer to .Cf unsigned .Cf short .Cf int rather than a pointer to .Cf unsigned .Cf int , or by .Cf l if it is a pointer to .Cf unsigned .Cf long .Cf int . Finally, the conversion specifiers .Cf e , .Cf f , and .Cf g shall be preceded by .Cf l if the corresponding argument is a pointer to .Cf double rather than a pointer to .Cf float , or by .Cf L if it is a pointer to .Cf long .Cf double . If an .Cf h , .Cf l , or .Cf L appears with any other conversion specifier, the behavior is undefined. .LI A wide character that specifies the type of conversion to be applied. The valid conversion specifiers are described below. .LE .P The .Cf fwscanf function executes each directive of the format in turn. If a directive fails, as detailed below, the .Cf fwscanf function returns. Failures are described as input failures (if an encoding error occurs or due to the unavailability of input characters), or matching failures (due to inappropriate input). .P A directive composed of white-space wide character(s) is executed by reading input up to the first non-white-space wide character (which remains unread), or until no more wide characters can be read. .P A directive that is an ordinary wide character is executed by reading the next wide character of the stream. If the wide character differs from the directive, the directive fails, and the differing and subsequent wide characters remain unread. .P A directive that is a conversion specification defines a set of matching input sequences, as described below for each specifier. A conversion specification is executed in the following steps: .P Input white-space wide characters (as specified by the .Cf iswspace function) are skipped, unless the specification includes a .Cf c , or .Cf n specifier.\*F .FS These white-space wide characters are not counted against a specified field width. .FE .P An input item is read from the stream, unless the specification includes an .Cf n specifier. An input item is defined as the longest matching sequence of input wide characters, unless that exceeds a specified field width, in which case it is the initial subsequence of that length in the sequence. The first wide character, if any, after the input item remains unread. If the length of the input item is zero, the execution of the directive fails: this condition is a matching failure, unless an error prevented input from the stream, in which case it is an input failure. .P Except in the case of a .Cf % specifier, the input item (or, in the case of a .Cf %n directive, the count of input wide characters) is converted to a type appropriate to the conversion specifier. If the input item is not a matching sequence, the execution of the directive fails: this condition is a matching failure. Unless assignment suppression was indicated by a .Cf * , the result of the conversion is placed in the object pointed to by the first argument following the .Cf format argument that has not already received a conversion result. 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. .P The following conversion specifiers are valid: .P .VL \w'\*(Cwe,f,gm'u .LI \*(Cwd\fR Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the .Cf wcstol function with the value 10 for the .Cf base argument. The corresponding argument shall be a pointer to integer. .LI \*(Cwi\fR Matches an optionally signed integer, whose format is the same as expected for the subject sequence of the .Cf wcstol function with the value 0 for the .Cf base argument. The corresponding argument shall be a pointer to integer. .LI \*(Cwo\fR Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence of the .Cf wcstoul function with the value 8 for the .Cf base argument. The corresponding argument shall be a pointer to unsigned integer. .LI \*(Cwu\fR Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the .Cf wcstoul function with the value 10 for the .Cf base argument. The corresponding argument shall be a pointer to unsigned integer. .LI \*(Cwx\fR Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence of the .Cf wcstoul function with the value 16 for the .Cf base argument. The corresponding argument shall be a pointer to unsigned integer. .LI \*(Cwe,f,g\fR Matches an optionally signed floating-point number, whose format is the same as expected for the subject sequence of the .Cf wcstod function. The corresponding argument shall be a pointer to floating. .LI \*(Cws\fR Matches a sequence of non-white-space wide characters. The corresponding argument shall be a pointer to the initial element of an array of .Cf wchar_t type large enough to accept the sequence and a terminating null wide character, which shall be added automatically. .LI \*(Cwc\fR Matches a sequence of wide characters of the number specified by the field width (1 if no field width is present in the directive). The corresponding argument shall be a pointer to the initial element of an array of .Cf wchar_t type large enough to accept the sequence. No null wide character is added. .LI \*(Cwp\fR Matches an implementation-defined set of sequences, which should be the same as the set of sequences that may be produced by the .Cf %p conversion of the .Cf fwprintf function. The corresponding argument shall be a pointer to a pointer to .Cf void . The interpretation of the input item is implementation-defined. If the input item is a value converted earlier during the same program execution, the pointer that results shall compare equal to that value; otherwise the behavior of the .Cf %p conversion is undefined. .LI \*(Cwn\fR No input is consumed. The corresponding argument shall be a pointer to integer into which is to be written the number of wide characters read from the input stream so far by this call to the .Cf fwscanf function. Execution of a .Cf %n directive does not increment the assignment count returned at the completion of execution of the .Cf fwscanf function. .LI \*(Cw%\fR Matches a single .Cf % ; no conversion or assignment occurs. The complete conversion specification shall be .Cf %% . .LE .P If a conversion specification is invalid, the behavior is undefined.\*F .FS See ``future library directions'' (4.6.1). .FE .P The conversion specifiers .Cf E , .Cf G , and .Cf X are also valid and behave the same as, respectively, .Cf e , .Cf g , and .Cf x . .P If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any wide characters matching the current directive have been read (other than leading white space, where permitted), execution of the current directive terminates with an input failure; otherwise, unless execution of the current directive is terminated with a matching failure, execution of the following directive (other than .Cf %n , if any) is terminated with an input failure. .P If conversion terminates on a conflicting input wide character, the offending input wide character is left unread in the input stream. Trailing white space (including new-line wide characters) is left unread unless matched by a directive. The success of literal matches and suppressed assignments is not directly determinable other than via the .Cf %n directive. .HU Returns .P The .Cf fwscanf function returns the value of the macro .Cf EOF if an input failure occurs before any conversion. Otherwise, the .Cf fwscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure. .HU Examples .AL 1 .LI The call: .Cb #include #include /*...*/ int n, i; float x; wchar_t name[50]; n = fwscanf(stdin, L"%d%f%s", &i, &x, name); .Ce with the input line: .Cb 25 54.32E-1 thompson .Ce will assign to .I n the value .Cf 3 , to .I i the value .Cf 25 , to .I x the value .Cf 5.432 , and .I name will contain .Cf thompson\e0 . .LI The call: .Cb #include #include /*...*/ int i; float x; double y; fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y); .Ce with input: .Cb 56789 0123 56a72 .Ce will assign to .I i the value .Cf 56 and to .I x the value .Cf 789.0 , will skip past .Cf 0123 , and will assign to .I y the value .Cf 56.0 . The next wide character read from the input stream will be .Cf a . .LE .rF the .Cf wcstod function (4.5.4.1.1), the .Cf wcstol function (4.5.4.1.2), the .Cf wcstoul function (4.5.4.1.3). .H 5 "The \*(Cwwprintf\fP function" .HU Synopsis .Cb #include int wprintf(const wchar_t *format, ...); .Ce .HU Description .P The .Cf wprintf function is equivalent to .Cf fwprintf with the argument .Cf stdout interposed before the arguments to .Cf wprintf . .HU Returns .P The .Cf wprintf function returns the number of wide characters transmitted, or a negative value if an output error occurred. .H 5 "The \*(Cwwscanf\fP function" .HU Synopsis .Cb #include int wscanf(const wchar_t *format, ...); .Ce .HU Description .P The .Cf wscanf function is equivalent to .Cf fwscanf with the argument .Cf stdin interposed before the arguments to .Cf wscanf . .HU Returns .P The .Cf wscanf function returns the value of the macro .Cf EOF if an input failure occurs before any conversion. Otherwise, the .Cf wscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure. .H 5 "The \*(Cwswprintf\fP function" .HU Synopsis .Cb #include int swprintf(wchar_t *s, size_t n, const wchar_t *format, ...); .Ce .HU Description .P The .Cf swprintf function is equivalent to .Cf fwprintf , except that the argument .Cf s specifies an array of wide characters into which the generated output is to be written, rather than converted to multibyte characters and written to a stream, and in that the detection of encoding errors may differ. No more than .Cf n wide characters are written, including a terminating null wide character, which is always added (unless .Cf n is zero). If copying takes place between objects that overlap, the behavior is undefined. .HU Returns .P The .Cf swprintf function returns the number of wide characters written in the array, not counting the terminating null wide character, or a negative value if .Cf n or more wide characters were requested to be generated. .H 5 "The \*(Cwswscanf\fP function" .HU Synopsis .Cb #include int swscanf(const wchar_t *s, const wchar_t *format, ...); .Ce .HU Description .P The .Cf swscanf function is equivalent to .Cf fwscanf , except that the argument .Cf s specifies a wide string from which the input is to be obtained, rather than by converting multibyte characters from a stream, and in that the detection of encoding errors may differ. Reaching the end of the wide string is equivalent to encountering end-of-file for the .Cf fwscanf function. If copying takes place between objects that overlap, the behavior is undefined. .HU Returns .P The .Cf swscanf function returns the value of the macro .Cf EOF if an input failure occurs before any conversion. Otherwise, the .Cf swscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure. .H 5 "The \*(Cwvfwprintf\fP function" .HU Synopsis .Cb #include #include #include int vfwprintf(FILE *stream, const wchar_t *format, va_list arg); .Ce .HU Description .P The .Cf vfwprintf function is equivalent to .Cf fwprintf , with the variable argument list replaced by .Cf arg , which shall have been initialized by the .Cf va_start macro (and possibly subsequent .Cf va_arg calls). The .Cf vfwprintf function does not invoke the .Cf va_end .ds rN \*F macro.\*(rN .FS As the functions .Cf vfwprintf , .Cf vswprintf , and .Cf vwprintf invoke the .Cf va_arg macro, the value of .Cf arg after the return is unspecified. .FE .HU Returns .P The .Cf vfwprintf function returns the number of wide characters transmitted, or a negative value if an output error occurred. .HU Example .P The following shows the use of the .Cf vfwprintf function in a general error-reporting routine. .Cb #include #include #include .sp 0.5v void error(wchar_t *function_name, wchar_t *format, ...) { va_list args; .sp 0.5v va_start(args, format); /* \fIprint out name of function causing error\fP */ fwprintf(stderr, L"ERROR in %s: ", function_name); /* \fIprint out remainder of message\fP */ vfwprintf(stderr, format, args); va_end(args); } .Ce .H 5 "The \*(Cwvwprintf\fP function" .HU Synopsis .Cb #include #include int vwprintf(const wchar_t *format, va_list arg); .Ce .HU Description .P The .Cf vwprintf function is equivalent to .Cf wprintf , with the variable argument list replaced by .Cf arg , which shall have been initialized by the .Cf va_start macro (and possibly subsequent .Cf va_arg calls). The .Cf vwprintf function does not invoke the .Cf va_end macro.\*(rN .HU Returns .P The .Cf vwprintf function returns the number of wide characters transmitted, or a negative value if an output error occurred. .H 5 "The \*(Cwvswprintf\fP function" .HU Synopsis .Cb #include #include int vswprintf(wchar_t *s, size_t n, const wchar_t *format, va_list arg); .Ce .HU Description .P The .Cf vswprintf function is equivalent to .Cf swprintf , with the variable argument list replaced by .Cf arg , which shall have been initialized by the .Cf va_start macro (and possibly subsequent .Cf va_arg calls). The .Cf vswprintf function does not invoke the .Cf va_end macro.\*(rN\ If copying takes place between objects that overlap, the behavior is undefined. .HU Returns .P The .Cf vswprintf function returns the number of wide characters written in the array, not counting the terminating null wide character, or a negative value if .Cf n or more wide characters were requested to be generated.