grpc 1.74.1 → 1.75.0.pre1

data/third_party/cares/cares/src/lib/include/ares_htable_vpvp.h

@@ -0,0 +1,128 @@
+/* MIT License
+ *
+ * Copyright (c) 2024 Brad House
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef __ARES__HTABLE_VPVP_H
+#define __ARES__HTABLE_VPVP_H
+
+/*! \addtogroup ares_htable_vpvp HashTable with void pointer Key and void
+ * pointer Value
+ *
+ * This data structure wraps the base ares_htable data structure in order to
+ * split the key and value data types as size_t and void pointer, respectively.
+ *
+ * Average time complexity:
+ *  - Insert: O(1)
+ *  - Search: O(1)
+ *  - Delete: O(1)
+ *
+ * @{
+ */
+
+struct ares_htable_vpvp;
+
+/*! Opaque data type for size_t key, void pointer hash table implementation */
+typedef struct ares_htable_vpvp ares_htable_vpvp_t;
+
+/*! Callback to free key stored in hashtable
+ *
+ *  \param[in] key  user-supplied key
+ */
+typedef void (*ares_htable_vpvp_key_free_t)(void *key);
+
+/*! Callback to free value stored in hashtable
+ *
+ *  \param[in] val  user-supplied value
+ */
+typedef void (*ares_htable_vpvp_val_free_t)(void *val);
+
+/*! Destroy hashtable
+ *
+ *  \param[in] htable  Initialized hashtable
+ */
+CARES_EXTERN void ares_htable_vpvp_destroy(ares_htable_vpvp_t *htable);
+
+/*! Create size_t key, void pointer value hash table
+ *
+ *  \param[in] key_free  Optional. Call back to free user-supplied key.  If
+ *                       NULL it is expected the caller will clean up any user
+ *                       supplied keys.
+ *  \param[in] val_free  Optional. Call back to free user-supplied value.  If
+ *                       NULL it is expected the caller will clean up any user
+ *                       supplied values.
+ */
+CARES_EXTERN ares_htable_vpvp_t *
+  ares_htable_vpvp_create(ares_htable_vpvp_key_free_t key_free,
+                          ares_htable_vpvp_val_free_t val_free);
+
+/*! Insert key/value into hash table
+ *
+ *  \param[in] htable Initialized hash table
+ *  \param[in] key    key to associate with value
+ *  \param[in] val    value to store (takes ownership). May be NULL.
+ *  \return ARES_TRUE on success, ARES_FALSE on failure or out of memory
+ */
+CARES_EXTERN ares_bool_t ares_htable_vpvp_insert(ares_htable_vpvp_t *htable,
+                                                 void *key, void *val);
+
+/*! Retrieve value from hashtable based on key
+ *
+ *  \param[in]  htable  Initialized hash table
+ *  \param[in]  key     key to use to search
+ *  \param[out] val     Optional.  Pointer to store value.
+ *  \return ARES_TRUE on success, ARES_FALSE on failure
+ */
+CARES_EXTERN ares_bool_t ares_htable_vpvp_get(const ares_htable_vpvp_t *htable,
+                                              const void *key, void **val);
+
+/*! Retrieve value from hashtable directly as return value.  Caveat to this
+ *  function over ares_htable_vpvp_get() is that if a NULL value is stored
+ *  you cannot determine if the key is not found or the value is NULL.
+ *
+ *  \param[in] htable  Initialized hash table
+ *  \param[in] key     key to use to search
+ *  \return value associated with key in hashtable or NULL
+ */
+CARES_EXTERN void *ares_htable_vpvp_get_direct(const ares_htable_vpvp_t *htable,
+                                               const void               *key);
+
+/*! Remove a value from the hashtable by key
+ *
+ *  \param[in] htable  Initialized hash table
+ *  \param[in] key     key to use to search
+ *  \return ARES_TRUE if found, ARES_FALSE if not
+ */
+CARES_EXTERN ares_bool_t ares_htable_vpvp_remove(ares_htable_vpvp_t *htable,
+                                                 const void         *key);
+
+/*! Retrieve the number of keys stored in the hash table
+ *
+ *  \param[in] htable  Initialized hash table
+ *  \return count
+ */
+CARES_EXTERN size_t ares_htable_vpvp_num_keys(const ares_htable_vpvp_t *htable);
+
+/*! @} */
+
+#endif /* __ARES__HTABLE_VPVP_H */

