man/iconvctl.3

   1 .\" Copyright (c) Perry Rapp
   2 .\" Copyright (c) Free Software Foundation, Inc.
   3 .\"
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 3 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" References consulted:
  10 .\"   iconv.h
  11 .\"
  12 .TH ICONVCTL 3  "April 3, 2023" "GNU"
  13 .SH NAME
  14 iconvctl \- control iconv behavior
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <iconv.h>
  18 .sp
  19 .BI "int iconvctl (iconv_t " cd " , int " request ", void * " argument );
  20 .fi
  21 .SH DESCRIPTION
  22 The argument \fIcd\fP must be a conversion descriptor created using the
  23 function \fBiconv_open\fP.
  24 .PP
  25 \fBiconvctl\fP queries or adjusts the behavior of the \fBiconv\fP function,
  26 when invoked with the specified conversion descriptor, depending on the
  27 request value.
  28 .SH "REQUEST VALUES"
  29 The following are permissible values for the \fIrequest\fP parameter.
  30 .TP
  31 .B ICONV_TRIVIALP
  32 \fIargument\fP should be an \fBint *\fP which will receive 1 if the
  33 conversion is trivial, or 0 otherwise.
  34 .TP
  35 .B ICONV_GET_TRANSLITERATE
  36 \fIargument\fP should be an \fBint *\fP which will receive 1 if
  37 transliteration is enabled in the conversion, or 0 otherwise.
  38 .TP
  39 .B ICONV_SET_TRANSLITERATE
  40 \fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value.
  41 A non-zero value is used to enable transliteration in the conversion. A zero
  42 value disables it.
  43 .TP
  44 .B ICONV_GET_DISCARD_ILSEQ
  45 \fIargument\fP should be an \fBint *\fP which will receive 1 if
  46 "illegal sequence discard and continue" is enabled in the conversion,
  47 or 0 otherwise.
  48 .TP
  49 .B ICONV_SET_DISCARD_ILSEQ
  50 \fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value.
  51 A non-zero value is used to enable "illegal sequence discard and continue"
  52 in the conversion. A zero value disables it.
  53 .TP
  54 .B ICONV_GET_FROM_SURFACE
  55 \fIargument\fP should be an \fBunsigned int *\fP which will receive the
  56 from-side (input side) surface of the conversion.
  57 .TP
  58 .B ICONV_SET_FROM_SURFACE
  59 \fIargument\fP should be a \fBconst unsigned int *\fP, pointing to an
  60 \fBunsigned int\fP value.  This value is installed as the from-side
  61 (input side) surface of the conversion.  The value is a bit mask.  Zero
  62 denotes no surface.  The value \fBICONV_SURFACE_EBCDIC_ZOS_UNIX\fP has
  63 an effect on EBCDIC encodings: The EBCDIC newline 0x15 will get mapped
  64 to LF instead of NEL.
  65 .TP
  66 .B ICONV_GET_TO_SURFACE
  67 \fIargument\fP should be an \fBunsigned int *\fP which will receive the
  68 to-side (output side) surface of the conversion.
  69 .TP
  70 .B ICONV_SET_TO_SURFACE
  71 \fIargument\fP should be a \fBconst unsigned int *\fP, pointing to an
  72 \fBunsigned int\fP value.  This value is installed as the to-side
  73 (output side) surface of the conversion.  The value is a bit mask.  Zero
  74 denotes no surface.  The value \fBICONV_SURFACE_EBCDIC_ZOS_UNIX\fP has
  75 an effect on EBCDIC encodings: LF, instead of NEL, will get mapped to
  76 the EBCDIC newline 0x15.
  77 .SH "RETURN VALUE"
  78 The \fBiconvctl\fP function returns 0 if it succeeds. In case of error, it sets
  79 \fBerrno\fP and returns \-1.
  80 .SH ERRORS
  81 The following errors can occur, among others:
  82 .TP
  83 .B EINVAL
  84 The request is invalid.
  85 .SH "CONFORMING TO"
  86 This function is implemented only in GNU libiconv and not in other \fBiconv\fP
  87 implementations. It is not backed by a standard. You can test for its presence
  88 through \fB(_LIBICONV_VERSION >= 0x0108)\fP.
  89 .SH "SEE ALSO"
  90 .BR iconv_open (3)
  91 .BR iconv (3)