'\" te
.\" Copyright (c) 2011, 2015, Oracle and/or its                         affiliates. All rights reserved.
.TH iconvctl 3C "3 Nov 2015" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
iconvctl \- control and query \fBiconv\fR code conversion behavior
.SH SYNOPSIS
.LP
.nf
#include <iconv.h>

int iconvctl(iconv_t \fIcd\fR, int \fIrequest\fR, void *\fIarg\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBiconvctl()\fR function can be used to control \fBiconv\fR code conversion behavior by setting or getting the current \fBiconv\fR code conversion behavior settings from the current code conversion pointed to by the conversion descriptor \fIcd\fRthat was returned from a successful \fBiconv_open\fR(3C) call.
.sp
.LP
The following are the supported values for the request argument:
.sp
.ne 2
.mk
.na
\fB\fBICONV_GET_CONVERSION_BEHAVIOR\fR\fR
.ad
.sp .6
.RS 4n
With this request, if query is successful, the function returns the current \fBiconv\fR code conversion behavior represented in a bitwise-inclusive-OR of the following values into an int variable that is pointed to by the \fIarg\fR argument as an \fBint\fR *:
.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_DISCARD\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion silently discards any illegal input bytes.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_REPLACE_HEX\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion replaces illegal input bytes into hexadecimal number sequences as described in \fBiconv_open\fR(3C).
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_RESTORE_HEX\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion restores hexadecimal number sequences originated from illegal input bytes into actual byte values.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_DISCARD\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion discards non-identical characters.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_REPLACE_HEX\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion replaces bytes of non-identical characters into hexadecimal number sequences as described in \fBiconv_open\fR(3C).
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_RESTORE_HEX\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion restores hexadecimal number sequences originated from non-identical characters into actual byte values.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_TRANSLITERATE\fR\fR
.ad
.sp .6
.RS 4n
The current code conversion tries to transliterate non-identical characters as much as it can.
.RE

For more details on the above \fBiconv\fR code conversion behaviors, refer to \fBiconv_open\fR(3C).
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_SET_CONVERSION_BEHAVIOR\fR\fR
.ad
.sp .6
.RS 4n
With this request, the function tries to set a specific set of code conversion behavior as instructed by the \fIarg\fR argument which is a pointer to an \fBint\fR that has a bitwise-inclusive-OR of the following values:
.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_DISCARD\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to silently discard any illegal input bytes.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_REPLACE_HEX\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to replace illegal input bytes into hexadecimal number sequences.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_ILLEGAL_RESTORE_HEX\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to restore hexadecimal number sequences originated from illegal input bytes into actual byte values.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_DISCARD\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to discard non-identical characters.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_REPLACE_HEX\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to replace bytes of non-identical characters into hexadecimal number sequences.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_RESTORE_HEX\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to restore hexadecimal number sequences originated from non-identical characters into actual byte values.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_CONV_NON_IDENTICAL_TRANSLITERATE\fR\fR
.ad
.sp .6
.RS 4n
Instruct the current code conversion to transliterate non-identical characters as much as it can.
.RE

When conflicting values are specified together, the values for discarding and then replacing into hexadecimal numbers will supersede other values specified.
.sp
For more details on the above \fBiconv\fR code conversion behaviors, refer to \fBiconv_open\fR(3C).
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_GET_DISCARD_ILSEQ\fR\fR
.ad
.sp .6
.RS 4n
With this request, upon successful completion, the function saves 1 into an \fBint\fR variable that is pointed to by the \fIarg\fR argument if the current code conversion discards illegal and non-identical characters from the input buffer. Otherwise, it saves 0.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_SET_DISCARD_ILSEQ\fR\fR
.ad
.sp .6
.RS 4n
With this request and a pointer to a \fIconst int\fR 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.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_GET_TRANSLITERATE\fR\fR
.ad
.sp .6
.RS 4n
With this request, upon successful completion, the function saves 1 into an \fBint\fR variable that is pointed to by the \fIarg\fR argument if the current code conversion transliterates non-identical characters from the input buffer. Otherwise, it saves 0.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_SET_TRANSLITERATE\fR\fR
.ad
.sp .6
.RS 4n
With this request and a pointer to a \fBconst int\fR 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.
.RE

.sp
.ne 2
.mk
.na
\fB\fBICONV_TRIVIALP\fR\fR
.ad
.sp .6
.RS 4n
With this request, upon successful completion, the function saves 1 into an \fBint\fR variable that is pointed to by the \fIarg\fR argument if the current code conversion is a trivial \fBiconv\fR code conversion.  Otherwise, it saves 0. (In Solaris, the trivial \fBiconv\fR code conversion is a simple 1-to-1 mapping table based or single-step \fBiconv\fR code conversion requiring no complex algorithm or data structures. This classification is largely subjective and informative only in nature.)
.RE

.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBiconvctl()\fR returns 0 and, optionally, with a value pointed to by the \fIarg\fR argument. Otherwise, \fBiconvctl()\fR returns -1 and sets \fIerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBiconvctl()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEBADF\fR\fR
.ad
.RS 11n
.rt  
The conversion descriptor is invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 11n
.rt  
One or more of the requests are invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOTSUP\fR\fR
.ad
.RS 11n
.rt  
One or more of the requests are not supported by the corresponding code conversion implementation.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUse \fBiconvctl()\fR to discard illegal characters and replace non-identical characters into hexadecimal number sequences.
.sp
.in +2
.nf
#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.\en");
    } else if (errno == EINVAL) {
            (void) fprintf(stderr, "invalid request.\en");
    } else if (errno == ENOTSUP) {
            (void) fprintf(stderr, "unsupported request.\en");
    } else {
            /*
             * This shouldn't happen; this is only to make your code
             * robust.
             */
            (void) fprintf(stderr, "unknown reason.\en");
    }
    return (1);
}

return (0);
.fi
.in -2

.LP
\fBExample 2 \fRQuery to determine if the current conversion is doing transliteration on non-identical characters.
.sp
.in +2
.nf
#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)\en", errno);
    return (-1);
}

return (status);
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBgeniconvtbl\fR(1), \fBiconv\fR(1), \fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), \fBiconvstr\fR(3C), \fBiconv.h\fR(3HEAD), \fBgeniconvtbl\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
It is unsafe for any thread to call \fBiconvctl()\fR to change the current code conversion behavior while there is \fBiconv\fR(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 \fBiconvctl()\fR prior to any \fBiconv()\fR call with the same conversion descriptor or wait for existing \fBiconv()\fR\fBiconv\fR(3C) call to finish, reset the code conversion, call \fBiconvctl()\fR, and then call \fBiconv()\fR for a new code conversion behavior
.sp
.LP
It is safe to use \fBiconvctl()\fR to query the current code conversion behavior except when some other thread is changing the code conversion behavior.