contrib/ntp/lib/isc/include/isc/string.h

   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 */