usr/src/man/man9f/kiconvstr.9f

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KICONVSTR 9F "Oct 16, 2007"
   7 .SH NAME
   8 kiconvstr \- string-based code conversion function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/errno.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBsize_t\fR \fBkiconvstr\fR(\fBconst char *\fR\fItocode\fR, \fBconst char *\fR\fIfromcode\fR, \fBchar *\fR\fIinarray\fR,
  19      \fBsize_t *\fR\fIinlen\fR, \fBchar *\fR\fIoutarray\fR, \fBsize_t *\fR\fIoutlen\fR, \fBint\fR \fIflag\fR, \fBint *\fR\fIerrno\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .LP
  29 The parameters for the \fBkiconvstr\fR function are as follows:
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fItocode\fR\fR
  34 .ad
  35 .RS 12n
  36 Points to a target codeset name string. Supported names are specified at
  37 \fBkiconv_open()\fR.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIfromcode\fR\fR
  44 .ad
  45 .RS 12n
  46 Points to a source codeset name string. Supported names are specified at
  47 \fBkiconv_open()\fR.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIinarray\fR\fR
  54 .ad
  55 .RS 12n
  56 Points to a byte array containing a sequence of character bytes in
  57 \fIfromcode\fR codeset to be converted.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIinlen\fR\fR
  64 .ad
  65 .RS 12n
  66 As an input parameter, the number of bytes to be converted in \fIinarray\fR. As
  67 an output parameter, the number of bytes in \fIinarray\fR still not converted
  68 after the conversion.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIoutarray\fR\fR
  75 .ad
  76 .RS 12n
  77 Points to a byte array where converted character bytes in \fItocode\fR codeset
  78 can be saved.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fIoutlen\fR\fR
  85 .ad
  86 .RS 12n
  87 As an input parameter, the number of available bytes at \fIoutarray\fR where
  88 converted character bytes can be saved. As an output parameter, the number of
  89 bytes still available at \fIoutarray\fR after the conversion.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIflag\fR\fR
  96 .ad
  97 .RS 12n
  98 Indicates possible conversion options constructed by a bitwise-inclusive-OR of
  99 the following values:
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBKICONV_IGNORE_NULL\fR\fR
 104 .ad
 105 .sp .6
 106 .RS 4n
 107 Normally, \fBkiconvstr()\fR stops the conversion if it encounters \fBNULL\fR
 108 byte even if the current \fIinlen\fR is pointing to a value larger than zero.
 109 .sp
 110 If this option is set, a \fBNULL\fR byte does not stop the conversion and the
 111 conversion continues until the number of \fIinarray\fR bytes pointed by
 112 \fIinlen\fR are all consumed for conversion or an error happened.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBKICONV_REPLACE_INVALID\fR\fR
 119 .ad
 120 .sp .6
 121 .RS 4n
 122 Normally, \fBkiconvstr()\fR stops the conversion if it encounters illegal or
 123 incomplete characters with corresponding \fIerrno\fR values.
 124 .sp
 125 If this option is set, \fBkiconvstr()\fR does not stop the conversion and
 126 instead treats such characters as non-identical conversion  cases.
 127 .RE
 128
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fIerrno\fR\fR
 135 .ad
 136 .RS 12n
 137 Indicates the error when conversion is not completed or failed. The following
 138 are possible values:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEILSEQ\fR\fR
 143 .ad
 144 .RS 13n
 145 The input conversion was stopped due to an input byte that does not belong to
 146 the input codeset.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBE2BIG\fR\fR
 153 .ad
 154 .RS 13n
 155 The input conversion was stopped due to lack of space in the output array.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBEINVAL\fR\fR
 162 .ad
 163 .RS 13n
 164 The input conversion was stopped due to an incomplete character or shift
 165 sequence at the end of the input array.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBEBADF\fR\fR
 172 .ad
 173 .RS 13n
 174 The requested conversion is not supported.
 175 .RE
 176
 177 .RE
 178
 179 .SH DESCRIPTION
 180 .sp
 181 .LP
 182 The \fBkiconvstr()\fR function converts the sequence of characters from one
 183 \fBcodeset\fR, in the array specified by \fIinarray\fR, into a sequence of
 184 corresponding characters in another \fBcodeset\fR, in the array specified by
 185 \fIoutarray\fR. The \fBcodesets\fR are those specified in \fIfromcode\fR and
 186 \fItocode\fR parameters. The \fIinarray\fR parameter points to a character byte
 187 array to the first character in the input array and \fIinlen\fR indicates the
 188 number of bytes to the end of the array to be converted. The \fIoutarray\fR
 189 parameter points to a character byte array to the first available byte in the
 190 output array and \fIoutlen\fR indicates the number of the available bytes to
 191 the end of the array. Unless \fBKICONV_IGNORE_NULL\fR is specified at flag,
 192 \fBkiconvstr()\fR function normally stops when it encounters \fBNULL\fR byte
 193 from the input array regardless of the current \fIinlen\fR value.
 194 .sp
 195 .LP
 196 If \fBKICONV_REPLACE_INVALID\fR is not specified at flag and if a sequence of
 197 input bytes does not form a valid character in the specified codeset,
 198 conversion stops after the previous successfully converted character. If
 199 \fBKICONV_REPLACE_INVALID\fR is not specified in \fIflag\fR and if the input
 200 array ends with an incomplete character or shift sequence, conversion stops
 201 after the previous successfully converted bytes. If the output array is not
 202 large enough to hold the entire converted input, conversion stops just prior to
 203 the input bytes that would cause the output array to overflow. The value
 204 pointed to by \fIinlen\fR is decremented to reflect the number of bytes still
 205 not converted in the input array. The value pointed to by \fIoutlen\fR is
 206 decremented to reflect the number of bytes still available in the output array.
 207 .sp
 208 .LP
 209 If \fBkiconvstr()\fR encounters a character in the input array that is legal,
 210 but for which an identical character does not exist in the target
 211 \fBcodeset\fR, \fBkiconvstr()\fR performs an implementation-defined conversion
 212 (that is, a non-identical conversion) on this character.
 213 .sp
 214 .LP
 215 If \fBKICONV_REPLACE_INVALID\fR is specified in \fIflag\fR and if
 216 \fBkiconvstr()\fR encounters illegal or incomplete characters in the input
 217 array, instead of stopping the conversion, \fBkiconvstr()\fR treats such
 218 characters  as if they are non-identical characters and does non-identical
 219 conversions on such character bytes.
 220 .SH RETURN VALUES
 221 .sp
 222 .LP
 223 The \fBkiconvstr()\fR function updates the values pointed to by the \fIinlen\fR
 224 and \fIoutlen\fR parameters to reflect the extent of the conversion and returns
 225 the number of non-identical conversions performed. If the entire string in the
 226 input array is converted, the value pointed to by \fIinlen\fR is 0. If the
 227 input conversion is stopped due to any conditions mentioned above, the value
 228 pointed to by \fIinlen\fR is non-zero and \fIerrno\fR is set to indicate the
 229 condition. If an error occurs, \fBkiconvstr()\fR returns (\fBsize_t\fR)-1 and
 230 sets \fIerrno\fR to indicate the error.
 231 .SH CONTEXT
 232 .sp
 233 .LP
 234 \fBkiconvstr()\fR can be called from user or interrupt context.
 235 .SH EXAMPLES
 236 .LP
 237 \fBExample 1 \fRPerforming a Code Conversion
 238 .sp
 239 .LP
 240 The following example converts a \fBNULL\fR-terminated \fBISO8859-2\fR pathname
 241 string to a \fBUTF-8\fR string and treats illegal and incomplete characters as
 242 non-identical conversion cases. The conversion does not stop even if it
 243 encounters a \fBNULL\fR byte from the input array.
 244
 245 .sp
 246 .in +2
 247 .nf
 248 #include <sys/types.h>
 249 #include <sys/errno.h>
 250 #include <sys/sunddi.h>
 251
 252         :
 253
 254 size_t ret;
 255 char ib[MAXPATHLEN];
 256 char ob[MAXPATHLEN];
 257 size_t il, ol;
 258 int err;
 259
 260         :
 261
 262 /*
 263  * We got the pathname from somewhere.
 264  *
 265  * Calculate the length of input string including the terminating
 266  * NULL byte and prepare other parameters for the conversion.
 267  */
 268 (void) strlcpy(ib, pathname, MAXPATHLEN);
 269 il = strlen(ib) + 1;
 270 ol = MAXPATHLEN;
 271
 272 /*
 273  * Do the conversion. If the ret > 0, that's the number of
 274  * non-identical character conversions happened during the conversion.
 275  * Regardless of whether we have conversion failure or not,
 276  * outarray could contain some converted characters.
 277  */
 278 ret = kiconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol,
 279                 (KICONV_IGNORE_NULL|KICONV_REPLACE_INVALID), &err);
 280 if (ret == (size_t)-1) {
 281         /* Code conversion not supported? */
 282         if (err == EBADF)
 283                 return (-1);
 284
 285         /* Output array too small? */
 286         if (err == E2BIG)
 287                 return (-2);
 288
 289         /* Unknown error which isn't possible BTW. */
 290         return (-3);
 291 }
 292 .fi
 293 .in -2
 294
 295 .SH ATTRIBUTES
 296 .sp
 297 .LP
 298 See \fBattributes\fR(5) for descriptions of the following attributes:
 299 .sp
 300
 301 .sp
 302 .TS
 303 box;
 304 c | c
 305 l | l .
 306 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 307 _
 308 Interface Stability     Committed
 309 .TE
 310
 311 .SH SEE ALSO
 312 .sp
 313 .LP
 314 \fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C),
 315 \fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C),
 316 \fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C),
 317 \fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C),
 318 \fBattributes\fR(5), \fBkiconv\fR(9F), \fBkiconv_close\fR(9F),
 319 \fBkiconv_open\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F),
 320 \fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F),
 321 \fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F),
 322 \fBuconv_u8tou32\fR(9F)
 323 .sp
 324 .LP
 325 The Unicode Standard:
 326 .sp
 327 .LP
 328 http://www.unicode.org/standard/standard.html