1 /* Charset conversion with out-of-memory checking.
2 Copyright (C) 2001-2007, 2009-2023 Free Software Foundation, Inc.
3 Written by Bruno Haible and Simon Josefsson.
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program 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 General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
17
18 #ifndef _XSTRICONVEH_H
19 #define _XSTRICONVEH_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
28 /* Get the 'enum iconv_ilseq_handler' and iconveh_t types, and the
29 iconveh_open, iconveh_close declarations. */
30 #include "striconveh.h"
31
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37
38 #if HAVE_ICONV
39
40 /* Convert an entire string from one encoding to another, using iconv.
41 The original string is at [SRC,...,SRC+SRCLEN-1].
42 CD points to the conversion descriptor from FROMCODE to TOCODE, created by
43 the function iconveh_open().
44 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this
45 array is filled with offsets into the result, i.e. the character starting
46 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]],
47 and other offsets are set to (size_t)(-1).
48 *RESULTP and *LENGTH should initially be a scratch buffer and its size,
49 or *RESULTP can initially be NULL.
50 May erase the contents of the memory at *RESULTP.
51 Upon memory allocation failure, report the error and exit.
52 Return value: 0 if successful, otherwise -1 and errno set.
53 If successful: The resulting string is stored in *RESULTP and its length
54 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is
55 unchanged if no dynamic memory allocation was necessary. */
56 extern int
57 xmem_cd_iconveh (const char *src, size_t srclen,
58 const iconveh_t *cd,
59 enum iconv_ilseq_handler handler,
60 size_t *offsets,
61 char **resultp, size_t *lengthp);
62
63 /* Convert an entire string from one encoding to another, using iconv.
64 The original string is the NUL-terminated string starting at SRC.
65 CD points to the conversion descriptor from FROMCODE to TOCODE, created by
66 the function iconveh_open().
67 Both the "from" and the "to" encoding must use a single NUL byte at the end
68 of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32).
69 Allocate a malloced memory block for the result.
70 Upon memory allocation failure, report the error and exit.
71 Return value: the freshly allocated resulting NUL-terminated string if
72 successful, otherwise NULL and errno set. */
73 extern char *
74 xstr_cd_iconveh (const char *src,
75 const iconveh_t *cd,
76 enum iconv_ilseq_handler handler)
77 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
78
79 #endif
80
81 /* Convert an entire string from one encoding to another, using iconv.
82 The original string is at [SRC,...,SRC+SRCLEN-1].
83 If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this
84 array is filled with offsets into the result, i.e. the character starting
85 at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]],
86 and other offsets are set to (size_t)(-1).
87 *RESULTP and *LENGTH should initially be a scratch buffer and its size,
88 or *RESULTP can initially be NULL.
89 May erase the contents of the memory at *RESULTP.
90 Upon memory allocation failure, report the error and exit.
91 Return value: 0 if successful, otherwise -1 and errno set.
92 If successful: The resulting string is stored in *RESULTP and its length
93 in *LENGTHP. *RESULTP is set to a freshly allocated memory block, or is
94 unchanged if no dynamic memory allocation was necessary. */
95 extern int
96 xmem_iconveh (const char *src, size_t srclen,
97 const char *from_codeset, const char *to_codeset,
98 enum iconv_ilseq_handler handler,
99 size_t *offsets,
100 char **resultp, size_t *lengthp);
101
102 /* Convert an entire string from one encoding to another, using iconv.
103 The original string is the NUL-terminated string starting at SRC.
104 Both the "from" and the "to" encoding must use a single NUL byte at the
105 end of the string (i.e. not UCS-2, UCS-4, UTF-16, UTF-32).
106 Allocate a malloced memory block for the result.
107 Upon memory allocation failure, report the error and exit.
108 Return value: the freshly allocated resulting NUL-terminated string if
109 successful, otherwise NULL and errno set. */
110 extern char *
111 xstr_iconveh (const char *src,
112 const char *from_codeset, const char *to_codeset,
113 enum iconv_ilseq_handler handler)
114 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
115
116
117 #ifdef __cplusplus
118 }
119 #endif
120
121
122 #endif /* _XSTRICONVEH_H */