


_XConvertWCToMB(3X11)					_XConvertWCToMB(3X11)
X11R5									X11R5



NAME
  _XConvertWCToMB - conversion from  WC	string to mb string

SYNOPSIS
  iinntt __XXCCoonnvveerrttWWCCTTooMMBB(_x_l_o_c_a_l_e, _w_c__s_t_r, _w_c__l_e_n, _m_b__s_t_r, _m_b__b_y_t_e_s,
  _s_c_a_n_n_e_d__l_e_n)
  XXLLooccaallee _x_l_o_c_a_l_e;;
  wwcchhaarr	*_w_c__s_t_r;;
  iinntt _w_c__l_e_n;;
  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;;
  iinntt *_s_c_a_n_n_e_d__l_e_n;;

ARGUMENTS

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

  _w_c__s_t_r    In:	wchar string.

  _w_c__l_e_n    In:	length of wchar	string,	counted	in wchars.

  _m_b__s_t_r    Out: conversion buffer of result mb	string.

  _m_b__b_y_t_e_s  In/Out: as "In" it is length of buffer mb_str passed by caller;
	    as "Out" it	is the returned	length of converted mb string, both
	    counted in bytes

  _s_c_a_n_n_e_d__l_e_n
	    Out: scanned number	of wchars, counted in wchars

DESCRIPTION
  The __XXCCoonnvveerrttWWCCTTooMMBB converts the wc string to	multibyte string encoded in
  the current locale.  After successful	conversion function will automati-
  cally	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 concatenat-
  able.	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 con-
  verted 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 character
    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 __XXCCoonnvveerrttWWCCTTooMMBB 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
       String was terminated at	an 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
































