source/include/iconv.h

0001 /* Copyright (C) 1999-2022 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 #define _LIBICONV_VERSION 0x0111    /* version number: (major<<8) + minor */
0024 extern  int _libiconv_version; /* Likewise */
0025
0026 /* We would like to #include any system header file which could define
0027    iconv_t, 1. in order to eliminate the risk that the user gets compilation
0028    errors because some other system header file includes /usr/include/iconv.h
0029    which defines iconv_t or declares iconv after this file, 2. when compiling
0030    for LIBICONV_PLUG, we need the proper iconv_t type in order to produce
0031    binary compatible code.
0032    But gcc's #include_next is not portable. Thus, once libiconv's iconv.h
0033    has been installed in /usr/local/include, there is no way any more to
0034    include the original /usr/include/iconv.h. We simply have to get away
0035    without it.
0036    Ad 1. The risk that a system header file does
0037    #include "iconv.h"  or  #include_next "iconv.h"
0038    is small. They all do #include <iconv.h>.
0039    Ad 2. The iconv_t type is a pointer type in all cases I have seen. (It
0040    has to be a scalar type because (iconv_t)(-1) is a possible return value
0041    from iconv_open().) */
0042
0043 /* Define iconv_t ourselves. */
0044 #undef iconv_t
0045 #define iconv_t libiconv_t
0046 typedef void* iconv_t;
0047
0048 /* Get size_t declaration.
0049    Get wchar_t declaration if it exists. */
0050 #include <stddef.h>
0051
0052 /* Get errno declaration and values. */
0053 #include <errno.h>
0054 /* Some systems, like SunOS 4, don't have EILSEQ. Some systems, like BSD/OS,
0055    have EILSEQ in a different header.  On these systems, define EILSEQ
0056    ourselves. */
0057 #ifndef EILSEQ
0058 #define EILSEQ
0059 #endif
0060
0061
0062 #ifdef __cplusplus
0063 extern "C" {
0064 #endif
0065
0066
0067 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
0068    encoding ‘tocode’. */
0069 #ifndef LIBICONV_PLUG
0070 #define iconv_open libiconv_open
0071 #endif
0072 extern iconv_t iconv_open (const char* tocode, const char* fromcode);
0073
0074 /* Converts, using conversion descriptor ‘cd’, at most ‘*inbytesleft’ bytes
0075    starting at ‘*inbuf’, writing at most ‘*outbytesleft’ bytes starting at
0076    ‘*outbuf’.
0077    Decrements ‘*inbytesleft’ and increments ‘*inbuf’ by the same amount.
0078    Decrements ‘*outbytesleft’ and increments ‘*outbuf’ by the same amount. */
0079 #ifndef LIBICONV_PLUG
0080 #define iconv libiconv
0081 #endif
0082 extern size_t iconv (iconv_t cd,  char* * inbuf, size_t *inbytesleft, char* * outbuf, size_t *outbytesleft);
0083
0084 /* Frees resources allocated for conversion descriptor ‘cd’. */
0085 #ifndef LIBICONV_PLUG
0086 #define iconv_close libiconv_close
0087 #endif
0088 extern int iconv_close (iconv_t cd);
0089
0090
0091 #ifdef __cplusplus
0092 }
0093 #endif
0094
0095
0096 #ifndef LIBICONV_PLUG
0097
0098 /* Nonstandard extensions. */
0099
0100 #if 1
0101 #if 0
0102 /* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
0103    <wchar.h>.
0104    BSD/OS 4.0.1 has a bug: <stddef.h>, <stdio.h> and <time.h> must be
0105    included before <wchar.h>.  */
0106 #include <stddef.h>
0107 #include <stdio.h>
0108 #include <time.h>
0109 #endif
0110 #include <wchar.h>
0111 #endif
0112
0113 #ifdef __cplusplus
0114 extern "C" {
0115 #endif
0116
0117 /* A type that holds all memory needed by a conversion descriptor.
0118    A pointer to such an object can be used as an iconv_t. */
0119 typedef struct {
0120   void* dummy1[28];
0121 #if 1
0122   mbstate_t dummy2;
0123 #endif
0124 } iconv_allocation_t;
0125
0126 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
0127    encoding ‘tocode’ into preallocated memory. Returns an error indicator
0128    (0 or -1 with errno set). */
0129 #define iconv_open_into libiconv_open_into
0130 extern int iconv_open_into (const char* tocode, const char* fromcode,
0131                             iconv_allocation_t* resultp);
0132
0133 /* Control of attributes. */
0134 #define iconvctl libiconvctl
0135 extern int iconvctl (iconv_t cd, int request, void* argument);
0136
0137 /* Hook performed after every successful conversion of a Unicode character. */
0138 typedef void (*iconv_unicode_char_hook) (unsigned int uc, void* data);
0139 /* Hook performed after every successful conversion of a wide character. */
0140 typedef void (*iconv_wide_char_hook) (wchar_t wc, void* data);
0141 /* Set of hooks. */
0142 struct iconv_hooks {
0143   iconv_unicode_char_hook uc_hook;
0144   iconv_wide_char_hook wc_hook;
0145   void* data;
0146 };
0147
0148 /* Fallback function.  Invoked when a small number of bytes could not be
0149    converted to a Unicode character.  This function should process all
0150    bytes from inbuf and may produce replacement Unicode characters by calling
0151    the write_replacement callback repeatedly.  */
0152 typedef void (*iconv_unicode_mb_to_uc_fallback)
0153              (const char* inbuf, size_t inbufsize,
0154               void (*write_replacement) (const unsigned int *buf, size_t buflen,
0155                                          void* callback_arg),
0156               void* callback_arg,
0157               void* data);
0158 /* Fallback function.  Invoked when a Unicode character could not be converted
0159    to the target encoding.  This function should process the character and
0160    may produce replacement bytes (in the target encoding) by calling the
0161    write_replacement callback repeatedly.  */
0162 typedef void (*iconv_unicode_uc_to_mb_fallback)
0163              (unsigned int code,
0164               void (*write_replacement) (const char *buf, size_t buflen,
0165                                          void* callback_arg),
0166               void* callback_arg,
0167               void* data);
0168 #if 1
0169 /* Fallback function.  Invoked when a number of bytes could not be converted to
0170    a wide character.  This function should process all bytes from inbuf and may
0171    produce replacement wide characters by calling the write_replacement
0172    callback repeatedly.  */
0173 typedef void (*iconv_wchar_mb_to_wc_fallback)
0174              (const char* inbuf, size_t inbufsize,
0175               void (*write_replacement) (const wchar_t *buf, size_t buflen,
0176                                          void* callback_arg),
0177               void* callback_arg,
0178               void* data);
0179 /* Fallback function.  Invoked when a wide character could not be converted to
0180    the target encoding.  This function should process the character and may
0181    produce replacement bytes (in the target encoding) by calling the
0182    write_replacement callback repeatedly.  */
0183 typedef void (*iconv_wchar_wc_to_mb_fallback)
0184              (wchar_t code,
0185               void (*write_replacement) (const char *buf, size_t buflen,
0186                                          void* callback_arg),
0187               void* callback_arg,
0188               void* data);
0189 #else
0190 /* If the wchar_t type does not exist, these two fallback functions are never
0191    invoked.  Their argument list therefore does not matter.  */
0192 typedef void (*iconv_wchar_mb_to_wc_fallback) ();
0193 typedef void (*iconv_wchar_wc_to_mb_fallback) ();
0194 #endif
0195 /* Set of fallbacks. */
0196 struct iconv_fallbacks {
0197   iconv_unicode_mb_to_uc_fallback mb_to_uc_fallback;
0198   iconv_unicode_uc_to_mb_fallback uc_to_mb_fallback;
0199   iconv_wchar_mb_to_wc_fallback mb_to_wc_fallback;
0200   iconv_wchar_wc_to_mb_fallback wc_to_mb_fallback;
0201   void* data;
0202 };
0203
0204 /* Requests for iconvctl. */
0205 #define ICONV_TRIVIALP            0  /* int *argument */
0206 #define ICONV_GET_TRANSLITERATE   1  /* int *argument */
0207 #define ICONV_SET_TRANSLITERATE   2  /* const int *argument */
0208 #define ICONV_GET_DISCARD_ILSEQ   3  /* int *argument */
0209 #define ICONV_SET_DISCARD_ILSEQ   4  /* const int *argument */
0210 #define ICONV_SET_HOOKS           5  /* const struct iconv_hooks *argument */
0211 #define ICONV_SET_FALLBACKS       6  /* const struct iconv_fallbacks *argument */
0212
0213 /* Listing of locale independent encodings. */
0214 #define iconvlist libiconvlist
0215 extern void iconvlist (int (*do_one) (unsigned int namescount,
0216                                       const char * const * names,
0217                                       void* data),
0218                        void* data);
0219
0220 /* Canonicalize an encoding name.
0221    The result is either a canonical encoding name, or name itself. */
0222 extern const char * iconv_canonicalize (const char * name);
0223
0224 /* Support for relocatable packages.  */
0225
0226 /* Sets the original and the current installation prefix of the package.
0227    Relocation simply replaces a pathname starting with the original prefix
0228    by the corresponding pathname with the current prefix instead.  Both
0229    prefixes should be directory names without trailing slash (i.e. use ""
0230    instead of "/").  */
0231 extern void libiconv_set_relocation_prefix (const char *orig_prefix,
0232                                             const char *curr_prefix);
0233
0234 #ifdef __cplusplus
0235 }
0236 #endif
0237
0238 #endif
0239
0240
0241 #endif /* _LIBICONV_H */