--- /dev/null
+/*
+ * Copyright (c) 2016-2020 Apple Inc. All rights reserved.
+ *
+ * @APPLE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_LICENSE_HEADER_END@
+ */
+
+#ifndef unicode_h
+#define unicode_h
+
+#ifdef KERNEL_PRIVATE
+
+#include <sys/cdefs.h>
+#include <stdbool.h>
+
+/*
+ * WARNING - callers that use the following Unicode normalization interface for on-disk
+ * structures should be aware that the implementation will be periodically updated for
+ * the latest Unicode standard version.
+ */
+
+enum {
+ /* Maximum size of UTF32 reordering buffer for stream-safe format */
+ kNCFStreamSafeBufMax = 32
+};
+
+/*
+ * utf8_normalizeOptCaseFoldAndHash
+ *
+ * Convert a given UTF-8 string to UTF-32 in one of the following normalized forms,
+ * as specified by the case_sens parameter, and feed the result incrementally to
+ * the provided hash function callback:
+ * - "canonical caseless form" (case-folded NFD, as described by definition D145
+ * in chapter 3 of The Unicode Standard); for case-insensitive behavior.
+ * - standard NFD; for case-sensitive behavior (if case_sens = true).
+ *
+ * The input string should be valid UTF-8 that meets the criteria for stream safe
+ * text as described in http://unicode.org/reports/tr15/#Stream_Safe_Text_Format.
+ * It should not contain ASCII 0x00 or '/'.
+ *
+ * str: The input UTF-8 string (need not be 0 terminated)
+ * str_len: The byte length of the input string (excluding any 0 terminator)
+ * case_sens: False for case-insensitive behavior; generates canonical caseless form.
+ * True for case-sensitive behavior; generates standard NFD.
+ * hash_func: A pointer to a hashing function to compute the hash of the
+ * normalized/case-folded result. buf contains buf_len bytes
+ * of data to be added to the hash using the caller-supplied
+ * context (ctx).
+ * hash_ctx: The context for the hash function.
+ *
+ * Returns: 0 on success, or
+ * EILSEQ: The input string contains illegal ASCII-range characters
+ * (0x00 or '/'), or is not well-formed stream-safe UTF-8, or
+ * contains codepoints that are non-characters or unassigned in
+ * the version of Unicode currently supported.
+ */
+int utf8_normalizeOptCaseFoldAndHash(const char *str,
+ size_t str_len,
+ bool case_sens,
+ void (*hash_func)(void *buf, size_t buf_len, void *ctx),
+ void *hash_ctx);
+
+/*
+ * utf8_normalizeOptCaseFoldAndCompare
+ *
+ * Determine whether two UTF-8 strings are equal after converting each to one of the
+ * following normalized forms, as specified by the case_sens parameter:
+ * - "canonical caseless form" (case-folded NFD); for case-insensitive comparison.
+ * - standard NFD; for case-sensitive comparison (if case_sens = true).
+ * On success, sets are_equal to true if the strings are equal, or false if they are not.
+ *
+ * The input strings should be valid UTF-8 that meet the criteria for stream safe
+ * text as described in http://unicode.org/reports/tr15/#Stream_Safe_Text_Format.
+ * They should not contain ASCII 0x00 or '/'.
+ *
+ * strA: A UTF-8 string to be compared (need not be 0 terminated)
+ * strA_len: The byte length of strA (excluding any 0 terminator)
+ * strB: The second UTF-8 string to be compared (need not be 0 terminated)
+ * strB_len: The byte length of strB (excluding any 0 terminator)
+ * case_sens: False for case-insensitive behavior; compares canonical caseless forms.
+ * True for case-sensitive behavior; compares standard NFD forms.
+ * are_equal: On success, set to true if the strings are equal, or set to false
+ * if they are not.
+ *
+ * Returns: 0 on success, or
+ * EILSEQ: One or both of the input strings contains illegal ASCII-range
+ * characters (0x00 or '/'), or is not well-formed stream-safe UTF-8,
+ * or contains codepoints that are non-characters or unassigned in
+ * the version of Unicode currently supported.
+ * Note: The comparison may terminate early when a difference is
+ * detected, and may return 0 and set *are_equal=false even
+ * if one or both strings are invalid.
+ */
+int utf8_normalizeOptCaseFoldAndCompare(const char *strA,
+ size_t strA_len,
+ const char *strB,
+ size_t strB_len,
+ bool case_sens,
+ bool *are_equal);
+
+/*
+ * utf8_normalizeOptCaseFold
+ *
+ * Convert a given UTF-8 string to UTF-32 in one of the following normalized forms,
+ * as specified by the case_sens parameter, and copy the result to the ustr
+ * buffer:
+ * - "canonical caseless form" (case-folded NFD, as described by definition D145
+ * in chapter 3 of The Unicode Standard); for case-insensitive behavior.
+ * - standard NFD; for case-sensitive behavior (if case_sens = true).
+ *
+ * The input string should be valid UTF-8 that meets the criteria for stream safe
+ * text as described in http://unicode.org/reports/tr15/#Stream_Safe_Text_Format.
+ * It should not contain ASCII 0x00 or '/'.
+ *
+ * str: The input UTF-8 string (need not be 0 terminated)
+ * str_len: The byte length of the input string (excluding any 0 terminator)
+ * case_sens: False for case-insensitive behavior; generates canonical caseless form.
+ * True for case-sensitive behavior; generates standard NFD.
+ * ustr: A pointer to a buffer for the resulting UTF-32 string.
+ * ustr_size: The capacity of ustr, in UTF-32 units.
+ * ustr_len: Pointer to a value that will be filled in with the actual length
+ * in UTF-32 units of the string copied to ustr.
+ *
+ * Returns: 0 on success, or
+ * EILSEQ: The input string contains illegal ASCII-range characters
+ * (0x00 or '/'), or is not well-formed stream-safe UTF-8, or
+ * contains codepoints that are non-characters or unassigned in
+ * the version of Unicode currently supported.
+ * ENOMEM: ustr_size is insufficient for the resulting string. In this
+ * case the value returned in *ustr_len is invalid.
+ */
+int utf8_normalizeOptCaseFold(const char *str,
+ size_t str_len,
+ bool case_sens,
+ int32_t *ustr,
+ int32_t ustr_size,
+ int32_t *ustr_len);
+
+/*
+ * utf8_normalizeOptCaseFoldToUTF8
+ *
+ * Convert a given UTF-8 string to UTF-8 in one of the following normalized forms,
+ * as specified by the case_sens parameter, and copy the result to the ustr
+ * buffer:
+ * - "canonical caseless form" (case-folded NFD, as described by definition D145
+ * in chapter 3 of The Unicode Standard); for case-insensitive behavior.
+ * - standard NFD; for case-sensitive behavior (if case_sens = true).
+ *
+ * The input string should be valid UTF-8 that meets the criteria for stream safe
+ * text as described in http://unicode.org/reports/tr15/#Stream_Safe_Text_Format.
+ * It should not contain ASCII 0x00 or '/'.
+ *
+ * str: The input UTF-8 string (need not be 0 terminated)
+ * str_len: The byte length of the input string (excluding any 0 terminator)
+ * case_sens: False for case-insensitive behavior; generates canonical caseless form.
+ * True for case-sensitive behavior; generates standard NFD.
+ * ustr: A pointer to a buffer for the resulting UTF-8 string.
+ * ustr_size: The capacity of ustr, in bytes.
+ * ustr_len: Pointer to a value that will be filled in with the actual length
+ * in bytes of the string copied to ustr.
+ *
+ * Returns: 0 on success, or
+ * EILSEQ: The input string contains illegal ASCII-range characters
+ * (0x00 or '/'), or is not well-formed stream-safe UTF-8, or
+ * contains codepoints that are non-characters or unassigned in
+ * the version of Unicode currently supported.
+ * ENOMEM: ustr_size is insufficient for the resulting string. In this
+ * case the value returned in *ustr_len is invalid.
+ */
+int utf8_normalizeOptCaseFoldToUTF8(const char *str,
+ size_t str_len,
+ bool case_sens,
+ char *ustr,
+ size_t ustr_size,
+ size_t *ustr_len);
+
+/*
+ * utf8_normalizeOptCaseFoldAndMatchSubstring
+ *
+ * Determine whether the normalized UTF32 string derived from a specified UTF-8 string
+ * strA contains another UTF32 string ustrB which has already been normalized, typically
+ * with normalizeOptCaseFold. The normalization for both strings is one of the following,
+ * as specified by the case_sens parameter:
+ * - "canonical caseless form" (case-folded NFD); for case-insensitive comparison.
+ * - standard NFD; for case-sensitive comparison (if case_sens = true).
+ * On success, sets are_equal to true if strA contains ustrB, or false otherwise.
+ *
+ * The input string strA should be valid UTF-8 that meets the criteria for stream safe
+ * text as described in http://unicode.org/reports/tr15/#Stream_Safe_Text_Format.
+ * It should not contain ASCII 0x00 or '/'.
+ *
+ * strA: A UTF-8 string (need not be 0 terminated) in which to search for the
+ * substring specified by ustrB.
+ * strA_len: The byte length of strA (excluding any 0 terminator)
+ * ustrB: A normalized UTF-32 substring (need not be 0 terminated) to be searched
+ * for in the UTF-32 string resulting from converting strA to the normalized
+ * UTF-32 form specified by the case_sens parameter; ustrB must already be
+ * in that form. Normally this will be produced using normalizeOptCaseFold.
+ * ustrB_len: The length of ustrB in UTF-32 units (excluding any 0 terminator).
+ * case_sens: False for case-insensitive matching; compares canonical caseless forms.
+ * True for case-sensitive matching; compares standard NFD forms.
+ * buf: Pointer to caller-supplied working memory for storing the portion of
+ * strA which has been converted to normalized UTF-32.
+ * buf_size: The size of buf.
+ * has_match: On success, set to true if strA (when converter to UTF-32 and normalized
+ * per case_sens) contains ustrB, set to false otherwise.
+ *
+ * Returns: 0 on success, or
+ * EILSEQ: strA contains illegal ASCII-range characters (0x00 or '/'), or is
+ * not well-formed stream-safe UTF-8, or contains codepoints that are
+ * non-characters or unassigned in the version of Unicode currently
+ * supported.
+ * Note: The search may terminate early when a match is detected, and
+ * may return 0 and set *has_match=true even if strA is invalid.
+ * ENOMEM: buf_size is insufficient.
+ */
+int utf8_normalizeOptCaseFoldAndMatchSubstring(const char *strA,
+ size_t strA_len,
+ const int32_t *ustrB,
+ int32_t ustrB_len,
+ bool case_sens,
+ void *buf,
+ size_t buf_size,
+ bool *has_match);
+
+/*
+ * utf8_normalizeOptCaseFoldGetUVersion
+ *
+ * Get the Unicode and code version currently associated with the normalizeOptCaseFold
+ * functions. The caller allocates the version array and passes it to the function,
+ * which will fill out the array as follows:
+ * version[0] = Unicode major version; for Unicode 6.3.0 this would be 6
+ * version[1] = Unicode minor version; for Unicode 6.3.0 this would be 3
+ * version[2] = Unicode patch version; for Unicode 6.3.0 this would be 0
+ * version[3] = Code revision level; for any given Unicode version, this value starts
+ * at 0 and is incremented for each significant revision to the
+ * normalizeOptCaseFold functions.
+ */
+void utf8_normalizeOptCaseFoldGetUVersion(unsigned char version[4]);
+
+#endif /* KERNEL_PRIVATE */
+
+#endif /* unicode_h */
projects / apple / xnu.git / blobdiff