1 /* 2 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 2000, 2001, 2003 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18 /* $Id: string.h,v 1.23 2007/09/13 04:48:16 each Exp $ */ 19 20 #ifndef ISC_STRING_H 21 #define ISC_STRING_H 1 22 23 /*! \file isc/string.h */ 24 25 #include <isc/formatcheck.h> 26 #include <isc/int.h> 27 #include <isc/lang.h> 28 #include <isc/platform.h> 29 #include <isc/types.h> 30 31 #include <string.h> 32 33 #ifdef ISC_PLATFORM_HAVESTRINGSH 34 #include <strings.h> 35 #endif 36 37 #define ISC_STRING_MAGIC 0x5e 38 39 ISC_LANG_BEGINDECLS 40 41 isc_uint64_t 42 isc_string_touint64(char *source, char **endp, int base); 43 /*%< 44 * Convert the string pointed to by 'source' to isc_uint64_t. 45 * 46 * On successful conversion 'endp' points to the first character 47 * after conversion is complete. 48 * 49 * 'base': 0 or 2..36 50 * 51 * If base is 0 the base is computed from the string type. 52 * 53 * On error 'endp' points to 'source'. 54 */ 55 56 isc_result_t 57 isc_string_copy(char *target, size_t size, const char *source); 58 /* 59 * Copy the string pointed to by 'source' to 'target' which is a 60 * pointer to a string of at least 'size' bytes. 61 * 62 * Requires: 63 * 'target' is a pointer to a char[] of at least 'size' bytes. 64 * 'size' an integer > 0. 65 * 'source' == NULL or points to a NUL terminated string. 66 * 67 * Ensures: 68 * If result == ISC_R_SUCCESS 69 * 'target' will be a NUL terminated string of no more 70 * than 'size' bytes (including NUL). 71 * 72 * If result == ISC_R_NOSPACE 73 * 'target' is undefined. 74 * 75 * Returns: 76 * ISC_R_SUCCESS -- 'source' was successfully copied to 'target'. 77 * ISC_R_NOSPACE -- 'source' could not be copied since 'target' 78 * is too small. 79 */ 80 81 void 82 isc_string_copy_truncate(char *target, size_t size, const char *source); 83 /* 84 * Copy the string pointed to by 'source' to 'target' which is a 85 * pointer to a string of at least 'size' bytes. 86 * 87 * Requires: 88 * 'target' is a pointer to a char[] of at least 'size' bytes. 89 * 'size' an integer > 0. 90 * 'source' == NULL or points to a NUL terminated string. 91 * 92 * Ensures: 93 * 'target' will be a NUL terminated string of no more 94 * than 'size' bytes (including NUL). 95 */ 96 97 isc_result_t 98 isc_string_append(char *target, size_t size, const char *source); 99 /* 100 * Append the string pointed to by 'source' to 'target' which is a 101 * pointer to a NUL terminated string of at least 'size' bytes. 102 * 103 * Requires: 104 * 'target' is a pointer to a NUL terminated char[] of at 105 * least 'size' bytes. 106 * 'size' an integer > 0. 107 * 'source' == NULL or points to a NUL terminated string. 108 * 109 * Ensures: 110 * If result == ISC_R_SUCCESS 111 * 'target' will be a NUL terminated string of no more 112 * than 'size' bytes (including NUL). 113 * 114 * If result == ISC_R_NOSPACE 115 * 'target' is undefined. 116 * 117 * Returns: 118 * ISC_R_SUCCESS -- 'source' was successfully appended to 'target'. 119 * ISC_R_NOSPACE -- 'source' could not be appended since 'target' 120 * is too small. 121 */ 122 123 void 124 isc_string_append_truncate(char *target, size_t size, const char *source); 125 /* 126 * Append the string pointed to by 'source' to 'target' which is a 127 * pointer to a NUL terminated string of at least 'size' bytes. 128 * 129 * Requires: 130 * 'target' is a pointer to a NUL terminated char[] of at 131 * least 'size' bytes. 132 * 'size' an integer > 0. 133 * 'source' == NULL or points to a NUL terminated string. 134 * 135 * Ensures: 136 * 'target' will be a NUL terminated string of no more 137 * than 'size' bytes (including NUL). 138 */ 139 140 isc_result_t 141 isc_string_printf(char *target, size_t size, const char *format, ...) 142 ISC_FORMAT_PRINTF(3, 4); 143 /* 144 * Print 'format' to 'target' which is a pointer to a string of at least 145 * 'size' bytes. 146 * 147 * Requires: 148 * 'target' is a pointer to a char[] of at least 'size' bytes. 149 * 'size' an integer > 0. 150 * 'format' == NULL or points to a NUL terminated string. 151 * 152 * Ensures: 153 * If result == ISC_R_SUCCESS 154 * 'target' will be a NUL terminated string of no more 155 * than 'size' bytes (including NUL). 156 * 157 * If result == ISC_R_NOSPACE 158 * 'target' is undefined. 159 * 160 * Returns: 161 * ISC_R_SUCCESS -- 'format' was successfully printed to 'target'. 162 * ISC_R_NOSPACE -- 'format' could not be printed to 'target' since it 163 * is too small. 164 */ 165 166 void 167 isc_string_printf_truncate(char *target, size_t size, const char *format, ...) 168 ISC_FORMAT_PRINTF(3, 4); 169 /* 170 * Print 'format' to 'target' which is a pointer to a string of at least 171 * 'size' bytes. 172 * 173 * Requires: 174 * 'target' is a pointer to a char[] of at least 'size' bytes. 175 * 'size' an integer > 0. 176 * 'format' == NULL or points to a NUL terminated string. 177 * 178 * Ensures: 179 * 'target' will be a NUL terminated string of no more 180 * than 'size' bytes (including NUL). 181 */ 182 183 184 char * 185 isc_string_regiondup(isc_mem_t *mctx, const isc_region_t *source); 186 /* 187 * Copy the region pointed to by r to a NUL terminated string 188 * allocated from the memory context pointed to by mctx. 189 * 190 * The result should be deallocated using isc_mem_free() 191 * 192 * Requires: 193 * 'mctx' is a point to a valid memory context. 194 * 'source' is a pointer to a valid region. 195 * 196 * Returns: 197 * a pointer to a NUL terminated string or 198 * NULL if memory for the copy could not be allocated 199 * 200 */ 201 202 int 203 isc_tsmemcmp(const void *p1, const void *p2, size_t len); 204 /* 205 * Lexicographic compare 'len' unsigned bytes from 'p1' and 'p2' 206 * like 'memcmp()'. 207 * 208 * This function is safe from timing attacks as it has a runtime that 209 * only depends on 'len' and has no early-out option. 210 * 211 * Use this to check MACs and other material that is security sensitive. 212 * 213 * Returns: 214 * (let x be the byte offset of the first different byte) 215 * -1 if (u_char)p1[x] < (u_char)p2[x] 216 * 1 if (u_char)p1[x] > (u_char)p2[x] 217 * 0 if byte series are equal 218 */ 219 220 char * 221 isc_string_separate(char **stringp, const char *delim); 222 223 #ifdef ISC_PLATFORM_NEEDSTRSEP 224 #define strsep isc_string_separate 225 #endif 226 227 #ifdef ISC_PLATFORM_NEEDMEMMOVE 228 #define memmove(a,b,c) bcopy(b,a,c) 229 #endif 230 231 size_t 232 isc_string_strlcpy(char *dst, const char *src, size_t size); 233 234 235 #ifdef ISC_PLATFORM_NEEDSTRLCPY 236 #define strlcpy isc_string_strlcpy 237 #endif 238 239 240 size_t 241 isc_string_strlcat(char *dst, const char *src, size_t size); 242 243 #ifdef ISC_PLATFORM_NEEDSTRLCAT 244 #define strlcat isc_string_strlcat 245 #endif 246 247 ISC_LANG_ENDDECLS 248 249 #endif /* ISC_STRING_H */ 250