kiconvstr(9f)

1kiconvstr(9F)            Kernel Functions for Drivers            kiconvstr(9F)
2
3
4

NAME

6       kiconvstr - string-based code conversion function
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/errno.h>
11       #include <sys/sunddi.h>
12
13
14
15       size_t kiconvstr(const char *tocode, const char *fromcode, char *inarray,
16            size_t *inlen, char *outarray, size_t *outlen, int flag, int *errno);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI).
21

PARAMETERS

23       The parameters for the kiconvstr function are as follows:
24
25       tocode      Points to a target codeset name string. Supported names are
26                   specified at kiconv_open().
27
28
29       fromcode    Points to a source codeset name string. Supported names are
30                   specified at kiconv_open().
31
32
33       inarray     Points  to  a byte array containing a sequence of character
34                   bytes in fromcode codeset to be converted.
35
36
37       inlen       As an input parameter, the number of bytes to be  converted
38                   in  inarray. As an output parameter, the number of bytes in
39                   inarray still not converted after the conversion.
40
41
42       outarray    Points to a byte array where converted character  bytes  in
43                   tocode codeset can be saved.
44
45
46       outlen      As  an  input  parameter,  the number of available bytes at
47                   outarray where converted character bytes can be  saved.  As
48                   an output parameter, the number of bytes still available at
49                   outarray after the conversion.
50
51
52       flag        Indicates possible conversion options constructed by a bit‐
53                   wise-inclusive-OR of the following values:
54
55                   KICONV_IGNORE_NULL
56
57                       Normally,   kiconvstr()  stops  the  conversion  if  it
58                       encounters NULL byte  even  if  the  current  inlen  is
59                       pointing to a value larger than zero.
60
61                       If  this  option  is set, a NULL byte does not stop the
62                       conversion and the conversion continues until the  num‐
63                       ber  of inarray bytes pointed by inlen are all consumed
64                       for conversion or an error happened.
65
66
67                   KICONV_REPLACE_INVALID
68
69                       Normally,  kiconvstr()  stops  the  conversion  if   it
70                       encounters illegal or incomplete characters with corre‐
71                       sponding errno values.
72
73                       If this option is set, kiconvstr() does  not  stop  the
74                       conversion  and  instead treats such characters as non-
75                       identical conversion  cases.
76
77
78
79       errno       Indicates the error when conversion  is  not  completed  or
80                   failed. The following are possible values:
81
82                   EILSEQ       The  input  conversion  was  stopped due to an
83                                input byte that does not belong to  the  input
84                                codeset.
85
86
87                   E2BIG        The  input  conversion was stopped due to lack
88                                of space in the output array.
89
90
91                   EINVAL       The input conversion was  stopped  due  to  an
92                                incomplete  character or shift sequence at the
93                                end of the input array.
94
95
96                   EBADF        The requested conversion is not supported.
97
98
99

DESCRIPTION

101       The kiconvstr() function converts the sequence of characters  from  one
102       codeset,  in  the array specified by inarray, into a sequence of corre‐
103       sponding characters in another codeset, in the array specified by  out‐
104       array.  The codesets are those specified in fromcode and tocode parame‐
105       ters. The inarray parameter points to a character  byte  array  to  the
106       first  character  in  the input array and inlen indicates the number of
107       bytes to the end of the array to be converted. The  outarray  parameter
108       points  to  a  character  byte array to the first available byte in the
109       output array and outlen indicates the number of the available bytes  to
110       the  end  of the array. Unless KICONV_IGNORE_NULL is specified at flag,
111       kiconvstr() function normally stops when it encounters NULL  byte  from
112       the input array regardless of the current inlen value.
113
114
115       If KICONV_REPLACE_INVALID is not specified at flag and if a sequence of
116       input bytes does not form a valid character in the  specified  codeset,
117       conversion  stops  after the previous successfully converted character.
118       If KICONV_REPLACE_INVALID is not specified in flag  and  if  the  input
119       array  ends  with an incomplete character or shift sequence, conversion
120       stops after the previous successfully converted bytes.  If  the  output
121       array  is  not large enough to hold the entire converted input, conver‐
122       sion stops just prior to the input bytes that would  cause  the  output
123       array  to  overflow.  The  value  pointed to by inlen is decremented to
124       reflect the number of bytes still not converted in the input array. The
125       value  pointed  to  by  outlen  is decremented to reflect the number of
126       bytes still available in the output array.
127
128
129       If kiconvstr() encounters a character in the input array that is legal,
130       but for which an identical character does not exist in the target code‐
131       set, kiconvstr() performs an  implementation-defined  conversion  (that
132       is, a non-identical conversion) on this character.
133
134
135       If  KICONV_REPLACE_INVALID  is  specified  in  flag  and if kiconvstr()
136       encounters illegal or incomplete characters in the input array, instead
137       of  stopping  the conversion, kiconvstr() treats such characters  as if
138       they are non-identical characters and does non-identical conversions on
139       such character bytes.
140

RETURN VALUES

142       The kiconvstr() function updates the values pointed to by the inlen and
143       outlen parameters to reflect the extent of the conversion  and  returns
144       the number of non-identical conversions performed. If the entire string
145       in the input array is converted, the value pointed to by inlen is 0. If
146       the  input conversion is stopped due to any conditions mentioned above,
147       the value pointed to by inlen is non-zero and errno is set to  indicate
148       the  condition.  If an error occurs, kiconvstr() returns (size_t)-1 and
149       sets errno to indicate the error.
150

CONTEXT

152       kiconvstr() can be called from user or interrupt context.
153

EXAMPLES

155       Example 1 Performing a Code Conversion
156
157
158       The following example converts  a  NULL-terminated  ISO8859-2  pathname
159       string  to  a UTF-8 string and treats illegal and incomplete characters
160       as non-identical conversion cases. The conversion does not stop even if
161       it encounters a NULL byte from the input array.
162
163
164         #include <sys/types.h>
165         #include <sys/errno.h>
166         #include <sys/sunddi.h>
167
168                 :
169
170         size_t ret;
171         char ib[MAXPATHLEN];
172         char ob[MAXPATHLEN];
173         size_t il, ol;
174         int err;
175
176                 :
177
178         /*
179          * We got the pathname from somewhere.
180          *
181          * Calculate the length of input string including the terminating
182          * NULL byte and prepare other parameters for the conversion.
183          */
184         (void) strlcpy(ib, pathname, MAXPATHLEN);
185         il = strlen(ib) + 1;
186         ol = MAXPATHLEN;
187
188         /*
189          * Do the conversion. If the ret > 0, that's the number of
190          * non-identical character conversions happened during the conversion.
191          * Regardless of whether we have conversion failure or not,
192          * outarray could contain some converted characters.
193          */
194         ret = kiconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol,
195                         (KICONV_IGNORE_NULL|KICONV_REPLACE_INVALID), &err);
196         if (ret == (size_t)-1) {
197                 /* Code conversion not supported? */
198                 if (err == EBADF)
199                         return (-1);
200
201                 /* Output array too small? */
202                 if (err == E2BIG)
203                         return (-2);
204
205                 /* Unknown error which isn't possible BTW. */
206                 return (-3);
207         }
208
209

ATTRIBUTES

211       See attributes(5) for descriptions of the following attributes:
212
213
214
215
216       ┌─────────────────────────────┬─────────────────────────────┐
217       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
218       ├─────────────────────────────┼─────────────────────────────┤
219       │Interface Stability          │Committed                    │
220       └─────────────────────────────┴─────────────────────────────┘
221