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