iconvctl.3

Branch :

Show log
Commit
Author : Bruno Haible
Date : 2023-04-03 04:12:01
Hash : 19b6af5e
Message : Allow overriding the newline conversion for EBCDIC encodings. Reported by Mike Fulton <mikefultonpersonal@gmail.com> in <https://lists.gnu.org/archive/html/bug-gnu-libiconv/2023-04/msg00009.html>. * include/iconv.h.in (ICONV_SURFACE_NONE, ICONV_SURFACE_EBCDIC_ZOS_UNIX): New macros. (ICONV_GET_FROM_SURFACE, ICONV_SET_FROM_SURFACE, ICONV_GET_TO_SURFACE, ICONV_SET_TO_SURFACE): New macros. * lib/converters.h (struct conv_struct): Add the fields isurface, osurface. (swap_x15_x25): New macro. * lib/iconv.c (iconv_open, iconv_open_into): Add local variables from_surface, to_surface. (ALL_SURFACES): New macro. (iconvctl): Adjust ICONV_TRIVIALP implementation. Implement the ICONV_{GET,SET}_{FROM,TO}_SURFACE requests. * lib/iconv_open1.h: Parse a /ZOS_UNIX surface specifier. Set from_surface, to_surface. * lib/iconv_open2.h: Copy the values of from_surface, to_surface into the conversion descriptor. * lib/ebcdic*.h (*_mbtowc): Test the isurface. If requested, call swap_x15_x25 right after fetching an input byte. (*_wctomb): Test the osurface. If requested, call swap_x15_x25 right before storing an output byte. * man/iconvctl.3 (REQUEST VALUES): Document the ICONV_{GET,SET}_{FROM,TO}_SURFACE requests. * src/iconv.c (main): If ICONV_EBCDIC_ZOS_UNIX is set, set the from/to surfaces accordingly. * man/iconv.1 (ENVIRONMENT): New section. * tests/check-ebcdic: New file. * tests/Makefile.in (check): Invoke it. (SOURCE_FILES): Add it. * NEWS: Mention the new functionality.

man/iconvctl.3

.\" Copyright (c) Perry Rapp
.\" Copyright (c) Free Software Foundation, Inc.
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 3 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   iconv.h
.\"
.TH ICONVCTL 3  "April 3, 2023" "GNU" "Linux Programmer's Manual"
.SH NAME
iconvctl \- control iconv behavior
.SH SYNOPSIS
.nf
.B #include <iconv.h>
.sp
.BI "int iconvctl (iconv_t " cd " , int " request ", void * " argument );
.fi
.SH DESCRIPTION
The argument \fIcd\fP must be a conversion descriptor created using the
function \fBiconv_open\fP.
.PP
\fBiconvctl\fP queries or adjusts the behavior of the \fBiconv\fP function,
when invoked with the specified conversion descriptor, depending on the
request value.
.SH "REQUEST VALUES"
The following are permissible values for the \fIrequest\fP parameter.
.TP
.B ICONV_TRIVIALP
\fIargument\fP should be an \fBint *\fP which will receive 1 if the
conversion is trivial, or 0 otherwise.
.TP
.B ICONV_GET_TRANSLITERATE
\fIargument\fP should be an \fBint *\fP which will receive 1 if 
transliteration is enabled in the conversion, or 0 otherwise.
.TP
.B ICONV_SET_TRANSLITERATE
\fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value.
A non-zero value is used to enable transliteration in the conversion. A zero
value disables it.
.TP
.B ICONV_GET_DISCARD_ILSEQ
\fIargument\fP should be an \fBint *\fP which will receive 1 if 
"illegal sequence discard and continue" is enabled in the conversion,
or 0 otherwise.
.TP
.B ICONV_SET_DISCARD_ILSEQ
\fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value.
A non-zero value is used to enable "illegal sequence discard and continue"
in the conversion. A zero value disables it.
.TP
.B ICONV_GET_FROM_SURFACE
\fIargument\fP should be an \fBunsigned int *\fP which will receive the
from-side (input side) surface of the conversion.
.TP
.B ICONV_SET_FROM_SURFACE
\fIargument\fP should be a \fBconst unsigned int *\fP, pointing to an
\fBunsigned int\fP value.  This value is installed as the from-side
(input side) surface of the conversion.  The value is a bit mask.  Zero
denotes no surface.  The value \fBICONV_SURFACE_EBCDIC_ZOS_UNIX\fP has
an effect on EBCDIC encodings: The EBCDIC newline 0x15 will get mapped
to LF instead of NEL.
.TP
.B ICONV_GET_TO_SURFACE
\fIargument\fP should be an \fBunsigned int *\fP which will receive the
to-side (output side) surface of the conversion.
.TP
.B ICONV_SET_TO_SURFACE
\fIargument\fP should be a \fBconst unsigned int *\fP, pointing to an
\fBunsigned int\fP value.  This value is installed as the to-side
(output side) surface of the conversion.  The value is a bit mask.  Zero
denotes no surface.  The value \fBICONV_SURFACE_EBCDIC_ZOS_UNIX\fP has
an effect on EBCDIC encodings: LF, instead of NEL, will get mapped to
the EBCDIC newline 0x15.
.SH "RETURN VALUE"
The \fBiconvctl\fP function returns 0 if it succeeds. In case of error, it sets
\fBerrno\fP and returns \-1.
.SH ERRORS
The following errors can occur, among others:
.TP
.B EINVAL
The request is invalid.
.SH "CONFORMING TO"
This function is implemented only in GNU libiconv and not in other \fBiconv\fP
implementations. It is not backed by a standard. You can test for its presence
through \fB(_LIBICONV_VERSION >= 0x0108)\fP.
.SH "SEE ALSO"
.BR iconv_open (3)
.BR iconv (3)

thodg/libiconv/man/iconvctl.3

Commit

thodg/libiconv /man/iconvctl.3