---
name: "unicode_convert"
section: "3"
platform: "linux"
package: "libcourier-unicode-dev"
version: "2.3.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/unicode_u_ucs4_native"
---

# unicode\_convert(3)

unicode character set conversion

Part of [unicode\_u\_ucs4\_native(3)](/unicode_u_ucs4_native/3.md).

## NAME

unicode\_u\_ucs4\_native, unicode\_u\_ucs2\_native, unicode\_convert\_init, unicode\_convert, unicode\_convert\_deinit, unicode\_convert\_tocbuf\_init, unicode\_convert\_tou\_init, unicode\_convert\_fromu\_init, unicode\_convert\_uc, unicode\_convert\_tocbuf\_toutf8\_init, unicode\_convert\_tocbuf\_fromutf8\_init, unicode\_convert\_toutf8, unicode\_convert\_fromutf8, unicode\_convert\_tobuf, unicode\_convert\_tou\_tobuf, unicode\_convert\_fromu\_tobuf - unicode character set conversion

## SYNOPSIS

```
#include <courier-unicode.h>
	    extern const char unicode_u_ucs4_native[];
	    extern const char unicode_u_ucs2_native[];
```

**unicode\_convert\_handle\_t unicode\_convert\_init(const char \****src\_chset***, const char \****dst\_chset***, void \****cb\_arg***);**

**int unicode\_convert(unicode\_convert\_handle\_t** *handle***, const char \****text***, size\_t** *cnt***);**

**int unicode\_convert\_deinit(unicode\_convert\_handle\_t** *handle***, int \****errptr***);**

**unicode\_convert\_handle\_t unicode\_convert\_tocbuf\_init( const char \****src\_chset***, const char \****dst\_chset***, char \*\****cbufptr\_ret***, size\_t \****cbufsize\_ret***, int** *nullterminate***);**

**unicode\_convert\_handle\_t unicode\_convert\_tocbuf\_toutf8\_init( const char \****src\_chset***, char \*\****cbufptr\_ret***, size\_t \****cbufsize\_ret***, int** *nullterminate***);**

**unicode\_convert\_handle\_t unicode\_convert\_tocbuf\_fromutf8\_init( const char \****dst\_chset***, char \*\****cbufptr\_ret***, size\_t \****cbufsize\_ret***, int** *nullterminate***);**

**unicode\_convert\_handle\_t unicode\_convert\_tou\_init( const char \****src\_chset***, char32\_t \*\****ucptr\_ret***, size\_t \****ucsize\_ret***, int** *nullterminate***);**

**unicode\_convert\_handle\_t unicode\_convert\_fromu\_init( const char \****dst\_chset***, char \*\****cbufptr\_ret***, size\_t \****cbufsize\_ret***, int** *nullterminate***);**

**int unicode\_convert\_uc(unicode\_convert\_handle\_t** *handle***, const char32\_t \****text***, size\_t** *cnt***);**

**char \*unicode\_convert\_toutf8(const char \****text***, const char \****charset***, int \****error***);**

**char \*unicode\_convert\_fromutf8(const char \****text***, const char \****charset***, int \****error***);**

**char \*unicode\_convert\_tobuf(const char \****text***, const char \****charset***, const char \****dstcharset***, int \****error***);**

**int unicode\_convert\_toubuf(const char \****text***, size\_t** *text\_l***, const char \****charset***, char32\_t \*\****uc***, size\_t \****ucsize***, int \****error***);**

**int unicode\_convert\_fromu\_tobuf(const char32\_t \****utext***, size\_t** *utext\_l***, const char \****charset***, char \*\****c***, size\_t \****csize***, int \****error***);**

## DESCRIPTION

*unicode\_u\_ucs4\_native*\[\] contains the string “UCS-4BE” or “UCS-4LE”, matching the native char32\_t endianness.

*unicode\_u\_ucs2\_native*\[\] contains the string “UCS-2BE” or “UCS-2LE”, matching the native char32\_t endianness.

**unicode\_convert\_init**(), **unicode\_convert**(), and **unicode\_convert\_deinit**() are an adaption of th [**iconv**(3)](/iconv/3.md) API that uses the same calling convention as the other algorithms in this unicode library, with some value-added features. These functions use [**iconv**(3)](/iconv/3.md) to effect the actual character set conversion.

