source/include/iconv.h

0001 /* Copyright (C) 1999-2024 Free Software Foundation, Inc.
0002    This file is part of the GNU LIBICONV Library.
0003
0004    The GNU LIBICONV Library is free software; you can redistribute it
0005    and/or modify it under the terms of the GNU Lesser General Public
0006    License as published by the Free Software Foundation; either version 2.1
0007    of the License, or (at your option) any later version.
0008
0009    The GNU LIBICONV Library is distributed in the hope that it will be
0010    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Lesser General Public License for more details.
0013
0014    You should have received a copy of the GNU Lesser General Public
0015    License along with the GNU LIBICONV Library; see the file COPYING.LIB.
0016    If not, see <https://www.gnu.org/licenses/>.  */
0017
0018 /* When installed, this file is called "iconv.h". */
0019
0020 #ifndef _LIBICONV_H
0021 #define _LIBICONV_H
0022
0023 #ifdef __cplusplus
0024 extern "C" {
0025 #endif
0026
0027 #define _LIBICONV_VERSION 0x0112    /* version number: (major<<8) + minor */
0028 extern  int _libiconv_version; /* Likewise */
0029
0030 #ifdef __cplusplus
0031 }
0032 #endif
0033
0034 /* We would like to #include any system header file which could define
0035    iconv_t, in order to eliminate the risk that the user gets compilation
0036    errors because some other system header file includes /usr/include/iconv.h
0037    which defines iconv_t or declares iconv after this file.
0038    But gcc's #include_next is not portable. Thus, once libiconv's iconv.h
0039    has been installed in /usr/local/include, there is no way any more to
0040    include the original /usr/include/iconv.h. We simply have to get away
0041    without it.
0042    The risk that a system header file does
0043    #include "iconv.h"  or  #include_next "iconv.h"
0044    is small. They all do #include <iconv.h>. */
0045
0046 /* Define iconv_t ourselves. */
0047 #undef iconv_t
0048 #define iconv_t libiconv_t
0049 typedef void* iconv_t;
0050
0051 /* Get size_t declaration.
0052    Get wchar_t declaration if it exists. */
0053 #include <stddef.h>
0054
0055 /* Get errno declaration and values. */
0056 #include <errno.h>
0057 /* Some systems, like SunOS 4, don't have EILSEQ. Some systems, like BSD/OS,
0058    have EILSEQ in a different header.  On these systems, define EILSEQ
0059    ourselves. */
0060 #ifndef EILSEQ
0061 #define EILSEQ
0062 #endif
0063
0064
0065 #ifdef __cplusplus
0066 extern "C" {
0067 #endif
0068
0069
0070 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
0071    encoding ‘tocode’. */
0072 #define iconv_open libiconv_open
0073 extern iconv_t iconv_open (const char* tocode, const char* fromcode);
0074
0075 /* Converts, using conversion descriptor ‘cd’, at most ‘*inbytesleft’ bytes
0076    starting at ‘*inbuf’, writing at most ‘*outbytesleft’ bytes starting at
0077    ‘*outbuf’.
0078    Decrements ‘*inbytesleft’ and increments ‘*inbuf’ by the same amount.
0079    Decrements ‘*outbytesleft’ and increments ‘*outbuf’ by the same amount. */
0080 #define iconv libiconv
0081 extern size_t iconv (iconv_t cd,  char* * inbuf, size_t *inbytesleft, char* * outbuf, size_t *outbytesleft);
0082
0083 /* Frees resources allocated for conversion descriptor ‘cd’. */
0084 #define iconv_close libiconv_close
0085 extern int iconv_close (iconv_t cd);
0086
0087
0088 #ifdef __cplusplus
0089 }
0090 #endif
0091
0092
0093 /* Nonstandard extensions. */
0094
0095 #if 1
0096 #if 0
0097 /* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
0098    <wchar.h>.
0099    BSD/OS 4.0.1 has a bug: <stddef.h>, <stdio.h> and <time.h> must be
0100    included before <wchar.h>.  */
0101 #include <stddef.h>
0102 #include <stdio.h>
0103 #include <time.h>
0104 #endif
0105 #include <wchar.h>
0106 #endif
0107
0108 #ifdef __cplusplus
0109 extern "C" {
0110 #endif
0111
0112 /* A type that holds all memory needed by a conversion descriptor.
0113    A pointer to such an object can be used as an iconv_t. */
0114 typedef struct {
0115   void* dummy1[28];
0116 #if 1
0117   mbstate_t dummy2;
0118 #endif
0119 } iconv_allocation_t;
0120
0121 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
0122    encoding ‘tocode’ into preallocated memory. Returns an error indicator
0123    (0 or -1 with errno set). */
0124 #define iconv_open_into libiconv_open_into
0125 extern int iconv_open_into (const char* tocode, const char* fromcode,
0126                             iconv_allocation_t* resultp);
0127
0128 /* Control of attributes. */
0129 #define iconvctl libiconvctl
0130 extern int iconvctl (iconv_t cd, int request, void* argument);
0131
0132 /* Hook performed after every successful conversion of a Unicode character. */
0133 typedef void (*iconv_unicode_char_hook) (unsigned int uc, void* data);
0134 /* Hook performed after every successful conversion of a wide character. */
0135 typedef void (*iconv_wide_char_hook) (wchar_t wc, void* data);
0136 /* Set of hooks. */
0137 struct iconv_hooks {
0138   iconv_unicode_char_hook uc_hook;
0139   iconv_wide_char_hook wc_hook;
0140   void* data;
0141 };
0142
0143 /* Fallback function.  Invoked when a small number of bytes could not be
0144    converted to a Unicode character.  This function should process all
0145    bytes from inbuf and may produce replacement Unicode characters by calling
0146    the write_replacement callback repeatedly.  */
0147 typedef void (*iconv_unicode_mb_to_uc_fallback)
0148              (const char* inbuf, size_t inbufsize,
0149               void (*write_replacement) (const unsigned int *buf, size_t buflen,
0150                                          void* callback_arg),
0151               void* callback_arg,
0152               void* data);
0153 /* Fallback function.  Invoked when a Unicode character could not be converted
0154    to the target encoding.  This function should process the character and
0155    may produce replacement bytes (in the target encoding) by calling the
0156    write_replacement callback repeatedly.  */
0157 typedef void (*iconv_unicode_uc_to_mb_fallback)
0158              (unsigned int code,
0159               void (*write_replacement) (const char *buf, size_t buflen,
0160                                          void* callback_arg),
0161               void* callback_arg,
0162               void* data);
0163 /* Fallback function.  Invoked when a number of bytes could not be converted to
0164    a wide character.  This function should process all bytes from inbuf and may
0165    produce replacement wide characters by calling the write_replacement
0166    callback repeatedly.  */
0167 typedef void (*iconv_wchar_mb_to_wc_fallback)
0168              (const char* inbuf, size_t inbufsize,
0169               void (*write_replacement) (const wchar_t *buf, size_t buflen,
0170                                          void* callback_arg),
0171               void* callback_arg,
0172               void* data);
0173 /* Fallback function.  Invoked when a wide character could not be converted to
0174    the target encoding.  This function should process the character and may
0175    produce replacement bytes (in the target encoding) by calling the
0176    write_replacement callback repeatedly.  */
0177 typedef void (*iconv_wchar_wc_to_mb_fallback)
0178              (wchar_t code,
0179               void (*write_replacement) (const char *buf, size_t buflen,
0180                                          void* callback_arg),
0181               void* callback_arg,
0182               void* data);
0183 /* Set of fallbacks. */
0184 struct iconv_fallbacks {
0185   iconv_unicode_mb_to_uc_fallback mb_to_uc_fallback;
0186   iconv_unicode_uc_to_mb_fallback uc_to_mb_fallback;
0187   iconv_wchar_mb_to_wc_fallback mb_to_wc_fallback;
0188   iconv_wchar_wc_to_mb_fallback wc_to_mb_fallback;
0189   void* data;
0190 };
0191
0192 /* Surfaces.
0193    The concept of surfaces is described in the 'recode' manual.  */
0194 #define ICONV_SURFACE_NONE             0
0195 /* In EBCDIC encodings, 0x15 (which encodes the "newline function", see the
0196    Unicode standard, chapter 5) maps to U+000A instead of U+0085.  This is
0197    for interoperability with C programs and Unix environments on z/OS.  */
0198 #define ICONV_SURFACE_EBCDIC_ZOS_UNIX  1
0199
0200 /* Requests for iconvctl. */
0201 #define ICONV_TRIVIALP                    0  /* int *argument */
0202 #define ICONV_GET_TRANSLITERATE           1  /* int *argument */
0203 #define ICONV_SET_TRANSLITERATE           2  /* const int *argument */
0204 #define ICONV_GET_DISCARD_ILSEQ           3  /* int *argument */
0205 #define ICONV_SET_DISCARD_ILSEQ           4  /* const int *argument */
0206 #define ICONV_SET_HOOKS                   5  /* const struct iconv_hooks *argument */
0207 #define ICONV_SET_FALLBACKS               6  /* const struct iconv_fallbacks *argument */
0208 #define ICONV_GET_FROM_SURFACE            7  /* unsigned int *argument */
0209 #define ICONV_SET_FROM_SURFACE            8  /* const unsigned int *argument */
0210 #define ICONV_GET_TO_SURFACE              9  /* unsigned int *argument */
0211 #define ICONV_SET_TO_SURFACE             10  /* const unsigned int *argument */
0212 #define ICONV_GET_DISCARD_INVALID        11  /* int *argument */
0213 #define ICONV_SET_DISCARD_INVALID        12  /* const int *argument */
0214 #define ICONV_GET_DISCARD_NON_IDENTICAL  13  /* int *argument */
0215 #define ICONV_SET_DISCARD_NON_IDENTICAL  14  /* const int *argument */
0216
0217 /* Listing of locale independent encodings. */
0218 #define iconvlist libiconvlist
0219 extern void iconvlist (int (*do_one) (unsigned int namescount,
0220                                       const char * const * names,
0221                                       void* data),
0222                        void* data);
0223
0224 /* Canonicalize an encoding name.
0225    The result is either a canonical encoding name, or name itself. */
0226 extern const char * iconv_canonicalize (const char * name);
0227
0228 /* Support for relocatable packages.  */
0229
0230 /* Sets the original and the current installation prefix of the package.
0231    Relocation simply replaces a pathname starting with the original prefix
0232    by the corresponding pathname with the current prefix instead.  Both
0233    prefixes should be directory names without trailing slash (i.e. use ""
0234    instead of "/").  */
0235 extern void libiconv_set_relocation_prefix (const char *orig_prefix,
0236                                             const char *curr_prefix);
0237
0238 #ifdef __cplusplus
0239 }
0240 #endif
0241
0242
0243 #endif /* _LIBICONV_H */