iconv.h (11146B)
1 /* Copyright (C) 1999-2023 Free Software Foundation, Inc. 2 This file is part of the GNU LIBICONV Library. 3 4 The GNU LIBICONV Library is free software; you can redistribute it 5 and/or modify it under the terms of the GNU Lesser General Public 6 License as published by the Free Software Foundation; either version 2.1 7 of the License, or (at your option) any later version. 8 9 The GNU LIBICONV Library is distributed in the hope that it will be 10 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 Lesser General Public License for more details. 13 14 You should have received a copy of the GNU Lesser General Public 15 License along with the GNU LIBICONV Library; see the file COPYING.LIB. 16 If not, see <https://www.gnu.org/licenses/>. */ 17 18 /* When installed, this file is called "iconv.h". */ 19 20 #ifndef _LIBICONV_H 21 #define _LIBICONV_H 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #define _LIBICONV_VERSION 0x0111 /* version number: (major<<8) + minor */ 28 29 #if 1 && BUILDING_LIBICONV 30 # define LIBICONV_SHLIB_EXPORTED __attribute__((__visibility__("default"))) 31 #elif defined _MSC_VER && BUILDING_LIBICONV 32 /* When building with MSVC, exporting a symbol means that the object file 33 contains a "linker directive" of the form /EXPORT:symbol. This can be 34 inspected through the "objdump -s --section=.drectve FILE" or 35 "dumpbin /directives FILE" commands. 36 The symbols from this file should be exported if and only if the object 37 file gets included in a DLL. Libtool, on Windows platforms, defines 38 the C macro DLL_EXPORT (together with PIC) when compiling for a shared 39 library (called DLL under Windows) and does not define it when compiling 40 an object file meant to be linked statically into some executable. */ 41 # if defined DLL_EXPORT 42 # define LIBICONV_SHLIB_EXPORTED __declspec(dllexport) 43 # else 44 # define LIBICONV_SHLIB_EXPORTED 45 # endif 46 #else 47 # define LIBICONV_SHLIB_EXPORTED 48 #endif 49 extern LIBICONV_SHLIB_EXPORTED int _libiconv_version; /* Likewise */ 50 51 #ifdef __cplusplus 52 } 53 #endif 54 55 /* We would like to #include any system header file which could define 56 iconv_t, 1. in order to eliminate the risk that the user gets compilation 57 errors because some other system header file includes /usr/include/iconv.h 58 which defines iconv_t or declares iconv after this file, 2. when compiling 59 for LIBICONV_PLUG, we need the proper iconv_t type in order to produce 60 binary compatible code. 61 But gcc's #include_next is not portable. Thus, once libiconv's iconv.h 62 has been installed in /usr/local/include, there is no way any more to 63 include the original /usr/include/iconv.h. We simply have to get away 64 without it. 65 Ad 1. The risk that a system header file does 66 #include "iconv.h" or #include_next "iconv.h" 67 is small. They all do #include <iconv.h>. 68 Ad 2. The iconv_t type is a pointer type in all cases I have seen. (It 69 has to be a scalar type because (iconv_t)(-1) is a possible return value 70 from iconv_open().) */ 71 72 /* Define iconv_t ourselves. */ 73 #undef iconv_t 74 #define iconv_t libiconv_t 75 typedef void* iconv_t; 76 77 /* Get size_t declaration. 78 Get wchar_t declaration if it exists. */ 79 #include <stddef.h> 80 81 /* Get errno declaration and values. */ 82 #include <errno.h> 83 /* Some systems, like SunOS 4, don't have EILSEQ. Some systems, like BSD/OS, 84 have EILSEQ in a different header. On these systems, define EILSEQ 85 ourselves. */ 86 #ifndef EILSEQ 87 #define EILSEQ 88 #endif 89 90 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 96 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to 97 encoding ‘tocode’. */ 98 #ifndef LIBICONV_PLUG 99 #define iconv_open libiconv_open 100 #endif 101 extern LIBICONV_SHLIB_EXPORTED iconv_t iconv_open (const char* tocode, const char* fromcode); 102 103 /* Converts, using conversion descriptor ‘cd’, at most ‘*inbytesleft’ bytes 104 starting at ‘*inbuf’, writing at most ‘*outbytesleft’ bytes starting at 105 ‘*outbuf’. 106 Decrements ‘*inbytesleft’ and increments ‘*inbuf’ by the same amount. 107 Decrements ‘*outbytesleft’ and increments ‘*outbuf’ by the same amount. */ 108 #ifndef LIBICONV_PLUG 109 #define iconv libiconv 110 #endif 111 extern LIBICONV_SHLIB_EXPORTED size_t iconv (iconv_t cd, char* * inbuf, size_t *inbytesleft, char* * outbuf, size_t *outbytesleft); 112 113 /* Frees resources allocated for conversion descriptor ‘cd’. */ 114 #ifndef LIBICONV_PLUG 115 #define iconv_close libiconv_close 116 #endif 117 extern LIBICONV_SHLIB_EXPORTED int iconv_close (iconv_t cd); 118 119 120 #ifdef __cplusplus 121 } 122 #endif 123 124 125 #ifndef LIBICONV_PLUG 126 127 /* Nonstandard extensions. */ 128 129 #if 1 130 #if 0 131 /* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before 132 <wchar.h>. 133 BSD/OS 4.0.1 has a bug: <stddef.h>, <stdio.h> and <time.h> must be 134 included before <wchar.h>. */ 135 #include <stddef.h> 136 #include <stdio.h> 137 #include <time.h> 138 #endif 139 #include <wchar.h> 140 #endif 141 142 #ifdef __cplusplus 143 extern "C" { 144 #endif 145 146 /* A type that holds all memory needed by a conversion descriptor. 147 A pointer to such an object can be used as an iconv_t. */ 148 typedef struct { 149 void* dummy1[28]; 150 #if 1 151 mbstate_t dummy2; 152 #endif 153 } iconv_allocation_t; 154 155 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to 156 encoding ‘tocode’ into preallocated memory. Returns an error indicator 157 (0 or -1 with errno set). */ 158 #define iconv_open_into libiconv_open_into 159 extern LIBICONV_SHLIB_EXPORTED int iconv_open_into (const char* tocode, const char* fromcode, 160 iconv_allocation_t* resultp); 161 162 /* Control of attributes. */ 163 #define iconvctl libiconvctl 164 extern LIBICONV_SHLIB_EXPORTED int iconvctl (iconv_t cd, int request, void* argument); 165 166 /* Hook performed after every successful conversion of a Unicode character. */ 167 typedef void (*iconv_unicode_char_hook) (unsigned int uc, void* data); 168 /* Hook performed after every successful conversion of a wide character. */ 169 typedef void (*iconv_wide_char_hook) (wchar_t wc, void* data); 170 /* Set of hooks. */ 171 struct iconv_hooks { 172 iconv_unicode_char_hook uc_hook; 173 iconv_wide_char_hook wc_hook; 174 void* data; 175 }; 176 177 /* Fallback function. Invoked when a small number of bytes could not be 178 converted to a Unicode character. This function should process all 179 bytes from inbuf and may produce replacement Unicode characters by calling 180 the write_replacement callback repeatedly. */ 181 typedef void (*iconv_unicode_mb_to_uc_fallback) 182 (const char* inbuf, size_t inbufsize, 183 void (*write_replacement) (const unsigned int *buf, size_t buflen, 184 void* callback_arg), 185 void* callback_arg, 186 void* data); 187 /* Fallback function. Invoked when a Unicode character could not be converted 188 to the target encoding. This function should process the character and 189 may produce replacement bytes (in the target encoding) by calling the 190 write_replacement callback repeatedly. */ 191 typedef void (*iconv_unicode_uc_to_mb_fallback) 192 (unsigned int code, 193 void (*write_replacement) (const char *buf, size_t buflen, 194 void* callback_arg), 195 void* callback_arg, 196 void* data); 197 #if 0 198 /* Fallback function. Invoked when a number of bytes could not be converted to 199 a wide character. This function should process all bytes from inbuf and may 200 produce replacement wide characters by calling the write_replacement 201 callback repeatedly. */ 202 typedef void (*iconv_wchar_mb_to_wc_fallback) 203 (const char* inbuf, size_t inbufsize, 204 void (*write_replacement) (const wchar_t *buf, size_t buflen, 205 void* callback_arg), 206 void* callback_arg, 207 void* data); 208 /* Fallback function. Invoked when a wide character could not be converted to 209 the target encoding. This function should process the character and may 210 produce replacement bytes (in the target encoding) by calling the 211 write_replacement callback repeatedly. */ 212 typedef void (*iconv_wchar_wc_to_mb_fallback) 213 (wchar_t code, 214 void (*write_replacement) (const char *buf, size_t buflen, 215 void* callback_arg), 216 void* callback_arg, 217 void* data); 218 #else 219 /* If the wchar_t type does not exist, these two fallback functions are never 220 invoked. Their argument list therefore does not matter. */ 221 typedef void (*iconv_wchar_mb_to_wc_fallback) (); 222 typedef void (*iconv_wchar_wc_to_mb_fallback) (); 223 #endif 224 /* Set of fallbacks. */ 225 struct iconv_fallbacks { 226 iconv_unicode_mb_to_uc_fallback mb_to_uc_fallback; 227 iconv_unicode_uc_to_mb_fallback uc_to_mb_fallback; 228 iconv_wchar_mb_to_wc_fallback mb_to_wc_fallback; 229 iconv_wchar_wc_to_mb_fallback wc_to_mb_fallback; 230 void* data; 231 }; 232 233 /* Surfaces. 234 The concept of surfaces is described in the 'recode' manual. */ 235 #define ICONV_SURFACE_NONE 0 236 /* In EBCDIC encodings, 0x15 (which encodes the "newline function", see the 237 Unicode standard, chapter 5) maps to U+000A instead of U+0085. This is 238 for interoperability with C programs and Unix environments on z/OS. */ 239 #define ICONV_SURFACE_EBCDIC_ZOS_UNIX 1 240 241 /* Requests for iconvctl. */ 242 #define ICONV_TRIVIALP 0 /* int *argument */ 243 #define ICONV_GET_TRANSLITERATE 1 /* int *argument */ 244 #define ICONV_SET_TRANSLITERATE 2 /* const int *argument */ 245 #define ICONV_GET_DISCARD_ILSEQ 3 /* int *argument */ 246 #define ICONV_SET_DISCARD_ILSEQ 4 /* const int *argument */ 247 #define ICONV_SET_HOOKS 5 /* const struct iconv_hooks *argument */ 248 #define ICONV_SET_FALLBACKS 6 /* const struct iconv_fallbacks *argument */ 249 #define ICONV_GET_FROM_SURFACE 7 /* unsigned int *argument */ 250 #define ICONV_SET_FROM_SURFACE 8 /* const unsigned int *argument */ 251 #define ICONV_GET_TO_SURFACE 9 /* unsigned int *argument */ 252 #define ICONV_SET_TO_SURFACE 10 /* const unsigned int *argument */ 253 254 /* Listing of locale independent encodings. */ 255 #define iconvlist libiconvlist 256 extern LIBICONV_SHLIB_EXPORTED void iconvlist (int (*do_one) (unsigned int namescount, 257 const char * const * names, 258 void* data), 259 void* data); 260 261 /* Canonicalize an encoding name. 262 The result is either a canonical encoding name, or name itself. */ 263 extern LIBICONV_SHLIB_EXPORTED const char * iconv_canonicalize (const char * name); 264 265 /* Support for relocatable packages. */ 266 267 /* Sets the original and the current installation prefix of the package. 268 Relocation simply replaces a pathname starting with the original prefix 269 by the corresponding pathname with the current prefix instead. Both 270 prefixes should be directory names without trailing slash (i.e. use "" 271 instead of "/"). */ 272 extern LIBICONV_SHLIB_EXPORTED void libiconv_set_relocation_prefix (const char *orig_prefix, 273 const char *curr_prefix); 274 275 #ifdef __cplusplus 276 } 277 #endif 278 279 #endif 280 281 282 #endif /* _LIBICONV_H */