XConvertCTToMB man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

_XConvertCTToMB(3X11)		     X11R5		 _XConvertCTToMB(3X11)

NAME
       _XConvertCTToMB - conversion from CT string to multibyte string

SYNOPSIS
       int _XConvertCTToMB(xlocale, ct_str, ct_bytes, mb_str, mb_bytes,
       scanned_bytes, state)
       XLocale xlocale;
       unsigned char *ct_str;
       int ct_bytes;
       unsigned char *mb_str;
       int *mb_bytes;
       int *scanned_bytes;
       _State *state;

ARGUMENTS
       xlocale	 In: specifies locale, the default NULL is the current locale.

       ct_str	 In: multibyte string.

       mb_bytes	 In: length of mb strings, counted in bytes.

       ct_str	 Out: conversion buffer of result CT string.

       ct_bytes	 In/Out: as "In" it is length of buffer ct_str passed by call‐
		 er; as "Out" it  is  the  returned  number  of	 converted  CT
		 string, counted in bytes.

       scanned_bytes
		 Number of mb bytes converted when the function returns.

       state	 In/Out:  as  "In"  it is the state at the beginning of the CT
		 string; as "Out" it is the current state stopped at last con‐
		 verted CT encoding.  The state is defined internally by Xlib.
		 If this pointer is null, the function will assume  the	 state
		 to be the default CT state. Of course, nothing will be put in
		 the null pointer. Do not modify or free this  data  which  is
		 owned by the Xlib.

DESCRIPTION
       The _XConvertCTToMB converts the string encoded in CT to string encoded
       in the specified xlocale.  After	 a  successful	conversion,  the  null
       character  '\0' will be appended to mb_str if there is more room for it
       in the buffer.  The null character of  mb  string  is  not  counted  in
       length of output buffer mb_bytes.

       The  returned state will point to a state of the encoding in the inter‐
       nal table, so do not modify or free this pointer.

       When function returns at any time, scanned_bytes always remembers where
       stopped,	 and  state always remembers the current CT state if it is not
       null pointer.

       The caller of this function has to provide the  output  buffer  mb_str,
       and  store  the	buffer	length	into  mb_bytes	as  input.   By	 using
       scanned_bytes and state, the caller can break a large  CT  string  into
       pieces, and convert one piece at a time.

       In other hand caller can pass any broken CT string to this function for
       doing conversion.  For example, caller can still be trying  of  conver‐
       sion when the error BadBuffer is occurred(output buffer was exhausted).
       Usually, the application passes the NULL to state for first  conversion
       as following:

	      char *state = NULL;
	      _XConvertCTToMB(NULL, ct_str, ct_len, mb_str,
			  &mb_len, &scanned, &state)

       If  the	value  of  state is invalid or null-pointer, the function will
       suppose the default state of CT as initial.  The default state of CT is
       defined in 3 cases of encoding:

	 1. no control sequence, GL and GR of Latin-1 is supposed.

	 2.  control  sequence	of  Latin-1 GL only, GR of Latin-1 is supposed
	 too.

	 3. control sequence of Latin-1 GR only, GL  of	 Latin-1  is  supposed
	 too.

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

       Only in both the case of BadBuffer and BadTerminate the caller can move
       pointer	ct_str	to (ct_str + *scanned_bytes), then continue to do con‐
       version.	 And function ensure that the mb_str stores the	 already  con‐
       verted  mb  string;  mb_bytes  counts  the number of them in bytes; the
       state stores the last state of encoding.

       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
       conversion untill one of the results Success,  BadTerminate,  BadBuffer
       or BadEncoding is met.

       The  function  returns BadEncoding meaning for unrecoverable wrong code
       which is wrong escape sequence, or not registered by system yet.

       Both the null character and ct_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 _XConvertCTToMB will return the following values:

       Success
	      successful conversion.

       BadBuffer
	      output buffer(mb_str) was exhausted.

       BadTerminate
	      CT string was terminated uncompletely.

       BadEncoding
	      wrong codepoints can not be recovered.

       > 0    number of wrong codepoints, but recovered.

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

							 _XConvertCTToMB(3X11)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net