svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
iconvctl(3c)
iconvctl(3C) Standard C Library Functions iconvctl(3C)
NAME
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(3C) code conver‐
sion behavior by setting or getting the current iconv() code conversion
behavior settings from the current code conversion pointed to by the
conversion descriptor cd that 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-in‐
clusive-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 with
hexadecimal number sequences as described in iconv_open(3C).
ICONV_CONV_ILLEGAL_RESTORE_HEX
The current code conversion restores hexadecimal number se‐
quences originated from illegal input bytes by replacing the
sequences with 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 with hexadecimal number sequences as described in
iconv_open(3C).
ICONV_CONV_NON_IDENTICAL_RESTORE_HEX
The current code conversion restores hexadecimal number se‐
quences originated from non-identical characters by replacing
the sequences with actual byte values.
ICONV_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 iconv code conversion behaviors, re‐
fer 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 with hexadecimal number sequences.
ICONV_CONV_ILLEGAL_RESTORE_HEX
Instruct the current code conversion to restore hexadecimal
number sequences originated from illegal input bytes by replac‐
ing the sequences with the 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 with hexadecimal number sequences.
ICONV_CONV_NON_IDENTICAL_RESTORE_HEX
Instruct the current code conversion to restore hexadecimal
number sequences originated from non-identical characters by
replacing the sequences with actual byte values.
ICONV_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 dis‐
carding and then replacing with hexadecimal numbers will supersede
other values specified.
For more details on the above iconv code conversion behaviors, re‐
fer 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 charac‐
ters 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 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.
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 con‐
version 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. Other‐
wise, it saves 0. (In Solaris, the trivial iconv code conversion is
a simple 1-to-1 mapping table based or single-step iconv 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, 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 corre‐
sponding code conversion implementation.
EXAMPLES
Example 1 Change Conversion Behavior
This code example uses iconvctl() to discard illegal characters and re‐
place non-identical characters with 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 Conversion Behavior
This code example queries to determine if the current conversion is do‐
ing 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) {
perror("iconvctl() 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
It is unsafe for a thread to call iconvctl() to change the current code
conversion behavior at the same time that iconv(3C) is being called by
another thread using the same conversion descriptor. Unpredictable code
conversion behavior can occur in the middle of code conversion if this
happens. To change the code conversion behavior in a multi-threaded ap‐
plication, call iconvctl() prior to any iconv() call with the same con‐
version descriptor or wait for existing iconv() calls 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 be‐
havior except when some other thread is changing the code conversion
behavior.
SEE ALSO
geniconvtbl(1), iconv(1), iconv(3C), iconv_close(3C), iconv_open(3C),
iconvstr(3C), iconv.h(3HEAD), geniconvtbl(5), attributes(7), stan‐
dards(7)
Converting Codesets in Internationalizing and Localizing Applications
in Oracle Solaris
HISTORY
The iconvctl() function was added to Solaris in the Oracle Solaris
11.0.0 release.
Oracle Solaris 11.4 25 Nov 2024 iconvctl(3C)