1 /* Character set conversion with error handling. 2 Copyright (C) 2001-2007, 2009-2021 Free Software Foundation, Inc. 3 Written by Bruno Haible and Simon Josefsson. 4 5 This file is free software: you can redistribute it and/or modify 6 it under the terms of the GNU Lesser General Public License as 7 published by the Free Software Foundation; either version 2.1 of the 8 License, or (at your option) any later version. 9 10 This file is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public License 16 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 17 18 #ifndef _STRICONVEH_H 19 #define _STRICONVEH_H 20 21 #include <stdlib.h> 22 #if HAVE_ICONV 23 #include <iconv.h> 24 #endif 25 26 #include "iconveh.h" 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 34 #if HAVE_ICONV 35 36 /* A conversion descriptor for use by the iconveh functions. */ 37 typedef struct 38 { 39 /* Conversion descriptor from FROM_CODESET to TO_CODESET, or (iconv_t)(-1) 40 if the system does not support a direct conversion from FROM_CODESET to 41 TO_CODESET. */ 42 iconv_t cd; 43 /* Conversion descriptor from FROM_CODESET to UTF-8 (or (iconv_t)(-1) if 44 FROM_CODESET is UTF-8). */ 45 iconv_t cd1; 46 /* Conversion descriptor from UTF-8 to TO_CODESET (or (iconv_t)(-1) if 47 TO_CODESET is UTF-8). */ 48 iconv_t cd2; 49 } 50 iconveh_t; 51 52 /* Open a conversion descriptor for use by the iconveh functions. 53 If successful, fills *CDP and returns 0. Upon failure, return -1 with errno 54 set. */ 55 extern int 56 iconveh_open (const char *to_codeset, const char *from_codeset, 57 iconveh_t *cdp); 58 59 /* Close a conversion descriptor created by iconveh_open(). 60 Return value: 0 if successful, otherwise -1 and errno set. */ 61 extern int 62 iconveh_close (const iconveh_t *cd); 63 64 /* Convert an entire string from one encoding to another, using iconv. 65 The original string is at [SRC,...,SRC+SRCLEN-1]. 66 CD points to the conversion descriptor from FROMCODE to TOCODE, created by 67 the function iconveh_open(). 68 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this 69 array is filled with offsets into the result, i.e. the character starting 70 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]], 71 and other offsets are set to (size_t)(-1). 72 *RESULTP and *LENGTH should initially be a scratch buffer and its size, 73 or *RESULTP can initially be NULL. 74 May erase the contents of the memory at *RESULTP. 75 Return value: 0 if successful, otherwise -1 and errno set. 76 If successful: The resulting string is stored in *RESULTP and its length 77 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is 78 unchanged if no dynamic memory allocation was necessary. */ 79 extern int 80 mem_cd_iconveh (const char *src, size_t srclen, 81 const iconveh_t *cd, 82 enum iconv_ilseq_handler handler, 83 size_t *offsets, 84 char **resultp, size_t *lengthp); 85 86 /* Convert an entire string from one encoding to another, using iconv. 87 The original string is the NUL-terminated string starting at SRC. 88 CD points to the conversion descriptor from FROMCODE to TOCODE, created by 89 the function iconveh_open(). 90 Both the "from" and the "to" encoding must use a single NUL byte at the end 91 of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32). 92 Allocate a malloced memory block for the result. 93 Return value: the freshly allocated resulting NUL-terminated string if 94 successful, otherwise NULL and errno set. */ 95 extern char * 96 str_cd_iconveh (const char *src, 97 const iconveh_t *cd, 98 enum iconv_ilseq_handler handler) 99 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE; 100 101 #endif 102 103 /* Convert an entire string from one encoding to another, using iconv. 104 The original string is at [SRC,...,SRC+SRCLEN-1]. 105 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this 106 array is filled with offsets into the result, i.e. the character starting 107 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]], 108 and other offsets are set to (size_t)(-1). 109 *RESULTP and *LENGTH should initially be a scratch buffer and its size, 110 or *RESULTP can initially be NULL. 111 May erase the contents of the memory at *RESULTP. 112 Return value: 0 if successful, otherwise -1 and errno set. 113 If successful: The resulting string is stored in *RESULTP and its length 114 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is 115 unchanged if no dynamic memory allocation was necessary. */ 116 extern int 117 mem_iconveh (const char *src, size_t srclen, 118 const char *from_codeset, const char *to_codeset, 119 enum iconv_ilseq_handler handler, 120 size_t *offsets, 121 char **resultp, size_t *lengthp); 122 123 /* Convert an entire string from one encoding to another, using iconv. 124 The original string is the NUL-terminated string starting at SRC. 125 Both the "from" and the "to" encoding must use a single NUL byte at the 126 end of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32). 127 Allocate a malloced memory block for the result. 128 Return value: the freshly allocated resulting NUL-terminated string if 129 successful, otherwise NULL and errno set. */ 130 extern char * 131 str_iconveh (const char *src, 132 const char *from_codeset, const char *to_codeset, 133 enum iconv_ilseq_handler handler) 134 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE; 135 136 137 #ifdef __cplusplus 138 } 139 #endif 140 141 142 #endif /* _STRICONVEH_H */