data/third_party/cares/cares/src/lib/include/ares_llist.h

@@ -0,0 +1,239 @@
+/* MIT License
+ *
+ * Copyright (c) 2023 Brad House
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef __ARES__LLIST_H
+#define __ARES__LLIST_H
+
+/*! \addtogroup ares_llist LinkedList Data Structure
+ *
+ * This is a doubly-linked list data structure.
+ *
+ * Average time complexity:
+ *  - Insert: O(1)   -- head or tail
+ *  - Search: O(n)
+ *  - Delete: O(1)   -- delete assumes you hold a node pointer
+ *
+ * @{
+ */
+
+struct ares_llist;
+
+/*! Opaque data structure for linked list */
+typedef struct ares_llist ares_llist_t;
+
+struct ares_llist_node;
+
+/*! Opaque data structure for a node in a linked list */
+typedef struct ares_llist_node ares_llist_node_t;
+
+/*! Callback to free user-defined node data
+ *
+ *  \param[in] data  user supplied data
+ */
+typedef void (*ares_llist_destructor_t)(void *data);
+
+/*! Create a linked list object
+ *
+ *  \param[in] destruct  Optional. Destructor to call on all removed nodes
+ *  \return linked list object or NULL on out of memory
+ */
+CARES_EXTERN ares_llist_t *ares_llist_create(ares_llist_destructor_t destruct);
+
+/*! Replace destructor for linked list nodes.  Typically this is used
+ *  when wanting to disable the destructor by using NULL.
+ *
+ *  \param[in] list      Initialized linked list object
+ *  \param[in] destruct  replacement destructor, NULL is allowed
+ */
+CARES_EXTERN void
+  ares_llist_replace_destructor(ares_llist_t           *list,
+                                ares_llist_destructor_t destruct);
+
+/*! Insert value as the first node in the linked list
+ *
+ *  \param[in] list   Initialized linked list object
+ *  \param[in] val    user-supplied value.
+ *  \return node object referencing place in list, or null if out of memory or
+ *   misuse
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_insert_first(ares_llist_t *list,
+                                                        void         *val);
+
+/*! Insert value as the last node in the linked list
+ *
+ *  \param[in] list   Initialized linked list object
+ *  \param[in] val    user-supplied value.
+ *  \return node object referencing place in list, or null if out of memory or
+ *   misuse
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_insert_last(ares_llist_t *list,
+                                                       void         *val);
+
+/*! Insert value before specified node in the linked list
+ *
+ *  \param[in] node  node referenced to insert before
+ *  \param[in] val   user-supplied value.
+ *  \return node object referencing place in list, or null if out of memory or
+ *   misuse
+ */
+CARES_EXTERN ares_llist_node_t *
+  ares_llist_insert_before(ares_llist_node_t *node, void *val);
+
+/*! Insert value after specified node in the linked list
+ *
+ *  \param[in] node  node referenced to insert after
+ *  \param[in] val   user-supplied value.
+ *  \return node object referencing place in list, or null if out of memory or
+ *   misuse
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_insert_after(ares_llist_node_t *node,
+                                                        void              *val);
+
+/*! Obtain first node in list
+ *
+ *  \param[in] list  Initialized list object
+ *  \return first node in list or NULL if none
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_node_first(ares_llist_t *list);
+
+/*! Obtain last node in list
+ *
+ *  \param[in] list  Initialized list object
+ *  \return last node in list or NULL if none
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_node_last(ares_llist_t *list);
+
+/*! Obtain a node based on its index.  This is an O(n) operation.
+ *
+ *  \param[in] list Initialized list object
+ *  \param[in] idx  Index of node to retrieve
+ *  \return node at index or NULL if invalid index
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_node_idx(ares_llist_t *list,
+                                                    size_t        idx);
+
+/*! Obtain next node in respect to specified node
+ *
+ *  \param[in] node  Node referenced
+ *  \return node or NULL if none
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_node_next(ares_llist_node_t *node);
+
+/*! Obtain previous node in respect to specified node
+ *
+ *  \param[in] node  Node referenced
+ *  \return node or NULL if none
+ */
+CARES_EXTERN ares_llist_node_t *ares_llist_node_prev(ares_llist_node_t *node);
+
+
+/*! Obtain value from node
+ *
+ *  \param[in] node  Node referenced
+ *  \return user provided value from node
+ */
+CARES_EXTERN void              *ares_llist_node_val(ares_llist_node_t *node);
+
+/*! Obtain the number of entries in the list
+ *
+ *  \param[in] list  Initialized list object
+ *  \return count
+ */
+CARES_EXTERN size_t             ares_llist_len(const ares_llist_t *list);
+
+/*! Clear all entries in the list, but don't destroy the list object.
+ *
+ *  \param[in] list  Initialized list object
+ */
+CARES_EXTERN void               ares_llist_clear(ares_llist_t *list);
+
+/*! Obtain list object from referenced node
+ *
+ *  \param[in] node  Node referenced
+ *  \return list object node belongs to
+ */
+CARES_EXTERN ares_llist_t      *ares_llist_node_parent(ares_llist_node_t *node);
+
+/*! Obtain the first user-supplied value in the list
+ *
+ *  \param[in] list Initialized list object
+ *  \return first user supplied value or NULL if none
+ */
+CARES_EXTERN void              *ares_llist_first_val(ares_llist_t *list);
+
+/*! Obtain the last user-supplied value in the list
+ *
+ *  \param[in] list Initialized list object
+ *  \return last user supplied value or NULL if none
+ */
+CARES_EXTERN void              *ares_llist_last_val(ares_llist_t *list);
+
+/*! Take ownership of user-supplied value in list without calling destructor.
+ *  Will unchain entry from list.
+ *
+ *  \param[in] node Node referenced
+ *  \return user supplied value
+ */
+CARES_EXTERN void              *ares_llist_node_claim(ares_llist_node_t *node);
+
+/*! Replace user-supplied value for node
+ *
+ *  \param[in] node Node referenced
+ *  \param[in] val  new user-supplied value
+ */
+CARES_EXTERN void ares_llist_node_replace(ares_llist_node_t *node, void *val);
+
+/*! Destroy the node, removing it from the list and calling destructor.
+ *
+ *  \param[in] node  Node referenced
+ */
+CARES_EXTERN void ares_llist_node_destroy(ares_llist_node_t *node);
+
+/*! Destroy the list object and all nodes in the list.
+ *
+ *  \param[in] list Initialized list object
+ */
+CARES_EXTERN void ares_llist_destroy(ares_llist_t *list);
+
+/*! Detach node from the current list and re-attach it to the new list as the
+ *  last entry.
+ *
+ * \param[in] node       node to move
+ * \param[in] new_parent new list
+ */
+CARES_EXTERN void ares_llist_node_mvparent_last(ares_llist_node_t *node,
+                                                ares_llist_t      *new_parent);
+
+/*! Detach node from the current list and re-attach it to the new list as the
+ *  first entry.
+ *
+ * \param[in] node       node to move
+ * \param[in] new_parent new list
+ */
+CARES_EXTERN void ares_llist_node_mvparent_first(ares_llist_node_t *node,
+                                                 ares_llist_t      *new_parent);
+/*! @} */
+
+#endif /* __ARES__LLIST_H */

