usr/src/man/man9f/u8_validate.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_VALIDATE 9F "Sep 18, 2007"
   7 .SH NAME
   8 u8_validate \- validate UTF-8 characters and calculate the byte length
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/errno.h>
  14 #include <sys/sunddi.h>
  15
  16 \fBint\fR u8_validate(\fBchar *\fR\fIu8str\fR, \fBsize_t\fR \fIn\fR, \fBchar **\fR\fIlist\fR, \fBint\fR \fIflag\fR,
  17      \fBint *\fR\fIerrno\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Solaris DDI specific (Solaris DDI)
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIu8str\fR\fR
  29 .ad
  30 .RS 9n
  31 The UTF-8 string to be validated.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIn\fR\fR
  38 .ad
  39 .RS 9n
  40 The maximum number of bytes in \fIu8str\fR that can be examined and validated.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIlist\fR\fR
  47 .ad
  48 .RS 9n
  49 A list of null-terminated character strings in UTF-8 that must be additionally
  50 checked against as invalid characters. The last string in \fIlist\fR must be
  51 null to indicate there is no further string.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIflag\fR\fR
  58 .ad
  59 .RS 9n
  60 Possible validation options constructed by a bitwise-inclusive-OR of the
  61 following values:
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBU8_VALIDATE_ENTIRE\fR\fR
  66 .ad
  67 .sp .6
  68 .RS 4n
  69 By default, \fBu8_validate()\fR looks at the first character or up to \fIn\fR
  70 bytes, whichever is smaller in terms of the number of bytes to be consumed, and
  71 returns with the result.
  72 .sp
  73 When this option is used, \fBu8_validate()\fR will check up to \fIn\fR bytes
  74 from \fIu8str\fR and possibly more than a character before returning the
  75 result.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBU8_VALIDATE_CHECK_ADDITIONAL\fR\fR
  82 .ad
  83 .sp .6
  84 .RS 4n
  85 By default, \fBu8_validate()\fR does not use list supplied.
  86 .sp
  87 When this option is supplied with a list of character strings,
  88 \fBu8_validate()\fR additionally validates \fIu8str\fR against the character
  89 strings supplied with \fIlist\fR and returns EBADF in \fIerrno\fR if
  90 \fIu8str\fR has any one of the character strings in \fIlist\fR.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBU8_VALIDATE_UCS2_RANGE\fR\fR
  97 .ad
  98 .sp .6
  99 .RS 4n
 100 By default, \fBu8_validate()\fR uses the entire Unicode coding space of U+0000
 101 to U+10FFFF.
 102 .sp
 103 When this option is specified, the valid Unicode coding space is smaller to
 104 U+0000 to U+FFFF.
 105 .RE
 106
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fIerrno\fR\fR
 113 .ad
 114 .RS 9n
 115 An error occurred during validation.  The following values are supported:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBEBADF\fR\fR
 120 .ad
 121 .RS 10n
 122 Validation failed because list-specified characters were found in the string
 123 pointed to by \fIu8str\fR.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBEILSEQ\fR\fR
 130 .ad
 131 .RS 10n
 132 Validation failed because an illegal byte was found in the string pointed to by
 133 \fIu8str\fR.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEINVAL\fR\fR
 140 .ad
 141 .RS 10n
 142 Validation failed because an incomplete byte was found in the string pointed to
 143 by  \fIu8str\fR.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBERANGE\fR\fR
 150 .ad
 151 .RS 10n
 152 Validation failed because character bytes were encountered that are outside the
 153 range of the Unicode coding space.
 154 .RE
 155
 156 .RE
 157
 158 .SH DESCRIPTION
 159 .sp
 160 .LP
 161 The \fBu8_validate()\fR function validates \fIu8str\fR in UTF-8 and determines
 162 the number of bytes constituting the character(s) pointed to by \fIu8str\fR.
 163 .SH RETURN VALUES
 164 .sp
 165 .LP
 166 If \fIu8str\fR is a null pointer, \fBu8_validate()\fR returns 0. Otherwise,
 167 \fBu8_validate()\fR returns either the number of bytes that constitute the
 168 characters if the next \fIn\fR or fewer bytes form valid characters, or -1 if
 169 there is an validation failure, in which case it may set \fIerrno\fR to
 170 indicate the error.
 171 .SH EXAMPLES
 172 .LP
 173 \fBExample 1 \fRDetermine the length of the first UTF-8 character.
 174 .sp
 175 .in +2
 176 .nf
 177 #include <sys/types.h>
 178 #include <sys/errno.h>
 179 #include <sys/sunddi.h>
 180
 181 char u8[MAXPATHLEN];
 182 int errno;
 183 \&.
 184 \&.
 185 \&.
 186 len = u8_validate(u8, 4, (char **)NULL, 0, &errno);
 187 if (len == -1) {
 188     switch (errno) {
 189         case EILSEQ:
 190         case EINVAL:
 191             return (MYFS4_ERR_INVAL);
 192         case EBADF:
 193             return (MYFS4_ERR_BADNAME);
 194         case ERANGE:
 195             return (MYFS4_ERR_BADCHAR);
 196         default:
 197             return (-10);
 198     }
 199 }
 200 .fi
 201 .in -2
 202
 203 .LP
 204 \fBExample 2 \fRCheck if there are any invalid characters in the entire string.
 205 .sp
 206 .in +2
 207 .nf
 208 #include <sys/types.h>
 209 #include <sys/errno.h>
 210 #include <sys/sunddi.h>
 211
 212 char u8[MAXPATHLEN];
 213 int n;
 214 int errno;
 215 \&.
 216 \&.
 217 \&.
 218 n = strlen(u8);
 219 len = u8_validate(u8, n, (char **)NULL, U8_VALIDATE_ENTIRE, &errno);
 220 if (len == -1) {
 221     switch (errno) {
 222         case EILSEQ:
 223         case EINVAL:
 224             return (MYFS4_ERR_INVAL);
 225         case EBADF:
 226             return (MYFS4_ERR_BADNAME);
 227         case ERANGE:
 228             return (MYFS4_ERR_BADCHAR);
 229         default:
 230             return (-10);
 231     }
 232 }
 233 .fi
 234 .in -2
 235
 236 .LP
 237 \fBExample 3 \fRCheck if there is any invalid character, including prohibited
 238 characters, in the entire string.
 239 .sp
 240 .in +2
 241 .nf
 242 #include <sys/types.h>
 243 #include <sys/errno.h>
 244 #include <sys/sunddi.h>
 245
 246 char u8[MAXPATHLEN];
 247 int n;
 248 int errno;
 249 char *prohibited[4] = {
 250     ".", "..", "\e\e", NULL
 251 };
 252 \&.
 253 \&.
 254 \&.
 255 n = strlen(u8);
 256 len = u8_validate(u8, n, prohibited,
 257     (U8_VALIDATE_ENTIRE|U8_VALIDATE_CHECK_ADDITIONAL), &errno);
 258 if (len == -1) {
 259     switch (errno) {
 260         case EILSEQ:
 261         case EINVAL:
 262             return (MYFS4_ERR_INVAL);
 263         case EBADF:
 264             return (MYFS4_ERR_BADNAME);
 265         case ERANGE:
 266             return (MYFS4_ERR_BADCHAR);
 267         default:
 268             return (-10);
 269     }
 270 }
 271 .fi
 272 .in -2
 273
 274 .SH ATTRIBUTES
 275 .sp
 276 .LP
 277 See \fBattributes\fR(5) for descriptions of the following attributes:
 278 .sp
 279
 280 .sp
 281 .TS
 282 box;
 283 c | c
 284 l | l .
 285 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 286 _
 287 Interface Stability     Committed
 288 .TE
 289
 290 .SH SEE ALSO
 291 .sp
 292 .LP
 293 \fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C),
 294 \fBattributes\fR(5), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F),
 295 \fBuconv_u16tou32\fR(9F)
 296 .sp
 297 .LP
 298 The Unicode Standard (http://www.unicode.org)