From kido@vnet.ibm.com Wed Oct  7 07:43:06 1992
Received: from vnet.ibm.com by dkuug.dk via EUnet with SMTP (5.64+/8+bit/IDA-1.2.8)
	id AA20804; Wed, 7 Oct 92 07:43:06 +0100
Message-Id: <9210070643.AA20804@dkuug.dk>
Received: from YMTVM8 by vnet.ibm.com (IBM VM SMTP V2R2) with BSMTP id 4998;
   Wed, 07 Oct 92 02:45:30 EDT
Date: Wed, 7 Oct 92 15:40:58 JST
From: "Akio    Kido" <kido@vnet.ibm.com>
To: sc22wg20@dkuug.dk, sc22wg15@dkuug.dk, sig-international@osf.org
Subject: mse.trf.4
X-Charset: ASCII
X-Char-Esc: 29

#! /bin/sh
#
# This is shell archive.
# Remove anything before this line, then unpack this
# file by saveing it into a $file and typing
# "sh $file".
#
# Contents:
#	-rw-rw-rw- format.mm
#
sed "s/^X//" > format.mm << 'EOF'
X.H 3 "Formatted wide character input/output functions"
X.H 4 "The \f(CBfwprintf\fP function"
X.HU "Synopsis"
X.Cb
X	#include <stdio.h>
X	#include <wchar.h>
X	int fwprintf(FILE *stream, const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf fwprintf
Xfunction  writes  output  to  the
X.Cf stream
Xpointed to by stream, under control of the wide string
Xpointed to
Xby
X.Cf format
Xthat  specifies  how  subsequent  arguments  are
Xconverted  for  output.  If there are insufficient arguments
Xfor the format, the behavior is undefined.  If the format is
Xexhausted  while  arguments remain, the excess arguments are
Xevaluated  (as  always)  but  are  otherwise  ignored.   The
X.Cf fwprintf
Xfunction returns when the end of the format
Xis encountered.
X.P
XNote that all characters in the format that are described
Xas special wide characters in the following description
X(such as white-space and %) are members of the basic character
Xset.
X.P
X.mc *
X.mc
XThe format
Xis composed of zero or more directives:  ordinary wide
X.mc |
Xcharacters (not %), which are
Xconverted to multibyte characters and written
Xto the output
X.mc
Xstream; and conversion specifications, each of which results
Xin   fetching zero  or  more subsequent  arguments.   Each
Xconversion specification is introduced by the  wide character %.
XAfter the %, the following appear in sequence:
X.BL
X.LI
XZero or more \f2flags\fP  (in  any   order)   that  modify  the
Xmeaning of the conversion specification.
X.LI
XAn optional minimum  \f2field  width\fP.   If  the  converted
Xvalue  has  fewer  wide characters  than the field width, it
Xwill be padded with spaces (by default) on the left (or
Xright,  if  the  left adjustment flag, described later,
Xhas been given) to the field width.  The  field  width
Xtakes  the form of an asterisk * (described later) or a
Xdecimal integer.
X.LI
XAn optional \f2precision\fP that gives the minimum number  of
Xdigits  to  appear  for  the  \*(Cwd\fP, \*(Cwi\fP,
X\*(Cwo\fP, \*(Cwu\fP, \*(Cwx\fP, and \*(CwX\fP
Xconversions, the number of digits to appear  after  the
Xdecimal-point  character for  \*(Cwe\fP, \*(CwE\fP, and
X\*(Cwf\fP conversions,
Xthe maximum number of significant digits for the \*(Cwg\fP  and
X\*(CwG\fP  conversions,  or the maximum number of wide characters to
Xbe  written  from  a  string   in \*(Cws\fP  conversion.   The
Xprecision  takes   the  form  of  a  period (.) followed
Xeither by an asterisk *  (described  later)  or  by  an
Xoptional   decimal  integer;   if only  the  period  is
Xspecified, the  precision  is  taken as zero. If a
Xprecision  appears with any other conversion specifier,
Xthe behavior is undefined.
X.LI
XAn optional \*(Cwh\fP specifying that a following \*(Cwd\fP,
X\*(Cwi\fP, \*(Cwo\fP, \*(Cwu\fP, \*(Cwx\fP, or \*(CwX\fP
Xconversion specifier applies to a \*(Cwshort int\fP or
X\*(Cwunsigned short int\fP argument  (the  argument  will  have
Xbeen promoted according to the integral promotions, and
Xits value shall be converted to \*(Cwshort int\fP  or  \*(Cwunsigned
Xshort  int\fP  before  printing); an optional \*(Cwh\fP specifying
Xthat a following \*(Cwn\fP conversion specifier  applies to a
Xpointer  to  a  \*(Cwshort int\fP argument; an optional \*(Cwl\fP (ell)
Xspecifying that a  following   \*(Cwd\fP, \*(Cwi\fP,
X\*(Cwo,\fP \*(Cwu\fP, \*(Cwx\fP, or \*(CwX\fP
Xconversion  specifier applies to a \*(Cwlong int\fP or \*(Cwunsigned
Xlong int\fP argument; an  optional  \*(Cwl\fP  specifying  that   a
Xfollowing  \*(Cwn\fP conversion specifier applies to a pointer
Xto a \*(Cwlong int\fP argument; or  an  optional   \*(CwL\fP  specifying
Xthat   a following \*(Cwe\fP, \*(CwE\fP, \*(Cwf\fP,
X\*(Cwg\fP, or \*(CwG\fP conversion specifier
Xapplies to a \*(Cwlong double\fP argument.  If an \*(Cwh\fP,
X\*(Cwl\fP, or \*(CwL\fP
Xappears   with  any  other  conversion  specifier,  the
Xbehavior is undefined.
X.LI
XA wide character that specifies the type of conversion to be
Xapplied.
X.LE
X.P
X.mc |
XAs noted above,
Xa field width, or precision, or both, may be  indicated
Xby  an asterisk.
XIn this case, an
X.mc
X\*(Cwint\fP argument supplies the field  width  or  precision.   The
Xarguments  specifying  field  width,  or precision, or both,
Xshall appear (in that order) before the argument (if any) to
Xbe converted. A negative field width argument is taken as a
X- flag followed by  a  positive  field  width.   A  negative
Xprecision  argument  is  taken  as  if  the  precision  were
Xomitted.
X.P
XThe flag wide characters and their meanings are
X.VL 10
X.LI "\*(Cw-\fP"
XThe result of the conversion  will  be  left-justified
X.mc |
Xwithin  the field.
X(It will be right-justified if this flag is not specified.)
X.mc
X.LI "\*(Cw+\fP"
XThe result of a signed conversion  will   always   begin
X.mc |
Xwith  a  plus or minus sign.
X(It will begin with a sign only when a negative value is converted
Xif this flag is not specified.)
X.mc
X.LI "\f2space\fP"
XIf the first wide character of a signed conversion is not a
Xsign,   or  if  a  signed  conversion  results  in  no
Xwide characters, a space will be prefixed  to  the  result.
XIf  the  space and + flags both appear, the space flag
Xwill be ignored.
X.LI "\*(Cw#\fP"
XThe result  is  to  be  converted  to  an  ``alternate
Xform.''  For  \*(Cwo\fP conversion, it increases the precision
X.mc |
Xto force the first digit of the result to be  a zero
Xif necessary.
X.mc
XFor \*(Cwx\fP (or \*(CwX\fP) conversion, a nonzero result
Xwill have \*(Cw0x\fP (or \*(Cw0X\fP) prefixed to  it.
XFor \*(Cwe\fP,  \*(CwE\fP, \*(Cwf\fP,  \*(Cwg\fP,  and
X\*(CwG\fP conversions,
Xthe   result    will  always  contain  a
Xdecimal-point wide character, even if no digits follow  it.
X(Normally,  a  decimal-point  wide character appears in the
Xresult of these conversions only if a  digit  follows
Xit.)  For \*(Cwg\fP and \*(CwG\fP conversions, trailing
Xzeros will \f2not\fP
Xbe removed from the result.    For  other  conversions,
Xthe behavior is undefined.
X.LI "\*(Cw0\fP"
XFor \*(Cwd\fP, \*(Cwi\fP, \*(Cwo\fP, \*(Cwu\fP, \*(Cwx\fP,
X\*(CwX\fP, \*(Cwe\fP, \*(CwE\fP, \*(Cwf\fP, \*(Cwg\fP, and
X\*(CwG\fP  conversions,
Xleading  zeros  (following  any  indication of sign or
Xbase) are used to pad to the  field width;   no space
Xpadding  is performed.   If  the  \*(Cw0\fP  and \*(Cw-\fP flags both
Xappear, the \*(Cw0\fP flag will be ignored.
XFor \*(Cwd\fP, \*(Cwi\fP, \*(Cwo\fP, \*(Cwu\fP, \*(Cwx\fP,
Xand \*(CwX\fP conversions,
Xif a precision is specified, the
X\*(Cw0\fP flag will be ignored. For  other  conversions,  the
Xbehavior is undefined.
X.LE
X.P
XThe conversion specifiers and their meanings are
X.VL 10
X.LI "\*(Cwd\fP, \*(Cwi\fP"
XThe \*(Cwint\fP argument is converted to signed  decimal  in
Xthe  style  \f2[\-]dddd\fP.   The  precision specifies the
Xminimum number of digits to  appear;  if  the  value
Xbeing   converted can be represented in fewer digits,
Xit will be expanded with leading zeros.  The default
Xprecision  is 1.  The  result of converting a zero
Xvalue with a precision of zero is no wide characters.
X.LI "\*(Cwo\fP, \*(Cwu\fP, \*(Cwx\fP, \*(CwX\fP"
XThe \*(Cwunsigned int\fP argument is converted  to  unsigned
Xoctal (\*(Cwo\fP), unsigned  decimal (\*(Cwu\fP),  or  unsigned
Xhexadecimal notation (\*(Cwx\fP or \*(CwX\fP) in the style
X\f2dddd\fP;
Xthe letters \*(Cwabcdef\fP are used for \*(Cwx\fP conversion
Xand the letters \*(CwABCDEF\fP for \*(CwX\fP conversion.
XThe   precision
Xspecifies the minimum number of digits to appear; if
Xthe value being  converted  can  be  represented  in
Xfewer   digits,  it  will  be  expanded  with leading
Xzeros.  The default precision is 1.  The  result  of
Xconverting  a zero value with a precision of zero is
Xno wide characters.
X.LI "\*(Cwf\fP"
XThe \*(Cwdouble\fP argument is converted to decimal notation
Xin  the style \f2[\-]ddd.ddd\fP, where the number of digits
Xafter the decimal-point wide character is   equal  to  the
Xprecision   specification.    If  the precision  is
Xmissing, it is taken as 6; if the precision is  zero
Xand  the  #  flag is not specified, no decimal-point
Xwide character appears. If a decimal-point wide character
Xappears,  at least one digit appears before it.  The
Xvalue   is rounded  to  the  appropriate  number  of
Xdigits.
X.LI "\*(Cwe\fP, \*(CwE\fP"
XThe  \*(Cwdouble\fP  argument  is converted  in  the   style
X\f2[\-]d.ddd\fP\*(Cwe\fP\o'+_'\f2dd\fP,
Xwhere  there  is one digit before the
Xdecimal-point wide character (which  is  nonzero  if  the
Xargument  is nonzero) and the number of digits after
Xit is equal to the precision; if  the precision  is
Xmissing,  it is taken as 6; if the precision is zero
Xand the \*(Cw#\fP flag is not  specified,  no decimal-point
Xwide character  appears.  The  value  is rounded to the
Xappropriate number  of  digits.   The \*(CwE\fP  conversion
Xspecifier  will produce a number with \*(CwE\fP instead of
X\*(Cwe\fP introducing  the  exponent.   The  exponent   always
Xcontains at least two digits.   If the value is zero,
Xthe exponent is zero.
X.LI "\*(Cwg\fP, \*(CwG\fP"
XThe \*(Cwdouble\fP argument is converted
Xin style \*(Cwf\fP or \*(Cwe\fP
X(or in style \*(CwE\fP in the case of a \*(CwG\fP conversion
Xspecifier),
Xwith  the  precision  specifying   the   number   of
Xsignificant digits.  If the precision is zero, it is
Xtaken as 1.  The style used  depends  on  the  value
Xconverted;  style   \*(Cwe\fP (or \*(CwE\fP) will be used
Xonly if the exponent resulting from such a  conversion  is
Xless than \-4  or greater than or equal to the precision.
XTrailing  zeros  are  removed   from  the  fractional
Xportion  of  the  result; a decimal-point wide character
Xappears only if it is followed by a digit.
X.LI "\*(Cwc\fP"
XThe
X.Cf wchar_t
X.mc |
Xargument is
Xconverted to a multibyte character and written.
X.mc
X.LI "\*(Cws\fP"
XThe argument shall be  a  pointer  to an array  of
X\*(WC
Xtype. Wide characters   from  the  array  are
X.mc |
Xconverted to multibyte characters and
X.mc
Xwritten up to (but not including) a terminating null
Xwide character; if the precision is  specified,  no  more
X.mc |
Xthan  that  many  wide characters  are
Xconverted to multibyte characters and
Xwritten.  If the
X.mc
Xprecision is not specified or is  greater   than  the
Xsize  of  the array, the array shall contain a null
Xwide character.
X.LI "\*(Cwp\fP"
XThe argument shall be a pointer to \*(Cwvoid\fP.  The  value
Xof  the  pointer  is  converted  to  a  sequence  of
Xprintable wide characters, in   an implementation-defined
Xmanner.
X.LI "\*(Cwn\fP"
XThe argument shall be a pointer to an integer  into
Xwhich is \f2written\fP the number of wide characters written to
Xthe output stream so far by this  call  to  \*(Cwfwprintf\fP.
XNo argument is converted.
X.LI "\*(Cw%\fP"
XA
X.Cf %
Xis written.   No  argument  is  converted.   The
Xcomplete conversion specification shall be
X.Cf %% .
X.LE
X.P
XIf a conversion specification is invalid, the  behavior
Xis undefined.
X.P
XIf any argument  is,  or points   to,  a   union  or  an
Xaggregate  (except  for  an array of \*(WC type using
X.Cf %s
Xconversion, or a pointer using
X.Cf %p
Xconversion), the  behavior
Xis undefined.
X.P
XIn no case does a  nonexistent  or  small  field width
Xcause   truncation  of a field; if the result of a conversion
Xis wider than the field width,  the  field  is  expanded  to
Xcontain the conversion result.
X.HU "Returns"
X.br
X.P
XThe \*(Cwfwprintf\fP function returns the number   of wide characters
Xtransmitted,  or a  negative  value   if an output   error
X.mc |
Xor an encoding error
X.mc
Xoccurred.
X.br
X.HU "Environmental limit"
X.br
X.P
X.mc |
XThe minimum value for the maximum number of
Xbytes
X.mc
Xproduced by any single conversion shall be 509.
X.HU "Examples"
X.br
X.P
XTo print a date and time in the form ``Sunday, July 3, 10:02,''
Xwhere weekday and month are pointers to wide strings:
X.Cb
X          #include <stdio.h>
X          #include <wchar.h>
X          /*...*/
X          fwprintf(stdout, L"%s, %s %d, %.2d:%.2d\en",
X                weekday, month, day, hour, min);
X.Ce
X.P
X.mc |
XTo print \*(pi to five decimal places:
X.mc
X.Cb
X          #include <stdio.h>
X          #include <math.h>
X          #include <wchar.h>
X          /*...*/
X          fwprintf(stdout, L"pi = %.5f\en", 4 * atan(1.0));
X.Ce
X
X.H 4  "The \f(CBfwscanf\fP function"
X.HU "Synopsis"
X.Cb
X      #include <stdio.h>
X      #include <wchar.h>
X      int fwscanf(FILE *stream, const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf fwscanf
Xfunction reads input from the stream pointed
Xto by
X.Cf stream ,
Xunder control of the wide string pointed to by
X.Cf format
Xthat specifies the admissible input sequences and how
Xthey  are  to be converted for assignment, using subsequent
Xarguments  as pointers  to  the  objects to receive   the
Xconverted  input.    If  there are insufficient arguments for
Xthe format, the behavior is undefined.   If  the  format  is
Xexhausted  while  arguments remain, the excess arguments are
Xevaluated (as always) but are otherwise ignored.
X.P
XNote that all wide characters in the format that are
Xdescribed as special wide characters in the following description
X(such as white-space and
X.Cf % )
Xare members of the basic character set.
X.P
X.mc *
X.mc
XThe format
Xis composed of zero or more directives: one or  more  white-space
Xwide characters; an ordinary wide character (neither
X.Cf %
Xnor a white-space wide character); or a conversion specification.
XEach conversion specification is introduced by the wide character
X.Cf % .
XAfter the
X.Cf % ,
Xthe following appear in sequence:
X.BL
X.LI
XAn optional assignment-suppressing wide character
X.Cf * .
X.LI
XAn optional nonzero decimal integer that specifies the  maximum field width.
X.LI
XAn optional
X.Cf h ,
X.Cf l
X(ell) or
X.Cf L
Xindicating the size of  the receiving  object.
XThe conversion specifiers
X.Cf d ,
X.Cf i ,
Xand
X.Cf n
Xshall be preceded by
X.Cf h
Xif the corresponding  argument
Xis a pointer to \*(Cwshort int\fP rather than a pointer to
X.Cf int ,
Xor by
X.Cf l
Xif it is a pointer to \*(Cwlong int\fP.
XSimilarly, the conversion  specifiers
X.Cf o ,
X.Cf u ,
Xand
X.Cf x
Xshall be preceded by
X.Cf h
Xif  the  corresponding  argument  is  a  pointer  to
X\*(Cwunsigned short int\fP rather than a pointer to \*(Cwunsigned int\fP,
Xor by
X.Cf l
Xif it is a pointer to \*(Cwunsigned long int\fP.
XFinally, the conversion specifiers
X.Cf e ,
X.Cf f ,
Xand
X.Cf g
Xshall be preceded by
X.Cf l
Xif  the  corresponding  argument is a
Xpointer to \*(Cwdouble\fP rather than a pointer to \*(Cwfloat\fP, or by
X.Cf L
Xif it is a pointer to \*(Cwlong doubles\fP. If an
X.Cf h ,
X.Cf l ,
Xor
X.Cf L
Xappears with any other conversion  specifier, the behavior is undefined.
X.LI
XA wide character that specifies the type of conversion to be
Xapplied.
XThe valid conversion specifiers are described below.
X.LE
X.P
XThe
X.Cf fwscanf
Xfunction  executes  each directive  of  the
Xformat  in  turn.    If a directive fails, as detailed below,
Xthe
X.Cf fwscanf
Xfunction  returns.
X.mc |
XFailures   are  described as input    failures
X(if an encoding error occurs or
Xdue   to  the unavailability of input wide characters),
Xor  matching failures  (due to inappropriate input).
X.mc
X.P
XA directive composed  of white-space  wide character(s)   is
Xexecuted  by  reading  input up to the first non-white-space
Xwide character  (which  remains  unread),   or  until    no   more
Xwide characters can be read.
X.P
XA directive that is an ordinary wide character  is
X.mc |
Xexecuted  by  reading the next wide character of the stream. If
Xthe  wide character  differs from  the
X.mc
Xdirective,  the  directive  fails,  and  the  differing  and
Xsubsequent wide characters remain unread.
X.P
XA directive that is a conversion specification  defines
Xa set  of  matching input sequences, as described below for
Xeach specifier.  A conversion specification is  executed  in
Xthe following steps:
X.P
XInput  white-space  wide characters  (as   specified  by  the
X.Cf iswspace
Xfunction)  are  skipped,  unless  the specification
Xincludes a
X.Cf [ ,
X.Cf c ,
Xor
X.Cf n
X.mc |
Xspecifier.\*F
X.FS
XThese white-space wide characters are not counted against a specified field width.
X.FE
X.mc
X.P
X.mc |
X.P
X.mc
XAn input item is   read  from  the  stream,  unless  the
Xspecification includes  an
X.Cf n
Xspecifier.  An input item is
Xdefined  as  the  longest  matching   sequence   of  input
Xwide characters,  unless that exceeds a specified field width, in
Xwhich case it is the initial subsequence of that  length  in
Xthe  sequence.  The first wide character, if any, after the input
Xitem remains unread.  If the length of  the  input  item  is
Xzero,   the  execution of the directive fails: this condition
Xis a matching failure, unless an error prevented input  from
Xthe stream, in which case it is an input failure.
X.P
XExcept in the case of a
X.Cf %
Xspecifier,  the  input  item
X(or,  in  the case  of  a
X.Cf %n
Xdirective, the count of input
Xwide characters) is  converted  to  a type  appropriate  to  the
Xconversion  specifier.   If the input item is not a matching
Xsequence,  the  execution of the  directive fails:    this
Xcondition   is   a   matching   failure.   Unless  assignment
Xsuppression  was  indicated  by  a
X.Cf * ,
Xthe  result  of  the
Xconversion  is  placed in the object pointed to by the first
Xargument following the
X.Cf format
Xargument that has not  already
Xreceived  a conversion result.  If this object does not have
Xan appropriate type, or if  the  result  of  the  conversion
Xcannot be represented in the space provided, the behavior is
Xundefined.
X.P
XThe following conversion specifiers are valid:
X.VL 10
X.LI "\*(Cwd\fP"
XMatches an optionally signed  decimal  integer, whose
Xformat  is  the   same  as  expected   for  the  subject
Xsequence of the
X.Cf wcstol
Xfunction with the value 10  for the
X.Cf base
Xargument.  The corresponding argument shall
Xbe a pointer to integer.
X.LI "\*(Cwi\fP"
XMatches an optionally signed integer, whose format  is
Xthe   same  as expected for the subject sequence of the
X.Cf wcstol
Xfunction  with  the   value  0  for  the
X.Cf  base
Xargument.   The   corresponding  argument  shall   be a
Xpointer to integer.
X.LI "\*(Cwo\fP"
XMatches an  optionally  signed  octal  integer, whose
Xformat  is  the   same  as  expected   for  the  subject
Xsequence of the
X.Cfwcstoul
Xfunction with the value 8  for
Xthe
X.Cf base
Xargument.  The corresponding argument shall
Xbe a pointer to unsigned integer.
X.LI "\*(Cwu\fP"
XMatches an optionally signed  decimal  integer, whose
Xformat  is  the   same  as  expected   for  the  subject
Xsequence of the
X.Cf wcstoul
Xfunction with the value 10 for
Xthe
X.Cf base
Xargument.  The corresponding argument shall
Xbe a pointer to unsigned integer.
X.LI "\*(Cwx\fP"
XMatches  an optionally  signed   hexadecimal  integer,
Xwhose  format  is the same as expected for the subject
Xsequence of the
X.Cf wcstoul
Xfunction with the value 16 for
Xthe
X.Cf base
Xargument.  The corresponding argument shall
Xbe a pointer to unsigned integer.
X.LI "\*(Cwe\fP, \*(Cwf\fP, \*(Cwg\fP"
X.mc |
XMatches an optionally  signed  floating-point  number,
X.mc
Xwhose  format  is the same as expected for the subject wide
Xstring of the
X.Cf wcstod
Xfunction.  The corresponding
Xargument shall be a pointer to floating.
X.LI "\*(Cws\fP"
XMatches a sequence of  non-white-space  wide characters.
XThe   corresponding  argument shall be a pointer to the
Xinitial wide character of an array large enough to accept
Xthe   sequence  and a terminating null wide character, which
Xwill be added automatically.
X.mc *
X.mc
X.LI "\*(Cwc\fP"
XMatches a  sequence  of wide characters  of  the  number
Xspecified  by  the field width (1 if no field width is
Xpresent in the directive).  The corresponding argument
Xshall  be  a  pointer  to  the initial wide character of an
Xarray large enough to accept the  sequence.   No  null
Xwide character is added.
X.LI "\*(Cwp\fP"
XMatches an implementation-defined set of wide character sequences,
Xwhich should be the same as the set of wide character sequences
Xthat may be produced by the
X.Cf %p
Xconversion  of  the
X.Cf fwprintf
Xfunction.   The   corresponding  argument  shall   be a
Xpointer to a pointer to
X.Cf void .
XThe  interpretation  of
Xthe   input  item  is  implementation-defined.   If the
Xinput item is a value  converted  earlier  during  the
Xsame program execution, the pointer that results shall
Xcompare equal to that value; otherwise the behavior of
Xthe
X.Cf %p
Xconversion is undefined.
X.LI "\*(Cwn\fP"
XNo input  is  consumed.  The  corresponding  argument
Xshall  be  a  pointer  to  integer into which is to be
Xwritten the number of wide characters read from the  input
Xstream  so  far   by this call to the
X.Cf fwscanf
Xfunction.
XExecution of a
X.Cf %n
Xdirective   does  not  increment  the
Xassignment  count returned  at  the  completion  of
Xexecution of the
X.Cf fwscanf
Xfunction.
X.LI "\*(Cw%\fP"
XMatches  a  single
X.Cf % ;
Xno  conversion  or  assignment
Xoccurs.   The  complete conversion specification shall be
X.Cf %% .
X.LE
X.P
XIf a conversion specification is invalid, the  behavior
Xis undefined.
X.P
XThe conversion specifiers
X.Cf E ,
X.Cf G ,
Xand
X.Cf X
Xare  also valid
Xand behave the same as, respectively,
X.Cf e ,
X.Cf g ,
Xand
X.Cf x .
X.P
XIf end-of-file is encountered during input,  conversion
Xis  terminated.  If end-of-file occurs before any wide characters
Xmatching the current directive have been  read  (other  than
Xleading  white  space,  where   permitted),  execution of the
Xcurrent  directive  terminates  with  an  input    failure;
Xotherwise,  unless  execution   of the  current directive is
Xterminated  with  a  matching   failure,  execution  of   the
X.mc |
Xfollowing  directive  other than
X.Cf %n
X(if any)  is terminated with an input
X.mc
Xfailure.
X.P
XIf  conversion  terminates  on  a   conflicting  input
Xwide character, the offending input wide character is left unread in
Xthe input stream.   Trailing white space (including  new-line
Xwide characters)  is  left  unread unless matched by a directive.
XThe success of literal matches and suppressed assignments is
Xnot directly determinable other than via the
X.Cf %n
Xdirective.
X.HU "Returns"
X.br
X.P
XThe
X.Cf fwscanf
Xfunction returns
X.Cf -1
Xif   an   input   failure  occurs  before  any  conversion.
XOtherwise, the
X.Cf fwscanf
Xfunction returns the number  of  input
Xitems   assigned,  which  can  be fewer than provided for, or
Xeven zero, in the event of an early matching failure.
X.HU "Examples"
X.br
X.P
XThe call:
X.Cb
X      #include <stdio.h>
X      #include <wchar.h>
X      /*...*/
X      int n, i; float x; wchar_t name[50];
X      n = fwscanf(stdin, L"%d%f%s", &i, &x, name);
X.Ce
X.P 0
Xwith the input line:
X.Cb
X      25 54.32E-1 thompson
X.Ce
X.P
Xwill assign to \f2n\fP the value 3, to \f2i\fP the value 25,  to  \f2x\fP  the
Xvalue 5.432, and \f2name\fP will contain \*(Cwthompson\e0\fP.  Or:
X.Cb
X      #include <stdio.h>
X      #include <wchar.h>
X      /*...*/
X.mc |
X      int i; float x; double y;
X      fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
X.mc
X.Ce
X.P 0
Xwith input:
X.Cb
X      56789 0123 56a72
X.Ce
Xwill assign to \f2i\fP the value 56 and to \f2x\fP the value 789.0, will
X.mc |
Xskip  0123,  and \f2y\fP will be assigned the value 56.0.
XThe next wide character read from the input stream will be
X.mc
X.Cf a .
X.mc |
X.ig
X# .P
X# To accept repeatedly from
X# .Cf stdin
X# a quantity, a  unit  of
X# measure and an item name:
X# .Cb
X#       #include <stdio.h>
X#      #include <wchar.h>
X#      /*...*/
X#      int count; float quant; wchar_t units[21], item[21];
X#      while (!feof(stdin) && !ferror(stdin)) {
X#            count = fwscanf(stdin, L"%f%20s of %20s",
X#                  &quant, units, item);
X#            fscanf(stdin, "%*[^\en]");
X#
X#      }
X# .Ce
X# .P
X# If the
X# .Cf stdin
X# stream contains the following lines:
X# .Cb
X#       2 quarts of oil
X#       -12.8degrees Celsius
X#       lots of luck
X#       10.0LBS  of
X#       dirt
X#       100ergs of energy
X# .Ce
X# .P 0
X# the execution of the above example will be analogous to  the
X# following assignments:
X# .Cb
X#	quant = 2; wcscpy(units, L"quarts"); wcscpy(item, L"oil");
X# 	count = 3;
X# 	quant = -12.8; wcscpy(units, L"degrees");
X# 	count = 2; /* L"C" \fIfails to match\fP L"o" */
X# 	count = 0; /* L"l" \fIfails to match\fP L"%f" */
X# 	quant = 10.0; wcscpy(units, L"LBS"); wcscpy(item, L"dirt");
X# 	count = 3;
X# 	count = 0; /* L"100e" \fIfails to match\fP L"%f" */
X# 	count = EOF;
X# .Ce
X..
X.mc
X
X.H 4 "The \f(CBwprintf\fP function"
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <wchar.h>
X      int wprintf(const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wprintf
Xfunction is equivalent to
X.Cf fwprintf
Xwith   the argument
X.Cf stdout
Xinterposed before the arguments to
X.Cf wprintf .
X.HU "Returns"
X.br
X.P
XThe
X.Cf wprintf
Xfunction returns the  number   of wide characters
Xtransmitted, or  a  negative  value  if  an  output  error
X.mc |
Xor an encoding error
X.mc
Xoccurred.
X.br
X
X.H 4 "The \f(CBwscanf\fP function
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <wchar.h>
X      int wscanf(const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf wscanf
Xfunction is equivalent  to
X.Cf fwscanf
Xwith   the argument
X.Cf stdin
Xinterposed before the arguments to wscanf.
X.HU "Returns"
X.br
X.P
XThe
X.Cf wscanf
Xfunction returns
X.Cf -1
Xif   an   input   failure  occurs  before  any  conversion.
XOtherwise, the
X.Cf wscanf
Xfunction returns the  number  of  input
Xitems   assigned,  which  can  be fewer than provided for, or
Xeven zero, in the event of an early matching failure.
X
X.H 4 "The \f(CBswprintf\fP function"
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <wchar.h>
X      int swprintf(wchar_t *s, size_t n, const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf swprintf
Xfunction is equivalent to
X.Cf fwprintf ,
Xexcept that the argument
X.Cf s
Xspecifies an array of wide characters into
X.mc |
Xwhich the generated output is to be
Xconverted to multibyte character and
Xwritten, rather than to a  stream.
XNo more than
X.mc
X.Cf n
X.mc |
Xwide characters are written including a terminating null wide character.
X.mc
XA null  wide character  is  written at the end of the wide characters
Xwritten; it is not counted as part of the returned sum.   If
Xcopying  takes  place  between  objects  that  overlap,  the
Xbehavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf swprintf
Xfunction returns the number   of wide characters
Xwritten  in  the  array,  not   counting the terminating null wide
Xcharacter.
X.br
X
X.H 4 "The \f(CBswscanf\fP function"
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <wchar.h>
X      int swscanf(const wchar_t *s, const wchar_t *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf swscanf
Xfunction is  equivalent  to
X.Cf fwscanf ,
Xexcept that
Xthe argument
X.Cf s
Xspecifies a wide string from which the input
Xis to be obtained, rather than from a stream.  Reaching the end of
Xthe wide string is equivalent to encountering end-of-file
Xfor the
X.Cf fwscanf
Xfunction. If copying  takes place  between
Xobjects that overlap, the behavior is undefined.
X.HU "Returns"
X.br
X.P
XThe
X.Cf swscanf
Xfunction returns
X.Cf -1
Xif   an   input   failure  occurs  before  any  conversion.
XOtherwise, the
X.Cf swscanf
Xfunction returns the number  of  input
Xitems   assigned,  which  can  be fewer than provided for, or
Xeven zero, in the event of an early matching failure.
X
X.H 4 "The \f(CBvfwprintf\fP function"
X.HU "Synopsis"
X.Cb
X      #include <stdio.h>
X      #include <stdarg.h>
X      #include <wchar.h>
X      int vfwprintf(FILE *stream, const wchar_t *format, va_list arg);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf vfwprintf
Xfunction is equivalent to
X.Cf fwprintf ,
Xwith the variable argument list replaced by
X.Cf arg ,
Xwhich shall have been  initialized   by the
X.Cf va_start
Xmacro  (and  possibly subsequent
X.Cf va_arg
Xcalls).   The
X.Cf vfwprintf
Xfunction does not invoke the
X.Cf va_end
Xmacro.
X.HU "Returns"
X.br
X.P
XThe
X.Cf vfwprintf
Xfunction returns the number of  wide characters
Xtransmitted,  or a  negative  value   if an output   error
X.mc |
Xor an encoding error
X.mc
Xoccurred.
X.HU "Example"
X.br
X.P
XThe following shows the use of the
X.Cf vfwprintf
Xfunction in a general error-reporting routine.
X.Cb
X      #include <stdio.h>
X      #include <stdarg.h>
X      #include <wchar.h>
X      void error(wchar_t *function_name, wchar_t *format, ...)
X      {
X            va_list args;
X            va_start(args, format);
X            /* print out name of function causing error */
X            fwprintf(stderr, L"ERROR in %s: ", function_name);
X            /* print out remainder of message */
X            vfwprintf(stderr, format, args);
X            va_end(args);
X      }
X.Ce
X
X.H 4 "The \f(CBvwprintf\fP function"
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <stdarg.h>
X      #include <wchar.h>
X      int vwprintf(const wchar_t *format, va_list arg);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf  vwprintf
Xfunction is equivalent to
X.Cf wprintf ,
Xwith   the variable  argument  list  replaced  by
X.Cf arg ,
Xwhich shall have been  initialized   by the
X.Cf va_start
Xmacro  (and  possibly subsequent
X.Cf va_arg
Xcalls).   The
X.Cf vwprintf
Xfunction does not invoke the
X.Cf va_end
Xmacro.
X.HU "Returns"
XThe
X.Cf vwprintf
Xfunction returns the number   of wide characters
Xtransmitted,  or a  negative  value   if an output   error
X.mc |
Xor an encoding error
X.mc
Xoccurred.
X
X.H 4 "The \f(CBvswprintf\fP function"
X.HU "Synopsis"
X'\"      #include <stdio.h>
X.Cb
X      #include <stdarg.h>
X      #include <wchar.h>
X      int vswprintf(wchar_t *s, size_t n, const wchar_t *format, va_list arg);
X.Ce
X.HU "Description"
X.br
X.P
XThe
X.Cf vswprintf
Xfunction is equivalent to
X.Cf swprintf ,
Xwith the variable argument list replaced by
X.Cf arg ,
Xwhich shall have been  initialized   by the
X.Cf va_start
Xmacro  (and  possibly subsequent
X.Cf va_arg
Xcalls).   The
X.Cf vswprintf
Xfunction does not invoke the
X.Cf va_end
Xmacro.  If copying takes  place  between
Xobjects that overlap, the behavior is undefined.
X.HU "Returns"
XThe
X.Cf vswprintf
Xfunction returns the number of  wide characters
Xwritten  in  the  array,  not   counting the terminating null
Xwide character.
X
X.H 3 "Formatted input/output functions"
X.br
X.P
XThe formatted input/output functions of \*(AC is modified to
Xhave some additional conversion specifiers to handle \*(WC type.
X
X.H 4 "The \f(CBfprintf\fP function"
X.HU "Synopsis"
X.Cb
X	#include <stdio.h>
X	int fprintf(FILE *stream, const char *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe new
X.Cf fprintf
Xfunction is extended so that wide characters and wide
X.mc |
Xstrings are handled.
XThough this is a pure extension and the
X.mc
Xdescription in \*(AC subclause 7.9.6.1 can be applied to the
Xnew
X.Cf fprintf
X.mc |
Xfunction, the term \f2character\fP used in the description
Xstands for a single byte character, never for a
X.mc
Xmultibyte character.
X
X.HU "Extension"
X.br
X.P
X.mc |
XIn \*(AC subclause 7.9.6.1, change the precision description
Xto include
X.Cf S
Xwith
X.Cf s
Xso that it contains the following fragment:
X.VL 2
X.LI
X``or the maximum number of characters (bytes) to be written from a string
Xin
X.Cf s
Xor
X.Cf S
Xconversion''
X.LE
X.mc
X.P
X.mc |
XAdd the following two paragraphs to \*(AC subclause 7.9.6.1
Xwithin the description of the conversion specifiers.
X.P
X.mc
X.VL 10
X.LI "\*(CwC\fP"
X.mc |
XThe \*(WC argument is converted to a multibyte character as if by
Xa call to the
X.mc
X.Cf wctomb
X.mc |
Xfunction, except that the shift state of the
X.Cf wctomb
Xfunction is not affected.  The resulting multibyte character
Xis written.  Redundant shift sequences may result if multibyte
Xcharacters have a state-dependent encoding.
X.mc
X.LI "\*(CwS\fP"
X.mc |
XThe argument shall be a pointer to an array of \*(WC type.  Wide
Xcharacters from the array are converted to multibyte characters
X(each as if by a call to the
X.Cf wctomb
Xfunction, except that the shift
Xstate of the
X.Cf wctomb
Xfunction is not affected) up to (but not
Xincluding) the terminating null wide character.  The resulting
Xmultibyte characters are written.  If no precision is specified,
Xthe array shall contain a null wide character.  If a precision is
Xspecified, no more than that many characters (bytes) are written
X(including shift sequences, if any), and the array shall contain a
Xnull wide character if, to equal or to surpass the multibyte
Xcharacter sequence length given by the precision, the function would
Xneed to access a wide character one past the end of the array.  In
Xno case shall a partial multibyte character be written.  Redundant
Xshift sequences may result if multibyte characters have a state-dependent
Xencoding.
X.mc
X.LE
X.P
X.mc |
XThe extension is also applied to other formatted output functions
Xspecified in \*(AC.
X.mc
X.P
X.HU "Returns"
X.br
X.P
X.mc |
XIn \*(AC subclause 7.9.6.1, change the return section to the
Xfollowing:
X.VL 2
X.LI
X``The
X.mc
X.Cf fprintf
X.mc |
Xfunction returns the number of characters (bytes) transmitted,
Xor a negative value if an output or encoding error occurred.''
X.LE
X.mc
X
X.HU "Examples"
X.br
X.P
X.mc |
XAdd the following to the examples portion of \*(AC subclause
X7.9.6.1:
X.P
XIn these examples, multibyte characters do not have a state-dependent
Xencoding, and the members of the extended character set consist of two bytes,
Xthe first of which is denoted here by a period and the second of which by an
Xuppercase letter.
X.P
XGiven a wide string that consists of seven wide characters
X\*(Cw.X\fP, \*(Cw.Y\fP, \*(Cwa\fP, \*(Cwb\fP, \*(Cwc\fP, \*(Cw.Z\fP, and
X\*(Cw.W\fP.
X.mc
X.Cb
X.mc |
X	static wchar_t wstr[] = L".X.Yabc.Z.W";
X.mc
X.Ce
X.mc |
Xthe seven calls
X.Cb
X	fprintf(stdout, "|1234567890123|\en");
X	fprintf(stdout, "|%13S|\en", wstr);
X	fprintf(stdout, "|%-13.9|\en", wstr);
X	fprintf(stdout, "|%13.10|\en", wstr);
X	fprintf(stdout, "|%13.1|\en", wstr);
X	fprintf(stdout, "|%13.15|\en", &wstr[2]);
X	fprintf(stdout, "|%13C|\en", wstr[5]);
X.Ce
X.mc
X.P 0
X.mc |
Xwill print the following seven lines:
X.mc
X.Cb
X.mc |
X	|1234567890123|
X	|  .X.Yabc.Z.W|
X	|.X.Yabc.Z    |
X	|    .X.Yabc.Z|
X	|             |
X	|      abc.Z.W|
X	|           .Z|
X.mc
X.Ce
X
X.H 4 "The \f(CBfscanf\fP function"
X.HU "Synopsis"
X.Cb
X	#include <stdio.h>
X	int fscanf(FILE *stream, const char *format, ...);
X.Ce
X.HU "Description"
X.br
X.P
XThe new
X.Cf fscanf
Xfunction is extended so that wide characters and wide
Xstrings are handled.  Though this is a pure extension and the
Xdescription in \*(AC subclause 7.9.6.2 can be applied to
Xthe new
X.Cf fscanf
X.mc |
Xfunction, the term \f2character\fP used in the
Xdescription stands for a single byte character,
X.mc
Xnever for a multibyte character.
X.HU "Extension"
X.br
X.P
X.mc |
XIn \*(AC subclause 7.9.6.2, change the definition of input
Xfailure to include encoding errors so that it now has the parenthetical
Xphrase:
X.VL 2
X.LI
X``(if an encoding error occurs, or due to the unavailability of input
Xcharacters)''
X.LE
X.mc
X.P
X.mc |
XIn \*(AC subclause 7.9.6.2, change the skip initial white
Xspace characters paragraph description to include
X.Cf C
Xwith
X.Cf C
Xso that it now reads:
X.VL 2
X.LI
X ``Input (single byte) white space characters (as specified by the
X.Cf isspace
Xfunction) are skipped, unless the specification includes a
X.Cf [,
X.Cf c,
X.Cf C,
Xor
X.Cf n
Xspecifier.''
X.LE
X.mc
X.P
X.mc |
XAdd the following two paragraphs to \*(AC subclause 7.9.6.2
Xwithin the description of the conversion specifiers.
X.P
X.mc
X.VL 10
X.mc *
X.mc
X.LI "\*(CwC\fP"
X.mc |
XMatches a sequence of multibyte characters that begins in the initial
Xshift state and each of which is converted to a wide character as if
Xby a call to the
X.Cf mbtowc
Xfunction, except that the shift state of the
X.Cf mbtowc
Xfunction is not affected.  The number of wide characters matched
Xis specified by the field width (1 if no field width is present).  The
Xcorresponding argument shall be a pointer to the initial element of an
Xarray of \*(WC large enough to accept the resulting sequence of wide
Xcharacters.  No null wide character is added.
X.LI "\*(CwS\fP"
XMatches a sequence of multibyte characters that begins in the initial
Xshift state none of which are also single byte white space characters
X(as specified by the
X.Cf isspace
Xfunction).  Each multibyte character is
Xconverted as if by a call to the
X.Cf mbtowc
Xfunction, except that the shift
Xstate of the
X.Cf mbtowc
Xfunction is not affected.  The corresponding
Xargument shall be a pointer to an array of \*(WC large enough to
Xaccept the sequence and the terminating null wide character, which will
Xbe added automatically.
X.mc
X.LE
X.P
X.mc |
XThe extension is also applied to the other formatted input functions
Xspecified in \*(AC.
X.mc
X
X.HU "Examples"
X.br
X.P
X.mc |
XAdd the following to the examples portion of \*(AC subclause
X7.9.6.2:
X.P
XIn these examples, multibyte characters do have a state-dependent encoding,
Xand members of the extended character set are denoted by a period and an
Ximmediately following uppercase letter.  Also, the in and out shift sequences
Xare explicitly denoted, respectively, by \*(Cw<SI>\fP and \*(Cw<SO>\fP.
X.P
XAfter the call:
X.mc
X.Cb
X	#include <stdio.h>
X	#include <stddef.h>
X.mc |
X	/*...*/
X	char str[50];
X	fscanf(stdin, "a%s", str);
X.mc
X.Ce
X.mc |
Xwith the input line:
X.mc
X.Cb
X.mc |
X	a<SI>.X.Y<SO> bc
X.mc
X.Ce
X.mc |
X\*(Cwstr\fP will contain \*(Cw<SI>.X.Y<SO>\e0\fP.
X.mc
X.P
X.mc |
XIn contrast, after the call:
X.mc
X.Cb
X	#include <stdio.h>
X	#include <stddef.h>
X.mc |
X	/*...*/
X	wchar_t wstr[50];
X	fscanf(stdin, "a%S", wstr);
X.mc
X.Ce
X.mc |
Xwith the same input line, \*(Cwwstr\fP will contain the two wide characters that
Xcorrespond to \*(Cw.X\fP and \*(Cw.Y\fP and a terminating null wide character.
X.P
XHowever, the call:
X.mc
X.Cb
X.mc |
X	#include <stdio.h>
X	#include <stddef.h>
X	/*...*/
X	wchar_t wstr[50];
X	fscanf(stdin, "a<SI>.X<SO>%S", wstr);
X.mc
X.Ce
X.mc |
Xwith the same input line will return 0 due to a matching failure against
Xthe \*(Cw<SO>\fP sequence in the format string.
X.P
XEven worse, assuming that the first byte of the multibyte character \*(Cw.X\fP is
Xthe same as the first byte of the multibyte character \*(Cw.Y\fP, after the call:
X.Cb
X	#include <stdio.h>
X	#include <stddef.h>
X	/*...*/
X	wchar_t wstr[50];
X	fscanf(stdin, "a<SI>.Y<SO>%S", wstr);
X.Ce
Xwith the same input line, \*(Cwstdin\fP will be left with a partially consumed
Xmultibyte character.
X.mc
EOF
chmod 666 format.mm