* README: Document signed integer overflow situation more
[gnulib.git] / lib / uniconv.h
1 /* Conversions between Unicode and legacy encodings.
2    Copyright (C) 2002, 2005, 2007 Free Software Foundation, Inc.
3
4    This program is free software; you can redistribute it and/or modify it
5    under the terms of the GNU Library General Public License as published
6    by the Free Software Foundation; either version 2, or (at your option)
7    any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    Library General Public License for more details.
13
14    You should have received a copy of the GNU Library General Public
15    License along with this program; if not, write to the Free Software
16    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
17    USA.  */
18
19 #ifndef _UNICONV_H
20 #define _UNICONV_H
21
22 /* Get size_t.  */
23 #include <stddef.h>
24
25 #include "unitypes.h"
26
27 /* Get enum iconv_ilseq_handler.  */
28 #include "striconveh.h"
29
30 /* Get iconv_register_autodetect(), mem_iconveha() declaration.  */
31 #include "striconveha.h"
32
33 /* Get locale_charset() declaration.  */
34 #include "localcharset.h"
35
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41
42 /* Converts an entire string, possibly including NUL bytes, from one encoding
43    to a Unicode encoding.
44    Converts a memory region given in encoding FROMCODE.  FROMCODE is as for
45    iconv_open(3).
46    The input is in the memory region between SRC (inclusive) and SRC + SRCLEN
47    (exclusive).
48    If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this
49    array is filled with offsets into the result, i.e. the character starting
50    at SRC[i] corresponds to the character starting at (*RESULTP)[OFFSETS[i]],
51    and other offsets are set to (size_t)(-1).
52    *RESULTP and *LENGTH should initially be a scratch buffer and its size,
53    or *RESULTP can initially be NULL.
54    May erase the contents of the memory at *RESULTP.
55    Return value: 0 if successful, otherwise -1 and errno set.
56    If successful: The resulting string is stored in *RESULTP and its length
57    in *LENGTHP.  *RESULTP is set to a freshly allocated memory block, or is
58    unchanged if no dynamic memory allocation was necessary.
59    Particular errno values: EINVAL, EILSEQ, ENOMEM.  */
60 extern int
61        u8_conv_from_encoding (const char *fromcode,
62                               enum iconv_ilseq_handler handler,
63                               const char *src, size_t srclen,
64                               size_t *offsets,
65                               uint8_t **resultp, size_t *lengthp);
66 extern int
67        u16_conv_from_encoding (const char *fromcode,
68                                enum iconv_ilseq_handler handler,
69                                const char *src, size_t srclen,
70                                size_t *offsets,
71                                uint16_t **resultp, size_t *lengthp);
72 extern int
73        u32_conv_from_encoding (const char *fromcode,
74                                enum iconv_ilseq_handler handler,
75                                const char *src, size_t srclen,
76                                size_t *offsets,
77                                uint32_t **resultp, size_t *lengthp);
78
79 /* Converts a NUL terminated string from a given encoding.
80    The result is malloc allocated, or NULL (with errno set) in case of error.
81    Particular errno values: EILSEQ, ENOMEM.  */
82 extern uint8_t *
83        u8_strconv_from_encoding (const char *string,
84                                  const char *fromcode,
85                                  enum iconv_ilseq_handler handler);
86 extern uint16_t *
87        u16_strconv_from_encoding (const char *string,
88                                   const char *fromcode,
89                                   enum iconv_ilseq_handler handler);
90 extern uint32_t *
91        u32_strconv_from_encoding (const char *string,
92                                   const char *fromcode,
93                                   enum iconv_ilseq_handler handler);
94
95 /* Converts a NUL terminated string to a given encoding.
96    The result is malloc allocated, or NULL (with errno set) in case of error.
97    Particular errno values: EILSEQ, ENOMEM.  */
98 extern char *
99        u8_strconv_to_encoding (const uint8_t *string,
100                                const char *tocode,
101                                enum iconv_ilseq_handler handler);
102 extern char *
103        u16_strconv_to_encoding (const uint16_t *string,
104                                 const char *tocode,
105                                 enum iconv_ilseq_handler handler);
106 extern char *
107        u32_strconv_to_encoding (const uint32_t *string,
108                                 const char *tocode,
109                                 enum iconv_ilseq_handler handler);
110
111 /* Converts a NUL terminated string from the locale encoding.
112    The result is malloc allocated, or NULL (with errno set) in case of error.
113    Particular errno values: ENOMEM.  */
114 extern uint8_t *
115        u8_strconv_from_locale (const char *string);
116 extern uint16_t *
117        u16_strconv_from_locale (const char *string);
118 extern uint32_t *
119        u32_strconv_from_locale (const char *string);
120
121 /* Converts a NUL terminated string to the locale encoding.
122    The result is malloc allocated, or NULL (with errno set) in case of error.
123    Particular errno values: ENOMEM.  */
124 extern char *
125        u8_strconv_to_locale (const uint8_t *string);
126 extern char *
127        u16_strconv_to_locale (const uint16_t *string);
128 extern char *
129        u32_strconv_to_locale (const uint32_t *string);
130
131
132 #ifdef __cplusplus
133 }
134 #endif
135
136 #endif /* _UNICONV_H */