


_XConvertMBToWC(3X11)					_XConvertMBToWC(3X11)
X11R5									X11R5



NAME
  _XConvertMBToWC - conversion from  CT	string to mb string.

SYNOPSIS
  iinntt __XXCCoonnvveerrttMMBBTTooWWCC(_x_l_o_c_a_l_e, _m_b__s_t_r, _m_b__b_y_t_e_s, _w_c__s_t_r, _w_c__l_e_n,
  _s_c_a_n_n_e_d__b_y_t_e_s, _s_t_a_t_e)
  XXLLooccaallee _x_l_o_c_a_l_e;;
  uunnssiiggnneedd cchhaarr	*_m_b__s_t_r;;
  iinntt _m_b__b_y_t_e_s;;
  wwcchhaarr	*_w_c__s_t_r;;
  iinntt *_w_c__l_e_n;;
  iinntt *_s_c_a_n_n_e_d__b_y_t_e_s;;
  __SSttaattee *_s_t_a_t_e;;

ARGUMENTS

  _x_l_o_c_a_l_e   In:	specifies locale, the default NULL is the current locale.

  _m_b__s_t_r    In:	multibyte string.

  _m_b__b_y_t_e_s  In:	length of mb strings, counted in bytes.

  _w_c__s_t_r    Out: conversion buffer of result wchar string.

  _w_c__l_e_n    In/Out: as "In" it is length of buffer wc_str passed by caller;
	    as "Out" it	is the returned	number of converted wchars.

  _s_c_a_n_n_e_d__b_y_t_e_s
	    Number of mb bytes converted when the function returns.

  _s_t_a_t_e	    In/Out: as "In" it is the state at the beginning of	mb string; as
	    "Out" it is	the current state stopped at the last converted	mb
	    string.

DESCRIPTION
  The __XXCCoonnvveerrttMMBBTTooWWCC converts the multibyte string encoded in the specified
  _x_l_o_c_a_l_e to wchar string.  After a successful conversion, the null character
  WNULL	will be	appended to wc_str if there is room for	it in the buffer.
  The terminator WNULL of wchar	string is not counted in length	of output
  buffer wc_len.

  When function	returns	at any time, scanned_bytes always remembers where
  stopped, and _s_t_a_t_e always remembers the current state	of _x_l_o_c_a_l_e if it is
  state-dependent codeset.

  The caller of	this function has to provide the output	buffer wc_str, and
  store	the buffer length (in wchars) into wc_len as input. By using
  _s_c_a_n_n_e_d__b_y_t_e_s	and _s_t_a_t_e, the caller can break	a large	mb string into
  pieces, and convert one piece	at a time.

  In other hand	caller can pass	any broken mb string to	this function for
  doing	conversion.  For example, caller can still be trying of	conversion
  when the error BadBuffer is occurred(output buffer was exhausted).  If the
  codeset of the _x_l_o_c_a_l_e is state dependent and	the mb_str is passed as	NULL
  pointer, the function	will set initial state in the _x_l_o_c_a_l_e.	Usually, the
  application should calls it with NULL	mb_str for first conversion as the
  following:

       __XXCCoonnvveerrttMMBBTTooWWCC((NNUULLLL,, mmbb__bbyytteess,, wwcc__ssttrr,,
		   &&mmbb__lleenn,, &&ssccaannnneedd))

  The function returns the BadBuffer meaning that the output buffer wc_str
  was exhausted.  The function returns the BadTerminate	meaning	that the mb
  string is terminated uncompletely, e.g., uncompleted ESC sequence or uncom-
  pleted code point ended at tail of mb_str.

  Only in both the case	of BadBuffer and BadTerminate the caller can move
  pointer mb_str to (mb_str + *scanned_bytes), then continue to	do conver-
  sion.	 And function ensure that the wc_str stores the	already	converted
  wchar	string;	wc_len counts the number of them in wchars(not bytes);

  The function returns a number	greater	than zero meaning a number of wrong
  codepoints recovered by the function.	 The wrong codepoint will be
  recovered with the first codepoint of	the charset at which the wrong
  codepoint occurs.  After replaced, the function will continue	to do conver-
  sion until one of the	results	Success, BadTerminate, BadBuffer or BadEncod-
  ing is met.

  Both the null	character and mb_bytes will terminate the conversion.

  All error status are defined to be less than zero, i.e.:

    #define Success	     0

    #define BadBuffer	    -1

    #define BadTerminate    -2

    #define BadEncoding	    -3

RETURNED VALUE
  The __XXCCoonnvveerrttMMBBTTooWWCC wwiillll rreettuurrnn tthhee ffoolllloowwiinngg	vvaalluueess::

  SSuucccceessss
       successful conversion.

  BBaaddBBuuffffeerr
       output buffer(wc_str) was exhausted.

  BBaaddTTeerrmmiinnaattee
       mb_str terminated at uncomplete codepoint.

  BBaaddEEnnccooddiinngg
       wrong codepoints	can not	be recovered.

  >> 00  number of wrong codepoints, but recovered.

SEE ALSO
  Refer	to "CT and WC" for their definitions.  delim off















