Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

cconvctl (3C)

Name

cconvctl - control and querycconvcode conversion behavior

Synopsis

#include <iconv.h>
int cconvctl(cconv_t cd, int request, void *arg);

Description

The cconvctl() function can be used to control cconv code conversion behavior by setting or getting the current cconv code conversion behavior settings from the current code conversion pointed to by the conversion descriptor, cd, which returned from a successful cconv_open() call.

The following are the supported values for the request argument:

CCONV_GET_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:

CCONV_CONV_ILLEGAL_DISCARD

The current code conversion silently discards any illegal input bytes.

CCONV_CONV_ILLEGAL_REPLACE_HEX

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

CCONV_CONV_ILLEGAL_RESTORE_HEX

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

CCONV_CONV_NON_IDENTICAL_DISCARD

The current code conversion discards non-identical characters.

CCONV_CONV_NON_IDENTICAL_REPLACE_HEX

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

CCONV_CONV_NON_IDENTICAL_RESTORE_HEX

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

CCONV_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 cconv code conversion behaviors, refer to cconv_open(3C).

CCONV_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:

CCONV_CONV_ILLEGAL_DISCARD

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

CCONV_CONV_ILLEGAL_REPLACE_HEX

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

CCONV_CONV_ILLEGAL_RESTORE_HEX

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

CCONV_CONV_NON_IDENTICAL_DISCARD

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

CCONV_CONV_NON_IDENTICAL_REPLACE_HEX

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

CCONV_CONV_NON_IDENTICAL_RESTORE_HEX

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

CCONV_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 cconv code conversion behaviors, refer to cconv_open(3C).

CCONV_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.

CCONV_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.

CCONV_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.

CCONV_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.

CCONV_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 cconv code conversion. Otherwise, it saves 0. (In Solaris, the trivial cconv code conversion is a simple 1-to-1 mapping table based or single-step cconv code conversion requiring no complex algorithm or data structures. This classification is largely subjective and informative only in nature.)

Return Values

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

Errors

The cconvctl() 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 Using cconvctl() to discard illegal characters and replace non-identical characters into hexadecimal number sequences
#include <stdio.h>
#include <errno.h>
#include <iconv.h>

           :
        cconv_t cd;
        int r;
	int status;
           :

	status = (CCONV_CONV_ILLEGAL_DISCARD |
		  CCONV_CONV_NON_IDENTICAL_REPLACE_HEX);
        r = cconvctl(cd, CCONV_SET_CONVERSION_BEHAVIOR, (void *)&status);
        if (r == -1) {
            (void) fprintf(stderr, "cconvctl() 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 see if the current conversion is doing transliteration on non-identical characters
#include <stdio.h>
#include <errno.h>
#include <iconv.h>

            :
        cconv_t cd;
        int status;
        int r;
            :

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

        return (status);

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe with exceptions as noted below.

It is unsafe for any thread to call cconvctl() to change the current code conversion behavior while there is cconv(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 cconvctl() prior to any cconv() call with the same conversion descriptor or wait for existing cconv() call to finish, reset the code conversion, call cconvctl(), and then call cconv() for a new code conversion behavior.

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

See Also

geniconvtbl(1), iconv(1), cconv(3C), cconv_close(3C), cconv_open(3C), iconv(3C), iconv_close(3C), iconv_open(3C), iconvctl(3C), iconvstr(3C), iconv.h(3HEAD), geniconvtbl(5), geniconvtbl-cconv(5), attributes(7)