1 /* Character set conversion with error handling.
2 Copyright (C) 2001-2007, 2009-2023 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 /* This file uses _GL_ATTRIBUTE_MALLOC, HAVE_ICONV. */
22 #if !_GL_CONFIG_H_INCLUDED
23 #error "Please include config.h first."
24 #endif
25
26 #include <stdlib.h>
27 #if HAVE_ICONV
28 #include <iconv.h>
29 #endif
30
31 #include "iconveh.h"
32
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38
39 #if HAVE_ICONV
40
41 /* A conversion descriptor for use by the iconveh functions. */
42 typedef struct
43 {
44 /* Conversion descriptor from FROM_CODESET to TO_CODESET, or (iconv_t)(-1)
45 if the system does not support a direct conversion from FROM_CODESET to
46 TO_CODESET. */
47 iconv_t cd;
48 /* Conversion descriptor from FROM_CODESET to UTF-8 (or (iconv_t)(-1) if
49 FROM_CODESET is UTF-8). */
50 iconv_t cd1;
51 /* Conversion descriptor from UTF-8 to TO_CODESET (or (iconv_t)(-1) if
52 TO_CODESET is UTF-8). */
53 iconv_t cd2;
54 }
55 iconveh_t;
56
57 /* Open a conversion descriptor for use by the iconveh functions.
58 If successful, fills *CDP and returns 0. Upon failure, return -1 with errno
59 set. */
60 extern int
61 iconveh_open (const char *to_codeset, const char *from_codeset,
62 iconveh_t *cdp);
63
64 /* Close a conversion descriptor created by iconveh_open().
65 Return value: 0 if successful, otherwise -1 and errno set. */
66 extern int
67 iconveh_close (const iconveh_t *cd);
68
69 /* Convert an entire string from one encoding to another, using iconv.
70 The original string is at [SRC,...,SRC+SRCLEN-1].
71 CD points to the conversion descriptor from FROMCODE to TOCODE, created by
72 the function iconveh_open().
73 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this
74 array is filled with offsets into the result, i.e. the character starting
75 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]],
76 and other offsets are set to (size_t)(-1).
77 *RESULTP and *LENGTH should initially be a scratch buffer and its size,
78 or *RESULTP can initially be NULL.
79 May erase the contents of the memory at *RESULTP.
80 Return value: 0 if successful, otherwise -1 and errno set.
81 If successful: The resulting string is stored in *RESULTP and its length
82 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is
83 unchanged if no dynamic memory allocation was necessary. */
84 extern int
85 mem_cd_iconveh (const char *src, size_t srclen,
86 const iconveh_t *cd,
87 enum iconv_ilseq_handler handler,
88 size_t *offsets,
89 char **resultp, size_t *lengthp);
90
91 /* Convert an entire string from one encoding to another, using iconv.
92 The original string is the NUL-terminated string starting at SRC.
93 CD points to the conversion descriptor from FROMCODE to TOCODE, created by
94 the function iconveh_open().
95 Both the "from" and the "to" encoding must use a single NUL byte at the end
96 of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32).
97 Allocate a malloced memory block for the result.
98 Return value: the freshly allocated resulting NUL-terminated string if
99 successful, otherwise NULL and errno set. */
100 extern char *
101 str_cd_iconveh (const char *src,
102 const iconveh_t *cd,
103 enum iconv_ilseq_handler handler)
104 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
105
106 #endif
107
108 /* Convert an entire string from one encoding to another, using iconv.
109 The original string is at [SRC,...,SRC+SRCLEN-1].
110 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this
111 array is filled with offsets into the result, i.e. the character starting
112 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]],
113 and other offsets are set to (size_t)(-1).
114 *RESULTP and *LENGTH should initially be a scratch buffer and its size,
115 or *RESULTP can initially be NULL.
116 May erase the contents of the memory at *RESULTP.
117 Return value: 0 if successful, otherwise -1 and errno set.
118 If successful: The resulting string is stored in *RESULTP and its length
119 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is
120 unchanged if no dynamic memory allocation was necessary. */
121 extern int
122 mem_iconveh (const char *src, size_t srclen,
123 const char *from_codeset, const char *to_codeset,
124 enum iconv_ilseq_handler handler,
125 size_t *offsets,
126 char **resultp, size_t *lengthp);
127
128 /* Convert an entire string from one encoding to another, using iconv.
129 The original string is the NUL-terminated string starting at SRC.
130 Both the "from" and the "to" encoding must use a single NUL byte at the
131 end of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32).
132 Allocate a malloced memory block for the result.
133 Return value: the freshly allocated resulting NUL-terminated string if
134 successful, otherwise NULL and errno set. */
135 extern char *
136 str_iconveh (const char *src,
137 const char *from_codeset, const char *to_codeset,
138 enum iconv_ilseq_handler handler)
139 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
140
141
142 #ifdef __cplusplus
143 }
144 #endif
145
146
147 #endif /* _STRICONVEH_H */