svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
cconvctl(3c)
cconvctl(3C) Standard C Library Functions cconvctl(3C)
NAME
cconvctl - control and query cconv code 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 behav‐
ior settings from the current code conversion pointed to by the conver‐
sion descriptor, cd, which was 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 se‐
quences 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 se‐
quences originated from non-identical characters into actual
byte values.
CCONV_CONV_NON_IDENTICAL_TRANSLITERATE
The current code conversion tries to transliterate non-identi‐
cal 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 ac‐
tual 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-iden‐
tical characters as much as it can.
When conflicting values are specified together, the values for discard‐
ing 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 charac‐
ters 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 ille‐
gal 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 con‐
version 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. Other‐
wise, it saves 0. (In Solaris, the trivial cconv code conversion is
a simple 1-to-1 mapping table based or single-step cconv code con‐
version requiring no complex algorithm or data structures. This
classification is largely subjective and informative only in na‐
ture.)
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 corre‐
sponding code conversion implementation.
EXAMPLES
Example 1 Setting Conversion Behavior
The following code shows the use of cconvctl() to discard illegal char‐
acters and replace non-identical characters into hexadecimal number se‐
quences.
#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 Querying Conversion Behavior
The following code shows how to 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) {
perror("cconvctl() failed");
return (-1);
}
return (status);
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe with ex‐
ceptions 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 be‐
havior 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)
HISTORY
The cconvctl() function was added to Solaris in the Oracle Solaris
11.4.0 release.
Oracle Solaris 11.4 25 Nov 2024 cconvctl(3C)