u8_strcmp(9F)						   Kernel Functions for Drivers 					     u8_strcmp(9F)

NAME

       u8_strcmp - UTF-8 string comparison function

SYNOPSIS

       #include <sys/sunddi.h>

       int u8_strcmp(const char *s1, const char *s2, size_t n,
	    int flag, size_t unicode_version, int *errno);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

       s1, s2		   Pointers to null-terminated UTF-8 strings

       n		   The	maximum number of bytes to be compared.  If 0, the comparison is performed until either or both of the strings are
			   examined to the string terminating null byte.

       flag		   The possible comparison options constructed by a bit-wise-inclusive-OR of the following values:

			   U8_STRCMP_CS

			       Perform case-sensitive string comparison. This is the default.

			   U8_STRCMP_CI_UPPER

			       Perform case-insensitive string comparison based on Unicode upper case converted results of s1 and s2.

			   U8_STRCMP_CI_LOWER

			       Perform case-insensitive string comparison based on Unicode lower case converted results of s1 and s2.

			   U8_STRCMP_NFD

			       Perform string comparison after s1 and s2 have been normalized by using Unicode Normalization Form D.

			   U8_STRCMP_NFC

			       Perform string comparison after s1 and s2 have been normalized by using Unicode Normalization Form C.

			   U8_STRCMP_NFKD

			       Perform string comparison after s1 and s2 have been normalized by using Unicode Normalization Form KD.

			   U8_STRCMP_NFKC

			       Perform string comparison after s1 and s2 have been normalized by using Unicode Normalization Form KC.

			   Only one case-sensitive or case-insensitive option is allowed. Only one Unicode Normalization option is allowed.

       unicode_version	   The version of Unicode data that should be used during comparison. The following values are supported:

			   U8_UNICODE_320

			       Use Unicode 3.2.0 data during comparison.

			   U8_UNICODE_500

			       Use Unicode 5.0.0 data during comparison.

			   U8_UNICODE_LATEST

			       Use the latest Unicode version data available, which is Unicode 5.0.0.

       errno		   A non-zero value indicates that an error has occurred during comparison. The following values are supported:

			   EBADF     The specified option values are conflicting and cannot be supported.

			   EILSEQ    There was an illegal character at s1, s2, or both.

			   EINVAL    There was an incomplete character at s1, s2, or both.

			   ERANGE    The specified Unicode version value is not supported.

DESCRIPTION

       After proper pre-processing, the u8_strcmp() function compares two UTF-8 strings byte-by-byte, according to the machine ordering defined by
       the corresponding version of the Unicode Standard.

       When  multiple  comparison options are specified, Unicode Normalization is performed after case-sensitive or case-insensitive processing is
       performed.

RETURN VALUES

       The u8_strcmp() function returns an integer greater than, equal to, or less than 0 if the string pointed to by s1 is  greater  than,  equal
       to, or less than the string pointed to by s2, respectively.

       When  u8_strcmp() detects an illegal or incomplete character, such character causes the function to set errno to indicate the error. After-
       ward, the comparison is still performed on the resultant strings and a value based on byte-by-byte comparison is always returned.

CONTEXT

       The u8_strcmp() function can be called from user or interrupt context.

EXAMPLES

       Example 1 Perform simple default string comparison.

	 #include <sys/sunddi.h>

	 int
	 docmp_default(const char *u1, const char *u2) {
	     int result;
	     int ;

	     result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errno);
	     if (errno == EILSEQ)
		 return (-1);
	     if (errno == EINVAL)
		 return (-2);
	     if (errno == EBADF)
		 return (-3);
	     if (errno == ERANGE)
		 return (-4);

       Example 2 Perform upper case based case-insensitive comparison with Unicode 3.2.0 date.

	 #include <sys/sunddi.h>

	 int
	 docmp_caseinsensitive_u320(const char *u1, const char *u2) {
	     int result;
	     int errno;

	     result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER,
		 U8_UNICODE_320, &errno);
	     if (errno == EILSEQ)
		 return (-1);
	     if (errno == EINVAL)
		 return (-2);
	     if (errno == EBADF)
		 return (-3);
	     if (errno == ERANGE)
		 return (-4);

	     return (result);
	 }

       Example 3 Perform Unicode Normalization Form D.

       Perform Unicode Normalization Form D and uppercase-based case-insensitive comparison with Unicode 3.2.0 date.

	 #include <sys/sunddi.h>

	 int
	 docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) {
	     int result;
	     int errno;

	     result = u8_strcmp(u1, u2, 0,
		 (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320,
		 &errno);
	     if (errno == EILSEQ)
		 return (-1);
	     if (errno == EINVAL)
		 return (-2);
	     if (errno == EBADF)
		 return (-3);
	     if (errno == ERANGE)
		 return (-4);

	     return (result);
	 }

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       u8_validate(3C), u8_textprep_str(3C), u8_validate(3C), attributes(5), u8_textprep_str(9F), u8_validate(9F), uconv_u16tou32(9F)

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

SunOS 5.11							    18 Sep 2007 						     u8_strcmp(9F)