svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
iconvstr(3c)
iconvstr(3C) Standard C Library Functions iconvstr(3C)
NAME
iconvstr - string-based code conversion function
SYNOPSIS
#include <iconv.h>
size_t iconvstr(const char *tocode, const char *fromcode,
char *inarray, size_t *inlen, char *outarray, size_t *outlen,
int flag);
PARAMETERS
tocode
Pointer to a target codeset name string.
fromcode
Pointer to a source codeset name string.
inarray
Pointer to a byte array containing a sequence of character bytes in
fromcode codeset to be converted.
inlen
As input argument, the number of bytes to be converted in inarray.
As output argument, the number of bytes in inarray still not con‐
verted after the conversion.
outarray
Pointer to a byte array where converted character bytes in tocode
codeset can be saved.
outlen
As input argument, the number of available bytes at outarray where
converted character bytes can be saved. As output argument, after
the conversion, the number of bytes still available at outarray.
flag
Indicates possible conversion options constructed by a bitwise-in‐
clusive-OR of the following values:
ICONV_IGNORE_NULL
Normally iconvstr() stops the conversion if it encounters a
string terminating null character of fromcode from inarray even
if the value of inlen indicates there are more bytes in inar‐
ray.
With this option, the null character does not stop the conver‐
sion and the conversion continues until inlen pointed amount of
inarray bytes are all consumed for conversion or an error oc‐
curred.
ICONV_REPLACE_INVALID
Normally iconvstr() stops the conversion if it encounters ille‐
gal or incomplete characters from inarray() with a correspond‐
ing errno value.
When this option is set, iconvstr() does not stop the conver‐
sion and instead treats such characters as non-identical con‐
version cases.
DESCRIPTION
The iconvstr() function converts the sequence of characters from one
codeset, in the array specified by inarray, into a sequence of corre‐
sponding characters in another codeset, in the array specified by out‐
array. The codesets are those specified in fromcode and tocode argu‐
ments.
Unless ICONV_IGNORE_NULL is specified in flag, iconvstr() normally
stops when it encounters a string terminating null character of from‐
code from inarray regardless of the current inlen value; in that case,
it does not copy over the null character to outarray.
If ICONV_REPLACE_INVALID is not specified in flag and if a sequence of
input bytes does not form a valid character in the specified codeset,
conversion stops after the previous successfully converted character.
If ICONV_REPLACE_INVALID is not specified in flag and if the input ar‐
ray ends with an incomplete character or shift sequence, conversion
stops after the previous successfully converted bytes.
If the output array is not large enough to hold the entire converted
input, conversion stops just prior to the input bytes that would cause
the output array to overflow.
The value pointed to by inlen is decremented to reflect the number of
bytes still not converted in the input array. The value pointed to by
outlen is decremented to reflect the number of bytes still available in
the output array.
If iconvstr() encounters a character in the input array that is legal,
but for which an identical character does not exist in the target code‐
set, iconvstr() performs an implementation-defined conversion, i.e.,
non-identical conversion, on this character.
If ICONV_REPLACE_INVALID is specified in flag and if iconvstr() encoun‐
ters illegal or incomplete characters in the input array, instead of
stopping the conversion, iconvstr() treats such characters as if they
are non-identical characters and does non-identical conversions on such
character bytes.
RETURN VALUES
The iconvstr() function updates the values pointed to by inlen and
outlen arguments to reflect the extent of the conversion and returns
the number of non-identical conversions performed. If the entire string
in the input array is converted, the value pointed to by inlen will be
0. If the input conversion is stopped due to any conditions mentioned
above, the value pointed to by inlen will be non-zero and errno is set
to indicate the condition. If an error occurs, iconvstr() returns
(size_t) -1 and sets errno to indicate the error.
ERRORS
The iconvstr() function will fail if:
E2BIG Input conversion stopped due to lack of space in the output
array.
EBADF Requested conversion is not supported.
EILSEQ Input conversion stopped due to an input byte that does not
belong to the input codeset.
EINVAL Input conversion stopped due to an incomplete character or
shift sequence at the end of the input array.
EXAMPLES
Example 1 Code conversion from ISO8859-2 to UTF-8
The following example converts a null-terminated ISO8859-2 pathname
string to UTF-8 string and, in doing so, treats illegal and incomplete
characters as non-identical conversion cases. It also does not stop the
conversion even if it encounters a null byte from the input array.
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <iconv.h>
:
size_t ret;
char ib[MAXPATHLEN];
char ob[MAXPATHLEN];
size_t il, ol;
:
/*
* We got the pathname from somewhere.
*
* Calculate the length of input string including the terminating
* NULL byte and prepare other arguments for the conversion.
*/
(void) strlcpy(ib, pathname, MAXPATHLEN);
il = strlen(ib) + 1;
ol = MAXPATHLEN;
/*
* Do the conversion. If the ret > 0, that's the number of
* non-identical character conversions happened during the conversion.
* Regardless of whether we have conversion failure or not,
* outarray could contain some converted characters.
*/
ret = iconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol,
(ICONV_IGNORE_NULL|ICONV_REPLACE_INVALID));
if (ret == (size_t)-1) {
/* Code conversion not supported? */
if (errno == EBADF)
return (-1);
/* Output array too small? */
if (errno == E2BIG)
return (-2);
/* Unknown error which isn't possible BTW. */
return (-3);
}
:
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe
SEE ALSO
geniconvtbl(1), iconv(1), iconv(3C), iconv_close(3C), iconv_open(3C),
iconvctl(3C), iconv.h(3HEAD), geniconvtbl(5), attributes(7), iconv_uni‐
code(7), standards(7)
Converting Codesets in Internationalizing and Localizing Applications
in Oracle Solaris
HISTORY
The iconvstr() function was added to Solaris in the Oracle Solaris
11.0.0 release.
Oracle Solaris 11.4 25 Nov 2024 iconvstr(3C)