iconvctl

- control and query iconv code conversion behavior

Synopsis

#include <iconv.h>

int iconvctl(iconv_t cd, int request, void *arg);

Description

The iconvctl() function can be used to control iconv code conversion behavior by setting or getting the current iconv code conversion behavior settings from the current code conversion pointed to by the conversion descriptor cdthat was returned from a successful iconv_open(3C) call.

The following are the supported values for the request argument:

ICONV_GET_CONVERSION_BEHAVIOR

With this request, if query is successful, the function returns the current iconv code conversion behavior represented in a bitwise-inclusive-OR of the following values into an int variable that is pointed to by the arg argument as an int *:

ICONV_CONV_ILLEGAL_DISCARD

The current code conversion silently discards any illegal input bytes.

ICONV_CONV_ILLEGAL_REPLACE_HEX

The current code conversion replaces illegal input bytes into hexadecimal number sequences as described in iconv_open(3C).

ICONV_CONV_ILLEGAL_RESTORE_HEX

The current code conversion restores hexadecimal number sequences originated from illegal input bytes into actual byte values.

ICONV_CONV_NON_IDENTICAL_DISCARD

The current code conversion discards non-identical characters.

ICONV_CONV_NON_IDENTICAL_REPLACE_HEX

The current code conversion replaces bytes of non-identical characters into hexadecimal number sequences as described in iconv_open(3C).

ICONV_CONV_NON_IDENTICAL_RESTORE_HEX

The current code conversion restores hexadecimal number sequences originated from non-identical characters into actual byte values.

ICONV_CONV_NON_IDENTICAL_TRANSLITERATE

The current code conversion tries to transliterate non-identical characters as much as it can.

For more details on the above iconv code conversion behaviors, refer to iconv_open(3C).

ICONV_SET_CONVERSION_BEHAVIOR

With this request, the function tries to set a specific set of code conversion behavior as instructed by the arg argument which is a pointer to an int that has a bitwise-inclusive-OR of the following values:

ICONV_CONV_ILLEGAL_DISCARD

Instruct the current code conversion to silently discard any illegal input bytes.

ICONV_CONV_ILLEGAL_REPLACE_HEX

Instruct the current code conversion to replace illegal input bytes into hexadecimal number sequences.

ICONV_CONV_ILLEGAL_RESTORE_HEX

Instruct the current code conversion to restore hexadecimal number sequences originated from illegal input bytes into actual byte values.

ICONV_CONV_NON_IDENTICAL_DISCARD

Instruct the current code conversion to discard non-identical characters.

ICONV_CONV_NON_IDENTICAL_REPLACE_HEX

Instruct the current code conversion to replace bytes of non-identical characters into hexadecimal number sequences.

ICONV_CONV_NON_IDENTICAL_RESTORE_HEX

Instruct the current code conversion to restore hexadecimal number sequences originated from non-identical characters into actual byte values.

ICONV_CONV_NON_IDENTICAL_TRANSLITERATE

Instruct the current code conversion to transliterate non-identical characters as much as it can.

When conflicting values are specified together, the values for discarding and then replacing into hexadecimal numbers will supersede other values specified.

For more details on the above iconv code conversion behaviors, refer to iconv_open(3C).

ICONV_GET_DISCARD_ILSEQ

With this request, upon successful completion, the function saves 1 into an int variable that is pointed to by the arg argument if the current code conversion discards illegal and non-identical characters from the input buffer. Otherwise, it saves 0.

ICONV_SET_DISCARD_ILSEQ

With this request and a pointer to a const int with a non-zero value, caller can instruct the current conversion to discard illegal and non-identical characters from the input buffer during the code conversion. The value of zero, on the other hand, turns it off.

ICONV_GET_TRANSLITERATE

With this request, upon successful completion, the function saves 1 into an int variable that is pointed to by the arg argument if the current code conversion transliterates non-identical characters from the input buffer. Otherwise, it saves 0.

ICONV_SET_TRANSLITERATE

With this request and a pointer to a const int with a non-zero value, caller can instruct the current conversion to transliterate non-identical characters from the input buffer during the code conversion as much as it can. The value of zero, on the other hand, turns it off.

ICONV_TRIVIALP

With this request, upon successful completion, the function saves 1 into an int variable that is pointed to by the arg argument if the current code conversion is a trivial iconv code conversion. Otherwise, it saves 0. (In Solaris, the trivial iconv code conversion is a simple 1-to-1 mapping table based or single-step iconv code conversion requiring no complex algorithm or data structures. This classification is largely subjective and informative only in nature.)

Return Values

Upon successful completion, iconvctl() returns 0 and, optionally, with a value pointed to by the arg argument. Otherwise, iconvctl() returns -1 and sets errno to indicate the error.

Errors

The iconvctl() function will fail if:

EBADF

The conversion descriptor is invalid.

EINVAL

One or more of the requests are invalid.

ENOTSUP

One or more of the requests are not supported by the corresponding code conversion implementation.

Examples

Example 1 Use iconvctl() to discard illegal characters and replace non-identical characters into hexadecimal number sequences.

#include <stdio.h>
#include <errno.h>
#include <iconv.h>

   :
iconv_t cd;
int r;
int status;
   :

status = (ICONV_CONV_ILLEGAL_DISCARD |
    ICONV_CONV_NON_IDENTICAL_REPLACE_HEX);
r = iconvctl(cd, ICONV_SET_CONVERSION_BEHAVIOR, (void *)&status);
if (r == -1) {
    (void) fprintf(stderr, "iconvctl() failed due to ");
    if (errno == EBADF) {
            (void) fprintf(stderr, "invalid conversion descriptor.\n");
    } else if (errno == EINVAL) {
            (void) fprintf(stderr, "invalid request.\n");
    } else if (errno == ENOTSUP) {
            (void) fprintf(stderr, "unsupported request.\n");
    } else {
            /*
             * This shouldn't happen; this is only to make your code
             * robust.
             */
            (void) fprintf(stderr, "unknown reason.\n");
    }
    return (1);
}

return (0);

Example 2 Query to determine if the current conversion is doing transliteration on non-identical characters.

#include <stdio.h>
#include <errno.h>
#include <iconv.h>

    :
iconv_t cd;
int status;
int r;
    :

r = iconvctl(cd, ICONV_GET_TRANSLITERATE, (void *)&status);
if (r == -1) {
    (void) fprintf(stderr, "iconvctl() failed (errno = %d)\n", errno);
    return (-1);
}

return (status);

Attributes

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

See Also

geniconvtbl(1), iconv(1), iconv(3C), iconv_close(3C), iconv_open(3C), iconvstr(3C), iconv.h(3HEAD), geniconvtbl(4), attributes(5), standards(5)

Notes

It is unsafe for any thread to call iconvctl() to change the current code conversion behavior while there is iconv(3C) being called by any other thread with the same conversion descriptor in the application since such will yield unpredictable code conversion behavior change in the middle of code conversion. To change the code conversion behavior in a multi-threaded application, call iconvctl() prior to any iconv() call with the same conversion descriptor or wait for existing iconv()iconv(3C) call to finish, reset the code conversion, call iconvctl(), and then call iconv() for a new code conversion behavior

It is safe to use iconvctl() to query the current code conversion behavior except when some other thread is changing the code conversion behavior.