U8_STRCMP(9F) Kernel Functions for Drivers U8_STRCMP(9F)
u8_strcmp - UTF-8 string comparison function
#include <sys/sunddi.h>
int u8_strcmp(const char *s1, const char *s2, size_t n,
int flag, size_t unicode_version, int *errno);
illumos DDI specific (illumos DDI)
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.
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.
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.
Afterward, the comparison is still performed on the resultant strings
and a value based on byte-by-byte comparison is always returned.
The u8_strcmp() function can be called from user or interrupt
context.
#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);
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);
}
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);
}
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
u8_textprep_str(3C), u8_validate(3C), attributes(7),
u8_textprep_str(9F), u8_validate(9F), uconv_u16tou32(9F)
The Unicode Standard (http://www.unicode.org)
February 21, 2023 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
illumos DDI specific (illumos 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.
Afterward, 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(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
SEE ALSO
u8_textprep_str(3C), u8_validate(3C), attributes(7),
u8_textprep_str(9F), u8_validate(9F), uconv_u16tou32(9F)
The Unicode Standard (http://www.unicode.org)
February 21, 2023 U8_STRCMP(9F)