From kido@vnet.ibm.com Wed Oct  7 07:32:36 1992
Received: from vnet.ibm.com by dkuug.dk via EUnet with SMTP (5.64+/8+bit/IDA-1.2.8)
	id AA20246; Wed, 7 Oct 92 07:32:36 +0100
Message-Id: <9210070632.AA20246@dkuug.dk>
Received: from YMTVM8 by vnet.ibm.com (IBM VM SMTP V2R2) with BSMTP id 4824;
   Wed, 07 Oct 92 02:35:02 EDT
Date: Wed, 7 Oct 92 15:31:59 JST
From: "Akio    Kido" <kido@vnet.ibm.com>
To: sc22wg20@dkuug.dk, sc22wg15@dkuug.dk, sig-international@osf.org
Subject: mse.trf.3
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- exmbfunc.mm
#
sed "s/^X//" > exmbfunc.mm << 'EOF'
X.mc |
X'\".pH "EXTENDED MULTIBYTE FUNCTIONS"
X.H 2 "Extended Multibyte Functions"
X.P
XAn object of type
X.Cf mbstate_t
Xinitialized to zero (explicitly or implicitly) describes the
Xinitial conversion state.
XThe
X.Cf mbstate_t
Xobject will be affected by the
X.Cf LC_CTYPE
Xcategory of the current locale when the
X.Cf mbrlen
Xor
X.Cf mbrtowc
Xis called with the last argument pointing to the
X.Cf mbstate_t
Xobject which describes initial conversion state.
X.P
XIf the argument to
X.Cf mbrlen ,
X.Cf mbrtowc
Xor
X.Cf mbsrtowcs
Xencounters an invalid multibyte character,
Xor if
X.Cf wcrtomb
Xor
X.Cf wcsrtombs
Xdoes not correspond to a valid multibyte character,
Xan encoding error occurs,
Xand the value of the macro
X.Cf EILSEQ
Xis stored in
X.Cf errno .
X.H 3 "The \f(CBsisinit\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	int sisinit(mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf sisinit
Xfunction tests for any
X.Cf mbstate_t
Xobject that corresponds to the initial shift state.
X.HU "Returns"
X.P
XIf \*(Cwps\fP is not a null pointer,
Xthe
X.Cf sisinit
Xfunction returns nonzero if and only if the object pointed
Xto by \*(Cwps\fP describes initial shift state.
XIf \*(Cwps\fP is a null pointer,
Xit always returns nonzero.
X.H 3 "Restartable Multibyte Character Functions"
X.P
XThese functions differ from the corresponding multibyte character
Xfunctions of \*(AC (
X.Cf mblen ,
X.Cf mbtowc ,
Xand
X.Cf wctomb )
Xin that they have an additional parameter of type pointer to
X.Cf mbstate_t
Xthat describes the current conversion state of the
Xassociated multibyte character or wide character sequence.
XAlso,
Xunlike their corresponding functions,
Xwhen the pointer to multibyte character is a null pointer,
Xthe
X.Cf mbstate_t
Xobject is not reset to the initial conversion state and the
Xreturn value does not represent whether the encoding is
Xstate-dependent.
X.H 4 "The \f(CBmbrlen\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	int mbrlen(const char *s, size_t n, mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf mbrlen
Xfunction is equivalent to
X.Cb
X	mbrtowc((wchar_t *)0, s, n, ps)
X.Ce
X.P
XIf the encoding is state-dependent,
Xon entry the
X.Cf mbrlen
Xfunction takes the conversion state described in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP as current,
Xand then alters the contents of the
X.Cf mbstate_t
Xobject as necessary if \*(Cws\fP is not a null pointer.
X.P
XIf \*(Cwps\fP is a null pointer,
Xthe
X.Cf mbrlen
Xfunction behaves as if the
X.Cf mblen
Xfunction of \*(AC were called,
Xexcept that if \*(Cws\fP is a null pointer the return value
Xdoes not represent whether the state is state-dependent.
X.HU "Returns"
X.P
XIf \*(Cws\fP is a null pointer,
Xthe
X.Cf mbrlen
Xfunction returns the number of bytes needed to return to the
Xinitial shift state (zero if encodings are not
Xstate-dependent or if the shift state in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP is the initial).
XOtherwise,
Xthe
X.Cf mbrlen
Xfunction returns 0 (if \*(Cws\fP points to a null character),
Xor returns the number of bytes that are contained in the
Xmultibyte character pointed to by \*(Cws\fP (if the next
X\*(Cwn\fP or fewer bytes form a valid multibyte character),
Xor returns \-1 (if encoding error occurs).
X.rF
Xthe
X.Cf mbrtowc
Xfunction (3.8.2.2).
X.H 4 "The \f(CBmbrtowc\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	int mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf mbrtowc
Xfunction is similar to the
X.Cf mbtowc
Xfunction of \*(AC except that the conversion state is
Xdescribed by an
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP instead of being internal to
Xthe function,
Xand if \*(Cws\fP is a null pointer,
Xthe conversion state is not reset and instead the number of
Xbytes needed to return to the initial shift state is determined.
X.P
XIf the encoding is state-dependent,
Xon entry the
X.Cf mbrtowc
Xfunction takes the conversion state described in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP as current,
Xand then alters the contents of the
X.Cf mbstate_t
Xobject as necessary if \*(Cws\fP is not a null pointer.
X.P
XIf \*(Cwps\fP is a null pointer,
Xthe
X.Cf mbrtowc
Xfunction behaves as if the
X.Cf mbtowc
Xfunction of \*(AC were called,
Xexcept that if \*(Cws\fP is a null pointer the return value
Xdoes not represent whether the state is state-dependent.
X.HU "Returns"
X.P
XIf \*(Cws\fP is a null pointer,
Xthe
X.Cf mbrtowc
Xfunction returns the number of bytes needed to return to the
Xinitial shift state (zero if encodings are not
Xstate-dependent or if the shift state described in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP is the initial).
XOtherwise,
Xthe
X.Cf mbrtowc
Xfunction returns 0 (if \*(Cws\fP points to a null character),
Xor returns the number of bytes that are contained in the
Xmultibyte character pointed to by \*(Cws\fP (if the next
X\*(Cwn\fP or fewer bytes form a valid multibyte character),
Xor returns \-1 (if encoding error occurs).
X.P
XIn no case will the value returned be greater than \*(Cwn\fP
Xor the value of the
X.Cf MB_CUR_MAX
Xmacro.
X.H 4 "The \f(CBwcrtomb\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	int wcrtomb(char *s, wchar_t wc, mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf wcrtomb
Xfunction is similar to the
X.Cf wctomb
Xfunction of \*(AC except that the conversion state is
Xdescribed by a
X.Cf mbstate_t
Xobject pointed to by ps instead of being internal to the
Xfunction,
Xand if \*(Cws\fP is a null pointer,
Xthe conversion state is not reset and instead the number of
Xbytes needed to return to the initial shift state is determined.
X.P
XIf the encoding is state-dependent,
Xon entry the
X.Cf wcrtomb
Xfunction takes the conversion state described in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP as current,
Xand then alters the contents of the
X.Cf mbstate_t
Xobject as necessary if \*(Cws\fP is not a null pointer.
X.P
XIf \*(Cwps\fP is a null pointer,
Xthe
X.Cf wcrtomb
Xfunction behaves as if the
X.Cf wctomb
Xfunction of \*(AC were called,
Xexcept that if \*(Cws\fP is a null pointer the return value
Xdoes not represent whether the state is state-dependent.
X.HU "Returns"
X.P
XIf \*(Cws\fP is a null pointer,
Xthe
X.Cf wcrtomb
Xfunction returns the number of bytes needed to return to the
Xinitial shift state (zero if encodings are not
Xstate-dependent or if the shift state described in the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP is the initial).
XOtherwise,
Xthe
X.Cf wcrtomb
Xfunction returns \-1 (if encoding error occurs),
Xor returns the number of bytes stored in the array pointed
Xto by \*(Cws\fP.
XThe bytes stored are the multibyte character corresponding
Xto the value of \*(Cwwc\fP including any change in conversion state.
X.P
XIn no case will the value returned be greater than the value
Xof the
X.Cf MB_CUR_MAX
Xmacro.
X.H 3 "Restartable Multibyte String Functions"
X.P
XThese functions differ from the corresponding multibyte
Xstring functions of \*(AC (
X.Cf mbstowcs
Xand
X.Cf wcstombs )
Xin that they have two additional parameters.
XThe first additional parameter is a pointer to a pointer into
Xwhich is stored the address of the next element to be converted;
Xthe second additional parameter is a pointer to an
X.Cf mbstate_t
Xobject that describes the current conversion state of the
Xassociate multibyte or wide character string.
X.H 4 "The \f(CBmbsrtowcs\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	size_t mbsrtowcs(wchar_t *dst, const char *src, size_t len,
X		char **ptr, mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf mbsrtowcs
Xfunction converts a sequence of multibyte characters that
Xbegin in the conversion state described in an
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP from the array pointed to by
X\*(Cwsrc\fP into a sequence of corresponding codes,
Xwhich,
Xif \*(Cwdst\fP is not a null pointer,
Xare then stored into the array pointed to by \*(Cwdst\fP.
XConversion continues up to,
Xbut not including,
Xa terminating null character.
XConversion will stop earlier in two cases:
Xwhen a sequence of bytes are reached that do not form a
Xvalid multibyte character,
Xor (if \*(Cwdst\fP is not a null pointer) when \*(Cwlen\fP
Xcodes have been stored into the array pointed to by
X\*(Cwdst\fP.
XEach conversion takes place as if by a call to the
X.Cf mbrtowc
Xfunction.
X.P
XIf both \*(Cwdst\fP and \*(Cwptr\fP are not null pointers,
Xthe object pointed to by \*(Cwptr\fP will be assigned either
Xa null pointer (if conversion stopped due to reaching a
Xterminating null character) or the address just past the
Xlast multibyte character converted.
XIf \*(Cwdst\fP is not a null pointer,
Xthe contents of the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP will be changed to match the
Xconversion state when conversion stopped;
Xif conversion stopped due to reaching a terminating null
Xcharacter,
Xthe initial shift state will be described.
X.P
XIf \*(Cwps\fP is a null pointer,
Xthe
X.Cf mbsrtowcs
Xbehaves as if the
X.Cf mbstowcs
Xfunction of \*(AC were called,
Xexcept that they are restartable so far as the
X.Cf LC_CTYPE
Xcategory of the current locale is not changed.
X.HU "Returns"
X.P
XIf a sequence of bytes are reached that do not form a valid
Xmultibyte character,
Xthe
X.Cf mbsrtowcs
Xreturns
X.Cf (size_t)-1 .
XOtherwise,
Xit returns the number of multibyte characters converted,
Xwhich is the same as the number of array elements modified
Xwhen \*(Cwdst\fP is not a null pointer.
X.P
XIf \*(Cwdst\fP is a null pointer,
Xthe
X.Cf mbsrtowcs
Xfunction returns the number of elements required for the
Xwide character array.
X.H 4 "The \f(CBwcstombs\fP Function"
X.HU "Synopsis"
X.Cb
X	#include <wchar.h>
X	size_t wcsrtombs(char *dst, const wchar_t *src, size_t len,
X                     wchar_t **ptr, mbstate_t *ps);
X.Ce
X.HU "Description"
X.P
XThe
X.Cf wcsrtombs
Xfunction converts a sequence of wide character codes from
Xthe array pointed to by \*(Cwsrc\fP into a sequence of
Xcorresponding multibyte characters that begin in the
Xconversion state described in an
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP,
Xwhich,
Xif \*(Cwdst\fP is not a null pointer,
Xare then stored into the array pointed to by \*(Cwdst\fP.
XConversion continues up to,
Xbut not including,
Xa terminating zero code.
XConversion will stop earlier in two cases:
Xwhen a code is reached that does not correspond to a valid
Xmultibyte character,
Xor (if \*(Cwdst\fP is not a null pointer) when the next
Xmultibyte character would exceed the limit of len total
Xbytes to be stored into the array pointed to by \*(Cwdst\fP.
XEach conversion takes place as if by a call to the
X.Cf wcrtomb
Xfunction.
X.P
XIf both \*(Cwdst\fP and \*(Cwptr\fP are not null pointers,
Xthe object pointed to by \*(Cwptr\fP will be assigned either
Xa null pointer (if conversion stopped due to reaching a
Xterminating zero code) or the address of the code just past
Xthe last converted.
XIf \*(Cwdst\fP is not a null pointer,
Xthe contents of the
X.Cf mbstate_t
Xobject pointed to by \*(Cwps\fP will be changed to match the
Xconversion state when conversion stopped;
Xif conversion stopped due to reaching a terminating zero code,
Xthe initial shift state will be described.
X.HU "Returns"
X.P
XIf a code is reached that does not correspond to a valid
Xmultibyte character,
Xthe
X.Cf wcsrtombs
Xfunction returns
X.Cf (size_t)-1 .
XOtherwise,
Xit returns the number of bytes in the resulting multibyte
Xcharacter sequence,
Xwhich is the same as the number of array elements modified
Xwhen \*(Cwdst\fP is not a null pointer.
X.P
XIf \*(Cwdst\fP is a null pointer,
Xthe
X.Cf wcsrtombs
Xfunction returns the number of bytes required for the
Xcharacter array.
X.mc
EOF
chmod 666 exmbfunc.mm