KICONV man page on SmartOS

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

KICONV(9F)							    KICONV(9F)

NAME
       kiconv - buffer-based code conversion function

SYNOPSIS
       #include <sys/types.h>
       #include <sys/errno.h>
       #include <sys/sunddi.h>

       size_t kiconv(kiconv_t cd, char **inbuf, size_t *inbytesleft,
	    char **outbuf, size_t *outbytesleft, int *errno);

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI).

PARAMETERS
       The parameters for the kiconv function are as follows:

       cd
		       Code  conversion descriptor indicating the code conver‐
		       sion and conversion state.

       inbuf
		       Points to an address of a buffer containing a  sequence
		       of character bytes in fromcode codeset to be converted.
		       After the conversion, the variable is updated to	 point
		       to  the	byte following the last byte that was success‐
		       fully used in the conversion.

       inbytesleft
		       As an input parameter, the number of bytes to  be  con‐
		       verted  in inbuf. As an output parameter, the number of
		       bytes in inbuf still not converted  after  the  conver‐
		       sion.

       outbuf
		       Points  to an address of a buffer where converted char‐
		       acter bytes in tocode codeset can be saved.  After  the
		       conversion,  the	 variable  is  updated to point to the
		       byte following the last byte of converted output data.

       outbytesleft
		       As an input parameter, the number of available bytes at
		       outbuf where converted character bytes can be saved. As
		       an output parameter, the number of bytes	 still	avail‐
		       able at outbuf after the conversion.

       errno
		       Indicates the error when conversion is not completed or
		       failed. The following are possible values:

		       EILSEQ
				    The input conversion was stopped due to an
				    input  byte	 that  does  not belong to the
				    input codeset.

		       E2BIG
				    The input conversion was  stopped  due  to
				    lack of space in the output buffer.

		       EINVAL
				    The input conversion was stopped due to an
				    incomplete character or shift sequence  at
				    the end of the input buffer.

		       EBADF
				    The cd input parameter is not a valid open
				    code conversion descriptor.

DESCRIPTION
       The kiconv() function converts the  sequence  of	 characters  from  one
       codeset,	 in  the  array	 specified by inbuf, into a sequence of corre‐
       sponding characters in another codeset, in the array specified by  out‐
       buf.  The  codesets  are those specified in the kiconv_open() call that
       returned the code conversion descriptor, cd. The inbuf parameter points
       to  a  variable	that points to the first character in the input buffer
       and inbytesleft indicates the number of bytes to the end of the	buffer
       to  be converted. The outbuf parameter points to a variable that points
       to the first available byte in the output buffer and outbytesleft indi‐
       cates the number of the available bytes to the end of the buffer.

       For  state-dependent  encodings, the conversion descriptor cd is placed
       into its initial shift state by a  call	for  which  inbuf  is  a  null
       pointer,	 or for which inbuf points to a null pointer. When kiconv() is
       called in this way, and if outbuf is not a null pointer or a pointer to
       a  null	pointer, and outbytesleft points to a positive value, kiconv()
       places, if any, into the output buffer, the byte sequence to change the
       output  buffer  to its initial shift state. If the output buffer is not
       large enough to hold the entire reset sequence, kiconv() fails and sets
       errno  to  E2BIG.  Subsequent  calls  with  inbuf  as other than a null
       pointer or a pointer to a null pointer cause  the  conversion  to  take
       place from the current state of the conversion descriptor.

       If  a  sequence	of  input bytes does not form a valid character in the
       specified codeset, conversion stops  after  the	previous  successfully
       converted  character. If the input buffer ends with an incomplete char‐
       acter or shift sequence, conversion stops after the  previous  success‐
       fully converted bytes. If the output buffer is not large enough to hold
       the entire converted input, conversion stops just prior	to  the	 input
       bytes  that  would  cause  the  output buffer to overflow. The variable
       pointed to by inbuf is updated to point to the byte following the  last
       byte that was successfully used in the conversion. The value pointed to
       by inbytesleft is decremented to reflect the number of bytes still  not
       converted  in  the  input  buffer. The variable pointed to by outbuf is
       updated to point to the byte following the last byte of converted  out‐
       put  data.  The	value  pointed	to  by	outbytesleft is decremented to
       reflect the number of bytes still available in the output  buffer.  For
       state-dependent	encodings,  the	 conversion  descriptor	 is updated to
       reflect the shift state in effect at the end of the  last  successfully
       converted byte sequence.

       If  kiconv()  encounters a character in the input buffer that is legal,
       but for which an identical character does not exist in the target code‐
       set, kiconv() performs an implementation-defined conversion (that is, a
       non-identical conversion) on this character.

