cconvctl - control and querycconvcode conversion behavior
#include <iconv.h> int cconvctl(cconv_t cd, int request, void *arg);
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:
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:
The current code conversion silently discards any illegal input bytes.
The current code conversion replaces illegal input bytes into hexadecimal number sequences as described in cconv_open(3C).
The current code conversion restores hexadecimal number sequences originated from illegal input bytes into actual byte values.
The current code conversion discards non-identical characters.
The current code conversion replaces bytes of non-identical characters into hexadecimal number sequences as described in cconv_open(3C).
The current code conversion restores hexadecimal number sequences originated from non-identical characters into actual byte values.
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).
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:
Instruct the current code conversion to silently discard any illegal input bytes.
Instruct the current code conversion to replace illegal input bytes into hexadecimal number sequences.
Instruct the current code conversion to restore hexadecimal number sequences originated from illegal input bytes into actual byte values.
Instruct the current code conversion to discard non-identical characters.
Instruct the current code conversion to replace bytes of non-identical characters into hexadecimal number sequences.
Instruct the current code conversion to restore hexadecimal number sequences originated from non-identical characters into actual byte values.
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).
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.
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.
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.
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.
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.)
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.
The cconvctl() function will fail if:
The conversion descriptor is invalid.
One or more of the requests are invalid.
One or more of the requests are not supported by the corresponding code conversion implementation.
#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);
See attributes(7) for descriptions of the following attributes:
|
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.
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)