te
Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved.
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.
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.
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]
u8_textprep_str - string-based UTF-8 text preparation function

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>

size_t u8_textprep_str(char *inarray, size_t *inlen,
 char *outarray, size_t *outlen, int flag,
 size_t unicode_version, int *errno);

illumos DDI specific (illumos DDI) inarray inlen outarray outlen flag unicode_version errno The u8_textprep_str() function prepares the sequence of UTF-8 characters in the array specified by inarray into a sequence of corresponding UTF-8 characters prepared in the array specified by outarray. The inarray argument points to a character byte array to the first character in the input array and inlen indicates the number of bytes to the end of the array to be converted. The outarray argument points to a character byte array to the first available byte in the output array and outlen indicates the number of the available bytes to the end of the array. Unless flag is U8_TEXTPREP_IGNORE_NULL, u8_textprep_str() normally stops when it encounters a null byte from the input array regardless of the current inlen value.

If flag is U8_TEXTPREP_IGNORE_INVALID and a sequence of input bytes does not form a valid UTF-8 character, preparation stops after the previous successfully prepared character. If flag is U8_TEXTPREP_IGNORE_INVALID and the input array ends with an incomplete UTF-8 character, preparation stops after the previous successfully prepared bytes. If the output array is not large enough to hold the entire prepared text, preparation 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 prepared in the input array. The value pointed to by outlen is decremented to reflect the number of bytes still available in the output array.

The u8_textprep_str() function updates the values pointed to by inlen and outlen arguments to reflect the extent of the preparation. When U8_TEXTPREP_IGNORE_INVALID is specified, u8_textprep_str() returns the number of illegal or incomplete characters found during the text preparation. When U8_TEXTPREP_IGNORE_INVALID is not specified and the text preparation is successful, the function returns 0. If the entire string in the input array is prepared, the value pointed to by inlen will be 0. If the text preparation 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 error. If such and any other error occurs, u8_textprep_str() returns (size_t)-1 and sets errno to indicate the error. The u8_textprep_str() function can be called from user or interrupt context. Example 1 Simple UTF-8 text preparation

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>
.
.
.
size_t ret;
char ib[MAXPATHLEN];
char ob[MAXPATHLEN];
size_t il, ol;
int err;
.
.
.
/*
 * We got a UTF-8 pathname from somewhere.
 *
 * Calculate the length of input string including the terminating
 * NULL byte and prepare other arguments.
 */
(void) strlcpy(ib, pathname, MAXPATHLEN);
il = strlen(ib) + 1;
ol = MAXPATHLEN;

/*
 * Do toupper case folding, apply Unicode Normalization Form D,
 * ignore NULL byte, and ignore any illegal/incomplete characters.
 */
ret = u8_textprep_str(ib, &il, ob, &ol,
 (U8_TEXTPREP_IGNORE_NULL|U8_TEXTPREP_IGNORE_INVALID|
 U8_TEXTPREP_TOUPPER|U8_TEXTPREP_NFD), U8_UNICODE_LATEST, &err);
if (ret == (size_t)-1) {
 if (err == E2BIG)
 return (-1);
 if (err == EBADF)
 return (-2);
 if (err == ERANGE)
 return (-3);
 return (-4);
}

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

u8_strcmp (3C), u8_textprep_str (3C), u8_validate (3C), attributes (7), u8_strcmp (9F), u8_validate (9F), uconv_u16tou32 (9F)

The Unicode Standard (http://www.unicode.org)