iconv_open(), iconv_close(), iconv(), iconv_getnextcodesetname() -- codeset conversion functions

SYNOPSIS

#include <iconv.h>

iconv_t iconv_open(const char *dstname, const char *srcname);

int iconv_close(iconv_t cd);

size_t iconv(iconv_t cd, char **src, size_t *srcleft, char **dst, size_t *dstleft);

const char ** iconv_getnextcodesetname(int *index)

The iconv_open() function opens a converter from the codeset srcname to the codeset dstname and returns its descriptor. The arguments srcname and dstname accept "" and "char", which refer to the current locale encoding.

The iconv_close() function closes the specified converter cd.

The iconv() function converts the string in the buffer *src of length *srcleft bytes and stores the converted string in the buffer *dst of size *dstleft bytes. After calling iconv(), the values pointed to by src, srcleft, dst, and dstleft are updated as follows:

*src	Pointer to the byte just after the last character fetched.
*srcleft	Number of remaining bytes in the source buffer.
*dst	Pointer to the byte just after the last character stored.
*dstleft	Number of remainder bytes in the destination buffer.

If the string pointed to by *src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just after the last successful conversion. If the output buffer is too small to store the converted character, the conversion also stops in the same way. In these cases, the values pointed to by src, srcleft, dst, and dstleft are updated to the state just after the last successful conversion.

If the string pointed to by *src contains a character which is valid under the source codeset but can not be converted to the destination codeset, the character is replaced by an "invalid character" which depends on the destination codeset, e.g., "?", and the conversion is continued. iconv() returns the number of such "invalid conversions".

There are two special cases of iconv():

src == NULL || *src == NULL

If the source and/or destination codesets are stateful, iconv() places these into their initial state.

If both dst and *dst are non-NULL, iconv() stores the shift sequence for the destination switching to the initial state in the buffer pointed to by *dst. The buffer size is specified by the value pointed to by dstleft as above. iconv() will fail if the buffer is too small to store the shift sequence.

On the other hand, dst or *dst may be NULL. In this case, the shift sequence for the destination switching to the initial state is discarded.

The iconv_getnextcodesetname() function takes a location argument initially a pointer to an int of value zero and returns the alias and Windows description for that codeset entry, while updating the index to allow a subsequent call to find the next entry. It is a non-standard interface to enumerate all of the available iconv codepage aliases thus:

int listcset(void)
{
        int id = 0;
        const char **ss;

        printf("Character sets:");
        while ((ss = iconv_getnextcodesetname(&id)) != NULL)
	{
        	printf("\n\t%s\t%s", ss[0], ss[1]);
	}
        printf("\n");
        if (0 == id)
                fprintf(stderr, "System does not support querying the set of character sets\n");
        return 0;
}

Available code pages are not reinitialized after process startup. Asking for the nth codeset name will return the same pair of strings at any point in the process life. The array returned is thread local, allowing simultaneous calls from multiple threads.

RETURN VALUES

Upon successful completion of iconv_open(), it returns a conversion descriptor. Otherwise, iconv_open() returns (iconv_t)-1 and sets errno to indicate the error.

ENOMEM: Memory is exhausted.
EINVAL: There is no converter specified by srcname and dstname.

Upon successful completion of iconv_close(), it returns 0. Otherwise, iconv_close() returns -1 and sets errno to indicate the error.

EBADF: The conversion descriptor specified by cd is invalid.

Upon successful completion of iconv(), it returns the number of "invalid" conversions. Otherwise, iconv() returns (size_t)-1 and sets errno to indicate the error.

EBADF: The conversion descriptor specified by cd is invalid.
EILSEQ: The string pointed to by *src contains a byte sequence which does not describe a valid character of the source codeset.
E2BIG: The output buffer pointed to by *dst is too small to store the result string.
EINVAL: The string pointed to by *src terminates with an incomplete character or shift sequence.

CONFORMANCE

The iconv_open(), iconv_close(), and iconv() functions conform to IEEE Std 1003.1-2008 'POSIX.1'.

iconv_getnextcodesetname() is a NuTCRACKER Platform extension (-DNUTC_SOURCE), thus its use may break portability.

MULTITHREAD SAFETY LEVEL

Safe.

PORTING ISSUES

iconv() may conform to XPG4 and IEEE Std 1003.1-2008 'POSIX.1', but the strings passed into iconv_open() are not standardized. There is no standard way to enumerate these names, or even to know if a given name will work on an implementation. Efforts have been made to match other UNIX iconv() names.

The implementation uses the Win32 funtions MultibyteToWideChar() and WideCharToMultiByte(). The code pages installed on a given Windows machine may well differ and these functions can only translate among installed Windows code pages.

PORTABILITY

FreeBSD 5 and up. Linux. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

iconv_open(), iconv_close(), iconv(), iconv_getnextcodesetname()
codeset conversion functions

Function