


_XConvertMBToCT(3X11)					_XConvertMBToCT(3X11)
X11R5									X11R5



NAME
  _XConvertMBToCT - conversion from mb string to CT

SYNOPSIS
  iinntt __XXCCoonnvveerrttMMBBTTooCCTT(_x_l_o_c_a_l_e, _m_b__s_t_r, _m_b__b_y_t_e_s, _c_t__s_t_r, _c_t__b_y_t_e_s,
  _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;;
  cchhaarr *_m_b__s_t_r;;
  iinntt _m_b__b_y_t_e_s;;
  cchhaarr *_c_t__s_t_r;;
  iinntt *_c_t__b_y_t_e_s;;
  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 string, counted in	bytes.

  _c_t__s_t_r    Out: conversion buffer of result CT	string.

  _c_t__b_y_t_e_s  In/Out: as "In" it is length of buffer ct_str passed by caller;
	    as "Out" it	is the returned	length of converted CT string, both
	    counted in bytes.

  _s_c_a_n_n_e_d__b_y_t_e_s
	    Out: scanned number	of bytes of mb_str,

  _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oCCTT converts the multibyte string encoded in the specified
  _x_l_o_c_a_l_e to CT	string.	 After a successful conversion the default state
  designation of CT (usually it's Latin-1 GL) will be appended at ct_str if
  the last state is not	default	state.	And function will automatically
  append a null	character to ct_str if more room in output buffer ct_str.
  This null character is not counted in	length of CT string.

  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 ct_str.	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.  The	result of CT string is con-
  catenatable. However concatenation may produce redundant designation
  sequence.

  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 specified	_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oCCTT((NNUULLLL,, mmbb__bbyytteess,, wwcc__ssttrr,,
		   &&mmbb__bbyytteess,, &&ssccaannnneedd))

  The function returns BadBuffer meaning that the output buffer	ct_str was
  exhausted. In	this case function ensure that the ct_str stores already con-
  verted CT string; ct_bytes stores number of bytes of ct_str; the
  scanned_bytes	stores the number of already processed mb string. Caller can
  move mb_str to (mb_str + *scanned_bytes) for next conversion.

  The function returns a number	greater	than zero meaning a BadEncoding, the
  unconvertable	codes in mb string were	met.  In this case the function	will
  automatically	recover	the wrong code with the	following algorithm:

    If a byte of mb codepoint is wrong,	replace	it with	the minimum byte of
    the	character encoded in the current charset.

  Then function	continues to do	conversion.

  Both the null	character and mb_bytes 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 __XXCCoonnvveerrttMMBBTTooCCTT rreettuurrnnss tthhee ffoolllloowwiinngg vvaalluuee::

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

  BBaaddBBuuffffeerr
       buffer 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

















