usr/src/man/man9f/u8_strcmp.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 U8_STRCMP 9F "Sep 18, 2007"
   7 .SH NAME
   8 u8_strcmp \- UTF-8 string comparison function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunddi.h>
  13
  14 \fBint\fR \fBu8_strcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR,
  15      \fBint\fR \fIflag\fR, \fBsize_t\fR \fIunicode_version\fR, \fBint *\fR\fIerrno\fR);
  16 .fi
  17
  18 .SH INTERFACE LEVEL
  19 .sp
  20 .LP
  21 Solaris DDI specific (Solaris DDI)
  22 .SH PARAMETERS
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIs1\fR, \fIs2\fR\fR
  27 .ad
  28 .RS 20n
  29 Pointers to null-terminated UTF-8 strings
  30 .RE
  31
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIn\fR\fR
  36 .ad
  37 .RS 20n
  38 The maximum number of bytes to be compared.  If 0, the comparison is performed
  39 until either or both of the strings are examined to the string terminating null
  40 byte.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIflag\fR\fR
  47 .ad
  48 .RS 20n
  49 The possible comparison options constructed by a bit-wise-inclusive-OR of the
  50 following values:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBU8_STRCMP_CS\fR\fR
  55 .ad
  56 .sp .6
  57 .RS 4n
  58 Perform case-sensitive string comparison. This is the default.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBU8_STRCMP_CI_UPPER\fR\fR
  65 .ad
  66 .sp .6
  67 .RS 4n
  68 Perform case-insensitive string comparison based on Unicode upper case
  69 converted results of \fIs1\fR and \fIs2\fR.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBU8_STRCMP_CI_LOWER\fR\fR
  76 .ad
  77 .sp .6
  78 .RS 4n
  79 Perform case-insensitive string comparison based on Unicode lower case
  80 converted results of \fIs1\fR and \fIs2\fR.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBU8_STRCMP_NFD\fR\fR
  87 .ad
  88 .sp .6
  89 .RS 4n
  90 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
  91 using Unicode Normalization Form D.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBU8_STRCMP_NFC\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
 102 using Unicode Normalization Form C.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBU8_STRCMP_NFKD\fR\fR
 109 .ad
 110 .sp .6
 111 .RS 4n
 112 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
 113 using Unicode Normalization Form KD.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBU8_STRCMP_NFKC\fR\fR
 120 .ad
 121 .sp .6
 122 .RS 4n
 123 Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by
 124 using Unicode Normalization Form KC.
 125 .RE
 126
 127 Only one case-sensitive or case-insensitive option is allowed. Only one Unicode
 128 Normalization option is allowed.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fIunicode_version\fR\fR
 135 .ad
 136 .RS 20n
 137 The version of Unicode data that should be used during comparison. The
 138 following values are supported:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBU8_UNICODE_320\fR\fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 Use Unicode 3.2.0 data during comparison.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBU8_UNICODE_500\fR\fR
 153 .ad
 154 .sp .6
 155 .RS 4n
 156 Use Unicode 5.0.0 data during comparison.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBU8_UNICODE_LATEST\fR\fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 Use the latest Unicode version data available, which is Unicode 5.0.0.
 167 .RE
 168
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fIerrno\fR\fR
 175 .ad
 176 .RS 20n
 177 A non-zero value indicates that an error has occurred during comparison. The
 178 following values are supported:
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBEBADF\fR\fR
 183 .ad
 184 .RS 10n
 185 The specified option values are conflicting and cannot be supported.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBEILSEQ\fR\fR
 192 .ad
 193 .RS 10n
 194 There was an illegal character at \fIs1\fR, \fIs2\fR, or both.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBEINVAL\fR\fR
 201 .ad
 202 .RS 10n
 203 There was an incomplete character at \fIs1\fR, \fIs2\fR, or both.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBERANGE\fR\fR
 210 .ad
 211 .RS 10n
 212 The specified Unicode version value is not supported.
 213 .RE
 214
 215 .RE
 216
 217 .SH DESCRIPTION
 218 .sp
 219 .LP
 220 After proper pre-processing, the \fBu8_strcmp()\fR function compares two UTF-8
 221 strings byte-by-byte, according to the machine ordering defined by the
 222 corresponding version of the Unicode Standard.
 223 .sp
 224 .LP
 225 When multiple comparison options are specified, Unicode Normalization is
 226 performed after case-sensitive or case-insensitive processing is performed.
 227 .SH RETURN VALUES
 228 .sp
 229 .LP
 230 The \fBu8_strcmp()\fR function returns an integer greater than, equal to, or
 231 less than 0 if the string pointed to by \fIs1\fR is greater than, equal to, or
 232 less than the string pointed to by \fIs2\fR, respectively.
 233 .sp
 234 .LP
 235 When \fBu8_strcmp()\fR detects an illegal or incomplete character, such
 236 character causes the function to set \fIerrno\fR to indicate the error.
 237 Afterward, the comparison is still performed on the resultant strings and a
 238 value based on byte-by-byte comparison is always returned.
 239 .SH CONTEXT
 240 .sp
 241 .LP
 242 The \fBu8_strcmp()\fR function can be called from user or interrupt context.
 243 .SH EXAMPLES
 244 .LP
 245 \fBExample 1 \fRPerform simple default string comparison.
 246 .sp
 247 .in +2
 248 .nf
 249 #include <sys/sunddi.h>
 250
 251 int
 252 docmp_default(const char *u1, const char *u2) {
 253     int result;
 254     int ;
 255
 256     result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errno);
 257     if (errno == EILSEQ)
 258         return (-1);
 259     if (errno == EINVAL)
 260         return (-2);
 261     if (errno == EBADF)
 262         return (-3);
 263     if (errno == ERANGE)
 264         return (-4);
 265 .fi
 266 .in -2
 267
 268 .LP
 269 \fBExample 2 \fRPerform upper case based case-insensitive comparison with
 270 Unicode 3.2.0 date.
 271 .sp
 272 .in +2
 273 .nf
 274 #include <sys/sunddi.h>
 275
 276 int
 277 docmp_caseinsensitive_u320(const char *u1, const char *u2) {
 278     int result;
 279     int errno;
 280
 281     result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER,
 282         U8_UNICODE_320, &errno);
 283     if (errno == EILSEQ)
 284         return (-1);
 285     if (errno == EINVAL)
 286         return (-2);
 287     if (errno == EBADF)
 288         return (-3);
 289     if (errno == ERANGE)
 290         return (-4);
 291
 292     return (result);
 293 }
 294 .fi
 295 .in -2
 296
 297 .LP
 298 \fBExample 3 \fRPerform Unicode Normalization Form D.
 299 .sp
 300 .LP
 301 Perform Unicode Normalization Form D and uppercase-based case-insensitive
 302 comparison with Unicode 3.2.0 date.
 303
 304 .sp
 305 .in +2
 306 .nf
 307 #include <sys/sunddi.h>
 308
 309 int
 310 docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) {
 311     int result;
 312     int errno;
 313
 314     result = u8_strcmp(u1, u2, 0,
 315         (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320,
 316         &errno);
 317     if (errno == EILSEQ)
 318         return (-1);
 319     if (errno == EINVAL)
 320         return (-2);
 321     if (errno == EBADF)
 322         return (-3);
 323     if (errno == ERANGE)
 324         return (-4);
 325
 326     return (result);
 327 }
 328 .fi
 329 .in -2
 330
 331 .SH ATTRIBUTES
 332 .sp
 333 .LP
 334 See \fBattributes\fR(5) for descriptions of the following attributes:
 335 .sp
 336
 337 .sp
 338 .TS
 339 box;
 340 c | c
 341 l | l .
 342 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 343 _
 344 Interface Stability     Committed
 345 .TE
 346
 347 .SH SEE ALSO
 348 .sp
 349 .LP
 350 \fBu8_validate\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C),
 351 \fBattributes\fR(5), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F),
 352 \fBuconv_u16tou32\fR(9F)
 353 .sp
 354 .LP
 355 The Unicode Standard (http://www.unicode.org)