_XConvertWCToMB(3X11) X11R5 _XConvertWCToMB(3X11)NAME
_XConvertWCToMB - conversion from WC string to mb string
SYNOPSIS
int _XConvertWCToMB(xlocale, wc_str, wc_len, mb_str, mb_bytes,
scanned_len)
XLocale xlocale;
wchar *wc_str;
int wc_len;
unsigned char *mb_str;
int *mb_bytes;
int *scanned_len;
ARGUMENTS
xlocale In: specifies locale, the default NULL is the current locale.
wc_str In: wchar string.
wc_len In: length of wchar string, counted in wchars.
mb_str Out: conversion buffer of result mb string.
mb_bytes In/Out: as "In" it is length of buffer mb_str passed by call‐
er; as "Out" it is the returned length of converted mb
string, both counted in bytes
scanned_len
Out: scanned number of wchars, counted in wchars
DESCRIPTION
The _XConvertWCToMB converts the wc string to multibyte string encoded
in the current locale. After successful conversion function will auto‐
matically append a null to mb_str if more room in output buffer mb_str.
This null character is not counted in length of mb string.
When function returns at any time, scanned_len always remembers where
stopped.
The caller of this function has to provide the output buffer mb_str.
By using scanned_len, the caller can break a large wchar string into
pieces, and convert one piece at a time. The result of mb string is
concatenatable. However concatenation may produce redundant designation
sequence if the codeset is state-dependent.
The function returns BadBuffer meaning that the output buffer mb_str
was exhausted. In this case function ensure that the mb_str stores
already converted mb string; mb_bytes stores number of bytes of mb_str;
the scanned_len stores the number of already processed wchars. Caller
can move wc_str to (wc_str + *scanned_len) for next conversion.
The function returns a number greater than zero meaning a BadEncoding,
the unconvertable codes in wchar string were met. In this case the
function will automatically recover the wrong code with the following
algorithm:
If a byte of wchar code is wrong, replace it with the minimum charac‐
ter of the current encoding.
Then function continues to do conversion.
Both the WNULL character and wc_len will terminate the conversion.
All errors are defined less than zero, i.e.:
#define Success 0
#define BadBuffer -1
#define BadTerminate -2
#define BadEncoding -3
RETURNED VALUE
The _XConvertWCToMB returns the following value:
Success
successful conversion.
BadBuffer
buffer was exhausted.
BadEncoding
wrong codepoints can not be recovered.
> 0 number of wrong codepoints, but recovered.
SEE ALSO
Refer to "CT and WC" for their definitions.
_XConvertWCToMB(3X11)