RETURN VALUES
       The kiconv() function updates the variables pointed to by  the  parame‐
       ters  to reflect the extent of the conversion and returns the number of
       non-identical conversions performed. If the entire string in the	 input
       buffer  is  converted, the value pointed to by inbytesleft is 0. If the
       input conversion is stopped due to any conditions mentioned above,  the
       value  pointed  to by inbytesleft is non-zero and errno is set to indi‐
       cate the condition.  If such and other error occurs,  kiconv()  returns
       (size_t)-1 and sets errno to indicate the error.

CONTEXT
       kiconv() can be called from user or interrupt context.

EXAMPLES
       Example 1 Performing a Simple Conversion

       The  following  example	shows how to perform a simple conversion using
       kiconv() with a limited size of output buffer:

	 #include <sys/types.h>
	 #include <sys/errno.h>
	 #include <sys/sunddi.h>

	 int
	 doconversion(char *fromcode, char *tocode, char *inbuf, char *outbuf,
			 size_t inlen, size_t *outlen)
	 {
		 kiconv_t cd;
		 size_t ileft, ret;
		 int err;

		 cd = kiconv_open((const char *)tocode, (const char *)fromcode);
		 if (cd == (kiconv_t)-1) {
			/* Cannot open conversion. */
			return (-1);
		 }

		 ret = kiconv(cd, &inbuf, &inlen, &outbuf, outlen, &err);
		 if (ret == (size_t)-1)
			 goto doconv_error_return;

		 /*
		  * Reset the conversion descriptor. This will also
		  * make sure to write to output buffer any saved bytes
		  * in the conversion descriptor state.
		  */
		 ileft = 0;
		 ret = kiconv(cd, (char *)NULL, &ileft, &outbuf, outlen, &err);
		 if (ret == (size_t)-1)
			 goto doconv_error_return;

		 (void) kiconv_close(cd);

		 return (0);

	 doconv_error_return:
		 (void) kiconv_close(cd);

		 /* Need more output buffer. */
		 if (err == E2BIG)
			 return (-2);

		 /* Illegal sequence? */
		 if (err == EILSEQ)
			 return (-3);

		 /* Incomplete character? */
		 if (err == EINVAL)
			 return (-4);

		 /*
		  * Bad code conversion descriptor or any other unknown error.
		  */
		 return (-5);
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Committed	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       iconv(3C),     iconv_close(3C),	   iconv_open(3C),	u8_strcmp(3C),
       u8_textprep_str(3C),	   u8_validate(3C),	   uconv_u16tou32(3C),
       uconv_u16tou8(3C),	 uconv_u32tou16(3C),	    uconv_u32tou8(3C),
       uconv_u8tou16(3C),   uconv_u8tou32(3C),	attributes(5),	kiconvstr(9F),
       kiconv_close(9F), kiconv_open(9F), u8_strcmp(9F),  u8_textprep_str(9F),
       u8_validate(9F),		uconv_u16tou32(9F),	    uconv_u16tou8(9F),
       uconv_u32tou16(9F),	  uconv_u32tou8(9F),	    uconv_u8tou16(9F),
       uconv_u8tou32(9F)

       The Unicode Standard:

       http://www.unicode.org/standard/standard.html

NOTES
       The  iconv(3C) man page also has a good example code that can be refer‐
       enced.

				 Oct 16, 2007			    KICONV(9F)
[top]

List of man pages available for SmartOS

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