ICONVCTL(3) |
FreeBSD Library Functions Manual |
ICONVCTL(3) |
NAME
iconvctl —
controlling and diagnostical facility for iconv(3)
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include < iconv.h>
int
iconvctl( iconv_t cd, int request, void *argument);
DESCRIPTION
The
iconvctl() function can retrieve or set specific conversion setting from the
cd conversion descriptor. The
request parameter specifies the operation to accomplish and
argument is an operation-specific argument.
The possible operations are the following:
-
ICONV_TRIVIALP
-
In this case
argument is an
int * variable, which is set to 1 if the encoding is trivial one, i.e. the input and output encodings are the same. Otherwise, the variable will be 0.
-
ICONV_GET_TRANSLITERATE
-
Determines if transliteration is enabled. The answer is stored in
argument, which is of
int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.
-
ICONV_SET_TRANSLITERATE
-
Enables transliteration if
argument, which is of
int * set to 1 or disables it if
argument is set to 0.
-
ICONV_GET_DISCARD_ILSEQ
-
Determines if illegal sequences are discarded or not. The answer is stored in
argument, which is of
int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.
-
ICONV_SET_DISCARD_ILSEQ
-
Sets whether illegal sequences are discarded or not.
argument, which is of
int * set to 1 or disables it if
argument is set to 0.
-
ICONV_SET_HOOKS
-
Sets callback functions, which will be called back after successful conversions. The callback functions are stored in a
struct iconv_hooks variable, which is passed to
iconvctl via
argument by its address.
-
ICONV_GET_ILSEQ_INVALID
-
Determines if a character in the input buffer that is valid, but for which an identical character does not exist in the target codeset returns
EILSEQ or not. The answer is stored in
argument, which is of
int *. It will be set to 1 if this feature is enabled or set to 0 otherwise.
-
ICONV_SET_ILSEQ_INVALID
-
Sets whether a character in the input buffer that is valid, but for which an identical character does not exist in the target codeset returns
EILSEQ or not. If
argument, which is of
int * is set to 1 it will be enabled, and if
argument is set to 0 it will be disabled.
RETURN VALUES
Upon successful completion
iconvctl(), returns 0. Otherwise, -1 is returned and errno is set to specify the kind of error.
ERRORS
The
iconvctl() function may cause an error in the following cases:
-
[
EINVAL]
-
Unknown or unimplemented operation.
-
[
EBADF]
-
The conversion descriptor specified by
cd is invalid.
STANDARDS
The
iconvctl facility is a non-standard extension, which appeared in the GNU implementation and was adopted in
FreeBSD 9 for compatibility's sake.
AUTHORS
This manual page was written by
Gabor Kovesdan <gabor@FreeBSD.org>.
BUGS
Transliteration is enabled in this implementation by default, so it is impossible by design to turn it off. Accordingly, trying to turn it off will always fail and -1 will be returned. Getting the transliteration state will always succeed and indicate that it is turned on, though.