**unicode\_convert\_init**() returns a non-NULL handle for the requested conversion, or NULL if the requested conversion is not available. **unicode\_convert\_init**() takes a pointer to the output function that receives receives converted character text. The output function receives a pointer to the converted character text, and the number of characters in the converted text. The output function gets repeatedly called, until it receives the entire converted text.

The character text to convert gets passed, repeatedly, to **unicode\_convert**(). Each call to **unicode\_convert**() results in the output function getting invoked, zero or more times, with each successive part of the converted text. Finally, **unicode\_convert\_deinit**() stops the conversion and deallocates the conversion handle.

It's possible that a call to **unicode\_convert\_deinit**() results in some additional calls to the output function, passing the remaining, final parts, of the converted text, before **unicode\_convert\_deinit**() deallocates the handle, and returns.

The output function should return 0 normally. A non-0 return indicates n error condition. **unicode\_convert\_deinit**() returns non-zero if any previous invocation of the output function returned non-zero (this includes any invocations of the output function resulting from this call, or prior **unicode\_convert**() calls), or 0 if all invocations of the output function returned 0.

If the *errptr* is not NULL, \**errptr* gets set to non-zero if there were any conversion errors -- if there was any text that could not be converted to the destination character text.

**unicode\_convert**() also returns non-zero if it calls the output function and it returns non-zero, however the conversion handle remains allocated, so **unicode\_convert\_deinit**() must still be called, to clean that up.

### Collecting converted text into a buffer

Call **unicode\_convert\_tocbuf\_init**() instead of **unicode\_convert\_init**(), then call **unicode\_convert**() and **unicode\_convert\_deinit**() normally. The parameters to **unicode\_convert\_init**() specify the source and the destination character sets. **unicode\_convert\_tocbuf\_toutf8\_init**() is just an alias that specifies UTF-8 as the destination character set. **unicode\_convert\_tocbuf\_fromutf8\_init**() is just an alias that specifies UTF-8 as the source character st.

These functions supply an output function that collects the converted text into a malloc()ed buffer. If **unicode\_convert\_deinit**() returns 0, \**cbufptr\_ret* gets initialized to a malloc()ed buffer, and the number of converted characters, the size of the malloc()ed buffer, get placed into \**cbufsize\_ret*.

**Note**\

If the converted string is an empty string, \**cbufsize\_ret* gets set to 0, but \**cbufptr\_ret* still gets initialized (to a dummy malloced buffer).

A non-zero *nullterminate* places a trailing \\0 character after the converted string (this is included in \**cbufsize\_ret*).

### Converting between character sets and unicode

**unicode\_convert\_tou\_init**() converts character text into a char32\_t buffer. It works just like **unicode\_convert\_tocbuf\_init**(), except that only the source character set gets specified and the output buffer is a char32\_t buffer. *nullterminate* terminates the converted unicode characters with a U+0000.

**unicode\_convert\_fromu\_init**() converts char32\_ts to the output character set, and also works like **unicode\_convert\_tocbuf\_init**(). Additionally, in this case, **unicode\_convert\_uc**() works just like **unicode\_convert**() except that the input sequence is a char32\_t sequence, and the count parameter is th enumber of unicode characters.

### One-shot conversions

**unicode\_convert\_toutf8**() converts the specified text in the specified text into a UTF-8 string, returning a malloced buffer. If *error* is not NULL, even if **unicode\_convert\_toutf8**() returns a non NULL value \**error* gets set to a non-zero value if a character conversion error has occurred, and some characters could not be converted.

**unicode\_convert\_fromutf8**() does a similar conversion from UTF-8 *text* to the specified character set.

**unicode\_convert\_tobuf**() does a similar conversion between two different character sets.

**unicode\_convert\_tou\_tobuf**() calls **unicode\_convert\_tou\_init**(), feeds the character string through **unicode\_convert**(), then calls **unicode\_convert\_deinit**(). If this function returns 0, \**uc* and \**ucsize* are set to a malloced buffer+size holding the unicode char array.

**unicode\_convert\_fromu\_tobuf**() calls **unicode\_convert\_fromu\_init**(), feeds the unicode array through **unicode\_convert\_uc**(), then calls unicode\_convert\_deinit(). If this function returns 0, \**c* and \**csize* are set to a malloced buffer+size holding the char array.

## SEE ALSO

[**courier-unicode**(7)](/courier-unicode/7.md), [**unicode\_convert\_tocase**(3)](/unicode_convert_tocase/3.md), [**unicode\_default\_chset**(3)](/unicode_default_chset/3.md).

## AUTHOR

**Sam Varshavchik**

Author