ares_str.h (9996B)
1 /* MIT License 2 * 3 * Copyright (c) 1998 Massachusetts Institute of Technology 4 * Copyright (c) The c-ares project and its contributors 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to deal 8 * in the Software without restriction, including without limitation the rights 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 * copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice (including the next 14 * paragraph) shall be included in all copies or substantial portions of the 15 * Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 * 25 * SPDX-License-Identifier: MIT 26 */ 27 #ifndef __ARES_STR_H 28 #define __ARES_STR_H 29 30 CARES_EXTERN char *ares_strdup(const char *s1); 31 32 /*! Scan up to maxlen bytes for the first NULL character and return 33 * its index, or maxlen if not found. The function only returns 34 * maxlen if the first maxlen bytes were not NULL characters; it 35 * makes no guarantee for what \c str[maxlen] (if defined) is, and 36 * does not access it. It is behaving like the POSIX \c strnlen() 37 * function, except that it returns 0 if the \p str pointer is \c 38 * NULL. 39 * 40 * \param[in] str The string to scan for the NULL character 41 * \param[in] maxlen The maximum number of bytes to scan 42 * \return Index of first NULL byte. Between 0 and maxlen (inclusive). 43 */ 44 CARES_EXTERN size_t ares_strnlen(const char *str, size_t maxlen); 45 46 CARES_EXTERN size_t ares_strlen(const char *str); 47 48 /*! Copy string from source to destination with destination buffer size 49 * provided. The destination is guaranteed to be null terminated, if the 50 * provided buffer isn't large enough, only those bytes from the source that 51 * will fit will be copied. 52 * 53 * \param[out] dest Destination buffer 54 * \param[in] src Source to copy 55 * \param[in] dest_size Size of destination buffer 56 * \return String length. Will be at most dest_size-1 57 */ 58 CARES_EXTERN size_t ares_strcpy(char *dest, const char *src, size_t dest_size); 59 60 CARES_EXTERN ares_bool_t ares_str_isnum(const char *str); 61 CARES_EXTERN ares_bool_t ares_str_isalnum(const char *str); 62 63 CARES_EXTERN void ares_str_ltrim(char *str); 64 CARES_EXTERN void ares_str_rtrim(char *str); 65 CARES_EXTERN void ares_str_trim(char *str); 66 CARES_EXTERN void ares_str_lower(char *str); 67 68 CARES_EXTERN unsigned char ares_tolower(unsigned char c); 69 CARES_EXTERN unsigned char *ares_memmem(const unsigned char *big, 70 size_t big_len, 71 const unsigned char *little, 72 size_t little_len); 73 CARES_EXTERN ares_bool_t ares_memeq(const unsigned char *ptr, 74 const unsigned char *val, size_t len); 75 CARES_EXTERN ares_bool_t ares_memeq_ci(const unsigned char *ptr, 76 const unsigned char *val, size_t len); 77 CARES_EXTERN ares_bool_t ares_is_hostname(const char *str); 78 79 /*! Validate the string provided is printable. The length specified must be 80 * at least the size of the buffer provided. If a NULL-terminator is hit 81 * before the length provided is hit, this will not be considered a valid 82 * printable string. This does not validate that the string is actually 83 * NULL terminated. 84 * 85 * \param[in] str Buffer containing string to evaluate. 86 * \param[in] len Number of characters to evaluate within provided buffer. 87 * If 0, will return TRUE since it did not hit an exception. 88 * \return ARES_TRUE if the entire string is printable, ARES_FALSE if not. 89 */ 90 CARES_EXTERN ares_bool_t ares_str_isprint(const char *str, size_t len); 91 92 /* We only care about ASCII rules */ 93 #define ares_isascii(x) (((unsigned char)x) <= 127) 94 95 #define ares_isdigit(x) (((unsigned char)x) >= '0' && ((unsigned char)x) <= '9') 96 97 #define ares_isxdigit(x) \ 98 (ares_isdigit(x) || \ 99 (((unsigned char)x) >= 'a' && ((unsigned char)x) <= 'f') || \ 100 (((unsigned char)x) >= 'A' && ((unsigned char)x) <= 'F')) 101 102 #define ares_isupper(x) (((unsigned char)x) >= 'A' && ((unsigned char)x) <= 'Z') 103 104 #define ares_islower(x) (((unsigned char)x) >= 'a' && ((unsigned char)x) <= 'z') 105 106 #define ares_isalpha(x) (ares_islower(x) || ares_isupper(x)) 107 108 #define ares_isspace(x) \ 109 (((unsigned char)(x)) == '\r' || ((unsigned char)(x)) == '\t' || \ 110 ((unsigned char)(x)) == ' ' || ((unsigned char)(x)) == '\v' || \ 111 ((unsigned char)(x)) == '\f' || ((unsigned char)(x)) == '\n') 112 113 #define ares_isprint(x) \ 114 (((unsigned char)(x)) >= 0x20 && ((unsigned char)(x)) <= 0x7E) 115 116 /* Character set allowed by hostnames. This is to include the normal 117 * domain name character set plus: 118 * - underscores which are used in SRV records. 119 * - Forward slashes such as are used for classless in-addr.arpa 120 * delegation (CNAMEs) 121 * - Asterisks may be used for wildcard domains in CNAMEs as seen in the 122 * real world. 123 * While RFC 2181 section 11 does state not to do validation, 124 * that applies to servers, not clients. Vulnerabilities have been 125 * reported when this validation is not performed. Security is more 126 * important than edge-case compatibility (which is probably invalid 127 * anyhow). 128 * [A-Za-z0-9-*._/] 129 */ 130 #define ares_is_hostnamech(x) \ 131 (ares_isalpha(x) || ares_isdigit(x) || ((unsigned char)(x)) == '-' || \ 132 ((unsigned char)(x)) == '.' || ((unsigned char)(x)) == '_' || \ 133 ((unsigned char)(x)) == '/' || ((unsigned char)(x)) == '*') 134 135 136 /*! Compare two strings (for sorting) 137 * 138 * Treats NULL and "" strings as equivalent 139 * 140 * \param[in] a First String 141 * \param[in] b Second String 142 * \return < 0 if First String less than Second String, 143 * 0 if First String equal to Second String, 144 * > 0 if First String greater than Second String 145 */ 146 CARES_EXTERN int ares_strcmp(const char *a, const char *b); 147 148 /*! Compare two strings up to specified length (for sorting) 149 * 150 * Treats NULL and "" strings as equivalent 151 * 152 * \param[in] a First String 153 * \param[in] b Second String 154 * \param[in] n Length 155 * \return < 0 if First String less than Second String, 156 * 0 if First String equal to Second String, 157 * > 0 if First String greater than Second String 158 */ 159 CARES_EXTERN int ares_strncmp(const char *a, const char *b, size_t n); 160 161 162 /*! Compare two strings in a case-insensitive manner (for sorting) 163 * 164 * Treats NULL and "" strings as equivalent 165 * 166 * \param[in] a First String 167 * \param[in] b Second String 168 * \return < 0 if First String less than Second String, 169 * 0 if First String equal to Second String, 170 * > 0 if First String greater than Second String 171 */ 172 CARES_EXTERN int ares_strcasecmp(const char *a, const char *b); 173 174 /*! Compare two strings in a case-insensitive manner up to specified length 175 * (for sorting) 176 * 177 * Treats NULL and "" strings as equivalent 178 * 179 * \param[in] a First String 180 * \param[in] b Second String 181 * \param[in] n Length 182 * \return < 0 if First String less than Second String, 183 * 0 if First String equal to Second String, 184 * > 0 if First String greater than Second String 185 */ 186 CARES_EXTERN int ares_strncasecmp(const char *a, const char *b, size_t n); 187 188 /*! Compare two strings for equality 189 * 190 * Treats NULL and "" strings as equivalent 191 * 192 * \param[in] a First String 193 * \param[in] b Second String 194 * \return ARES_TRUE on match, or ARES_FALSE if no match 195 */ 196 CARES_EXTERN ares_bool_t ares_streq(const char *a, const char *b); 197 198 /*! Compare two strings for equality up to specified length 199 * 200 * Treats NULL and "" strings as equivalent 201 * 202 * \param[in] a First String 203 * \param[in] b Second String 204 * \param[in] n Length 205 * \return ARES_TRUE on match, or ARES_FALSE if no match 206 */ 207 CARES_EXTERN ares_bool_t ares_streq_max(const char *a, const char *b, size_t n); 208 209 /*! Compare two strings for equality in a case insensitive manner 210 * 211 * Treats NULL and "" strings as equivalent 212 * 213 * \param[in] a First String 214 * \param[in] b Second String 215 * \return ARES_TRUE on match, or ARES_FALSE if no match 216 */ 217 CARES_EXTERN ares_bool_t ares_strcaseeq(const char *a, const char *b); 218 219 /*! Compare two strings for equality up to specified length in a case 220 * insensitive manner 221 * 222 * Treats NULL and "" strings as equivalent 223 * 224 * \param[in] a First String 225 * \param[in] b Second String 226 * \param[in] n Length 227 * \return ARES_TRUE on match, or ARES_FALSE if no match 228 */ 229 CARES_EXTERN ares_bool_t ares_strcaseeq_max(const char *a, const char *b, 230 size_t n); 231 232 /*! Free a C array, each element in the array will be freed by the provided 233 * free function. Both NULL-terminated arrays and known length arrays are 234 * supported. 235 * 236 * \param[in] arr Array to be freed. 237 * \param[in] nmembers Number of members in the array, or SIZE_MAX for 238 * NULL-terminated arrays 239 * \param[in] freefunc Function to call on each array member (e.g. ares_free) 240 */ 241 CARES_EXTERN void ares_free_array(void *arr, size_t nmembers, 242 void (*freefunc)(void *)); 243 244 #endif /* __ARES_STR_H */