data/third_party/cares/cares/src/lib/include/ares_mem.h

@@ -0,0 +1,38 @@
+/* MIT License
+ *
+ * Copyright (c) The c-ares project and its contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#ifndef __ARES_MEM_H
+#define __ARES_MEM_H
+
+/* Memory management functions */
+CARES_EXTERN void *ares_malloc(size_t size);
+CARES_EXTERN void *ares_realloc(void *ptr, size_t size);
+CARES_EXTERN void  ares_free(void *ptr);
+CARES_EXTERN void *ares_malloc_zero(size_t size);
+CARES_EXTERN void *ares_realloc_zero(void *ptr, size_t orig_size,
+                                     size_t new_size);
+
+#endif

data/third_party/cares/cares/src/lib/include/ares_str.h

@@ -0,0 +1,244 @@
+/* MIT License
+ *
+ * Copyright (c) 1998 Massachusetts Institute of Technology
+ * Copyright (c) The c-ares project and its contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef __ARES_STR_H
+#define __ARES_STR_H
+
+CARES_EXTERN char  *ares_strdup(const char *s1);
+
+/*! Scan up to maxlen bytes for the first NULL character and return
+ *  its index, or maxlen if not found.  The function only returns
+ *  maxlen if the first maxlen bytes were not NULL characters; it
+ *  makes no guarantee for what \c str[maxlen] (if defined) is, and
+ *  does not access it.  It is behaving like the POSIX \c strnlen()
+ *  function, except that it returns 0 if the \p str pointer is \c
+ *  NULL.
+ *
+ *  \param[in] str    The string to scan for the NULL character
+ *  \param[in] maxlen The maximum number of bytes to scan
+ *  \return Index of first NULL byte. Between 0 and maxlen (inclusive).
+ */
+CARES_EXTERN size_t ares_strnlen(const char *str, size_t maxlen);
+
+CARES_EXTERN size_t ares_strlen(const char *str);
+
+/*! Copy string from source to destination with destination buffer size
+ *  provided.  The destination is guaranteed to be null terminated, if the
+ *  provided buffer isn't large enough, only those bytes from the source that
+ *  will fit will be copied.
+ *
+ *  \param[out] dest       Destination buffer
+ *  \param[in]  src        Source to copy
+ *  \param[in]  dest_size  Size of destination buffer
+ *  \return String length.  Will be at most dest_size-1
+ */
+CARES_EXTERN size_t ares_strcpy(char *dest, const char *src, size_t dest_size);
+
+CARES_EXTERN ares_bool_t    ares_str_isnum(const char *str);
+CARES_EXTERN ares_bool_t    ares_str_isalnum(const char *str);
+
+CARES_EXTERN void           ares_str_ltrim(char *str);
+CARES_EXTERN void           ares_str_rtrim(char *str);
+CARES_EXTERN void           ares_str_trim(char *str);
+CARES_EXTERN void           ares_str_lower(char *str);
+
+CARES_EXTERN unsigned char  ares_tolower(unsigned char c);
+CARES_EXTERN unsigned char *ares_memmem(const unsigned char *big,
+                                        size_t               big_len,
+                                        const unsigned char *little,
+                                        size_t               little_len);
+CARES_EXTERN ares_bool_t    ares_memeq(const unsigned char *ptr,
+                                       const unsigned char *val, size_t len);
+CARES_EXTERN ares_bool_t    ares_memeq_ci(const unsigned char *ptr,
+                                          const unsigned char *val, size_t len);
+CARES_EXTERN ares_bool_t    ares_is_hostname(const char *str);
+
+/*! Validate the string provided is printable.  The length specified must be
+ *  at least the size of the buffer provided.  If a NULL-terminator is hit
+ *  before the length provided is hit, this will not be considered a valid
+ *  printable string.  This does not validate that the string is actually
+ *  NULL terminated.
+ *
+ *  \param[in] str  Buffer containing string to evaluate.
+ *  \param[in] len  Number of characters to evaluate within provided buffer.
+ *                  If 0, will return TRUE since it did not hit an exception.
+ *  \return ARES_TRUE if the entire string is printable, ARES_FALSE if not.
+ */
+CARES_EXTERN ares_bool_t    ares_str_isprint(const char *str, size_t len);
+
+/* We only care about ASCII rules */
+#define ares_isascii(x) (((unsigned char)x) <= 127)
+
+#define ares_isdigit(x) (((unsigned char)x) >= '0' && ((unsigned char)x) <= '9')
+
+#define ares_isxdigit(x)                                       \
+  (ares_isdigit(x) ||                                          \
+   (((unsigned char)x) >= 'a' && ((unsigned char)x) <= 'f') || \
+   (((unsigned char)x) >= 'A' && ((unsigned char)x) <= 'F'))
+
+#define ares_isupper(x) (((unsigned char)x) >= 'A' && ((unsigned char)x) <= 'Z')
+
+#define ares_islower(x) (((unsigned char)x) >= 'a' && ((unsigned char)x) <= 'z')
+
+#define ares_isalpha(x) (ares_islower(x) || ares_isupper(x))
+
+#define ares_isspace(x)                                            \
+  (((unsigned char)(x)) == '\r' || ((unsigned char)(x)) == '\t' || \
+   ((unsigned char)(x)) == ' ' || ((unsigned char)(x)) == '\v' ||  \
+   ((unsigned char)(x)) == '\f' || ((unsigned char)(x)) == '\n')
+
+#define ares_isprint(x) \
+  (((unsigned char)(x)) >= 0x20 && ((unsigned char)(x)) <= 0x7E)
+
+/* Character set allowed by hostnames.  This is to include the normal
+ * domain name character set plus:
+ *  - underscores which are used in SRV records.
+ *  - Forward slashes such as are used for classless in-addr.arpa
+ *    delegation (CNAMEs)
+ *  - Asterisks may be used for wildcard domains in CNAMEs as seen in the
+ *    real world.
+ * While RFC 2181 section 11 does state not to do validation,
+ * that applies to servers, not clients.  Vulnerabilities have been
+ * reported when this validation is not performed.  Security is more
+ * important than edge-case compatibility (which is probably invalid
+ * anyhow).
+ * [A-Za-z0-9-*._/]
+ */
+#define ares_is_hostnamech(x)                                           \
+  (ares_isalpha(x) || ares_isdigit(x) || ((unsigned char)(x)) == '-' || \
+   ((unsigned char)(x)) == '.' || ((unsigned char)(x)) == '_' ||        \
+   ((unsigned char)(x)) == '/' || ((unsigned char)(x)) == '*')
+
+
+/*! Compare two strings (for sorting)
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \return < 0 if First String less than Second String,
+ *            0 if First String equal to Second String,
+ *          > 0 if First String greater than Second String
+ */
+CARES_EXTERN int ares_strcmp(const char *a, const char *b);
+
+/*! Compare two strings up to specified length (for sorting)
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \param[in] n Length
+ *  \return < 0 if First String less than Second String,
+ *            0 if First String equal to Second String,
+ *          > 0 if First String greater than Second String
+ */
+CARES_EXTERN int ares_strncmp(const char *a, const char *b, size_t n);
+
+
+/*! Compare two strings in a case-insensitive manner (for sorting)
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \return < 0 if First String less than Second String,
+ *            0 if First String equal to Second String,
+ *          > 0 if First String greater than Second String
+ */
+CARES_EXTERN int ares_strcasecmp(const char *a, const char *b);
+
+/*! Compare two strings in a case-insensitive manner up to specified length
+ *  (for sorting)
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \param[in] n Length
+ *  \return < 0 if First String less than Second String,
+ *            0 if First String equal to Second String,
+ *          > 0 if First String greater than Second String
+ */
+CARES_EXTERN int ares_strncasecmp(const char *a, const char *b, size_t n);
+
+/*! Compare two strings for equality
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \return ARES_TRUE on match, or ARES_FALSE if no match
+ */
+CARES_EXTERN ares_bool_t ares_streq(const char *a, const char *b);
+
+/*! Compare two strings for equality up to specified length
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \param[in] n Length
+ *  \return ARES_TRUE on match, or ARES_FALSE if no match
+ */
+CARES_EXTERN ares_bool_t ares_streq_max(const char *a, const char *b, size_t n);
+
+/*! Compare two strings for equality in a case insensitive manner
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \return ARES_TRUE on match, or ARES_FALSE if no match
+ */
+CARES_EXTERN ares_bool_t ares_strcaseeq(const char *a, const char *b);
+
+/*! Compare two strings for equality up to specified length in a case
+ *  insensitive manner
+ *
+ *  Treats NULL and "" strings as equivalent
+ *
+ *  \param[in] a First String
+ *  \param[in] b Second String
+ *  \param[in] n Length
+ *  \return ARES_TRUE on match, or ARES_FALSE if no match
+ */
+CARES_EXTERN ares_bool_t ares_strcaseeq_max(const char *a, const char *b,
+                                            size_t n);
+
+/*! Free a C array, each element in the array will be freed by the provided
+ *  free function.  Both NULL-terminated arrays and known length arrays are
+ *  supported.
+ *
+ *  \param[in] arr      Array to be freed.
+ *  \param[in] nmembers Number of members in the array, or SIZE_MAX for
+ *                      NULL-terminated arrays
+ *  \param[in] freefunc Function to call on each array member (e.g. ares_free)
+ */
+CARES_EXTERN void        ares_free_array(void *arr, size_t nmembers,
+                                         void (*freefunc)(void *));
+
+#endif /* __ARES_STR_H */