--- org/iconv_open.3c Wed Mar 3 13:43:29 2010 +++ iconv_open.3c Thu Apr 29 13:19:50 2010 @@ -28,11 +28,127 @@ the encoding name is described in the file /usr/lib/iconv/alias. See alias(4). + When "" (i.e., empty string) or "char" is supplied as the string | + value for fromcode argument, tocode argument, or both, it is | + interpreted by the function as the codeset name of the current locale. | + Similarly, when "wchar_t" is supplied, the function interprets it as | + the wide character encoding of the current locale in the natural byte | + order of the current processor or as defined by the locale. | + | + When one or more of the following indicators are appended to the string | + values pointed to by the arguments, code conversion behavior will be | + modified as specified at below: | + | + //ILLEGAL_DISCARD | + When specified, during subsequent iconv() code | + conversion, a sequence of illegal input bytes that | + does not form a valid character in the codeset specified | + by the fromcode argument is silently discarded as if | + there are no such illegal bytes in the input buffer | + and the conversion continues. | + | + //ILLEGAL_REPLACE_HEX | + For any illegal input bytes, the iconv() code conversion | + converts each of such bytes into a hexadecimal number | + with a specific leading four-letter designator sequence | + as if such is a valid input byte and the conversion | + continues. More specifically, each of such hexadecimal | + numbers has a leading four-letter designator sequence of | + "IL--" followed by two hexadecimal digits in uppercase, | + for instance, "IL--01" for 1, "IL--0A" for 10, | + "IL--0B" for 11, "IL--EF" for 239, and so on. | + | + //ILLEGAL_RESTORE_HEX | + When specified, the iconv() code conversion simply | + converts back the above mentioned hexadecimal numbers for | + illegal input bytes into corresponding byte values | + regardless of the codeset specified by the tocode | + argument. For instance, "IL--0A" will be converted back | + into a byte with 10 as the value and "IL--FF" into 255. | + | + If the characters following the leading four-letter | + designator sequence do not form a valid hexadecimal | + number, such a sequence will not be treated as | + a hexadecimal number for illegal input bytes. | + | + //NON_IDENTICAL_DISCARD | + During subsequent iconv() code conversion, if | + the conversion encounters a character in the input buffer | + in the codeset specified by the fromcode argument that is | + legal but for which an identical character does not exist | + in the target codeset specified by the tocode argument, | + i.e., non-identical characters, the conversion discards | + such characters in the output buffer instead of doing | + an implementation-defined conversion. | + | + The number of such conversions are, nonetheless, still | + counted and returned as the return value of iconv(). | + | + //NON_IDENTICAL_REPLACE_HEX | + For non-identical characters, the iconv() code | + conversion converts each byte of such characters into | + a hexadecimal number with a specific leading four-letter | + designator sequence. More specifically, each of such | + hexadecimal numbers has a leading four-letter designator | + sequence of "NI--" followed by two hexadecimal digits in | + uppercase, for instance, "NI--02" for 2, "NI--0C" for 12, | + "NI--EF" for 239, and so on. | + | + The number of such non-identical characters are counted | + and returned as the return value of iconv(). | + | + //NON_IDENTICAL_RESTORE_HEX | + When specified, the iconv() code conversion converts back | + the above mentioned non-identical hexadecimal numbers | + into corresponding byte values regardless of the codeset | + specified by the tocode argument. For instance, "NI--0B" | + will be converted back into a byte with 11 as the value | + and "NI--FF" into 255. | + | + If the characters following the leading four-letter | + designator sequence do not form a valid hexadecimal | + number, such a sequence will not be treated as | + a non-identical hexadecimal number. | + | + //NON_IDENTICAL_TRANSLITERATE | + For non-identical characters, if applicable, the iconv() | + code conversion transliterates each of such characters | + into one or more characters of the target codeset best | + resembling the input character. | + | + The number of such non-identical characters are counted | + and returned as the return value of iconv(). | + | + //IGNORE A convenience alias to | + //NON_IDENTICAL_DISCARD//ILLEGAL_DISCARD indicators. | + | + //REPLACE_HEX A convenience alias to | + //NON_IDENTICAL_REPLACE_HEX//ILLEGAL_REPLACE_HEX | + indicators. | + | + //RESTORE_HEX A convenience alias to | + //NON_IDENTICAL_RESTORE_HEX//ILLEGAL_RESTORE_HEX | + indicators. | + | + //TRANSLIT A convenience alias to //NON_IDENTICAL_TRANSLITERATE | + indicator. | + | + When conflicting indicators are specified, one specified right-most | + within an argument and at tocode argument if specified at both arguments | + will override preceding indicators. As an example, in the following: | + | + cd = iconv_open("UTF-8//IGNORE//REPLACE_HEX", | + "ISO8859-1//ILLEGAL_REPLACE_HEX"); | + | + Among the three indicators specified, the "//REPLACE_HEX" will be | + honored. For more details on the associated error numbers and function | + return values at iconv(), see iconv(3C). | + | A conversion descriptor remains valid in a process until that process closes it. For examples using the iconv_open() function, see - iconv(3C). + EXAMPLES section at below and iconv(3C). | RETURN VALUES @@ -56,6 +172,49 @@ not supported by the implementation. +EXAMPLES | + Example 1: Using iconv_open() to open a simple code conversion | + | + #include | + #include | + #include | + | + : | + iconv_t cd; | + : | + | + /* Open an iconv code conversion from ISO 8859-1 to UTF-8. */ | + cd = iconv_open("UTF-8", "ISO8859-1"); | + if (cd == (iconv_t)-1) { | + (void) fprintf(stderr, "iconv_open(UTF-8, ISO8859-1) failed.\n"); | + return (1); | + } | + | + Example 2: Change conversion behavior by supplying conversion behavior | + modification indicators | + | + #include | + #include | + #include | + | + : | + iconv_t cd; | + : | + | + /* | + * Open an iconv code conversion from UTF-8 to ISO 8859-1 with | + * conversion behavior modification indicators that will remove | + * illegal byte sequences and replace non-identicals into hexadecimal | + * number strings. | + */ | + cd = iconv_open("ISO8859-1//ILLEGAL_DISCARD//NON_IDENTICAL_REPLACE_HEX", | + "UTF-8"); | + if (cd == (iconv_t)-1) { | + (void) fprintf(stderr, "iconv_open(UTF-8, ISO8859-1) failed.\n"); | + return (1); | + } | + | + | FILES /usr/lib/iconv/alias alias table file of the encoding name @@ -68,15 +227,25 @@ ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| - | Interface Stability | Standard | + | Interface Stability | Committed | | |_____________________________|_____________________________| - | MT-Level | MT-Safe | + | MT-Level | MT-Safe with exceptions as | | + | | noted at below. | | |_____________________________|_____________________________| + | + The iconv_open() function is MT-Safe with exception if and only if | + fromcode, tocode, or both arguments are pointing to a value that is | + "" (i.e., empty string), "char", or "wchar_t" since the function will | + have to call nl_langinfo(3C) to know the codeset of the current locale | + in such cases. See ATTRIBUTES and NOTES sections of setlocale(3C) for | + more detail. | + | + Otherwise, it is fully MT-Safe. | SEE ALSO - exec(2), iconv(3C), iconv_close(3C), malloc(3C), alias(4), - attributes(5) + exec(2), iconv(3C), iconv_close(3C), iconvctl(3C), iconvstr(3C), | + malloc(3C), nl_langinfo(3C), setlocale(3C), alias(4), attributes(5) | NOTES @@ -87,6 +256,11 @@ Portable applications must assume that conversion descrip- tors are not valid after a call to one of the exec functions (see exec(2)). + | + Individually, depending on the actual implementation of a code | + conversion, it is possible that one or more (including all) conversion | + behavior modification indicators are not supported by the code | + conversion and iconv_open() may fail. | SunOS 5.11 Last change: 2 Oct 2001 1