lib/silcutil/silcmemory.h

   1 /*
   2
   3   silcmemory.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1999 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Memory Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Basic utility functions for allocating memory. All SILC routines, and
  25  * applications use these functions when they need to allocate, manipulate
  26  * and free memory.
  27  *
  28  ***/
  29
  30 #ifndef SILCMEMORY_H
  31 #define SILCMEMORY_H
  32
  33 /* Prototypes */
  34
  35 #ifndef SILC_STACKTRACE
  36
  37 /****f* silcutil/SilcMemoryAPI/silc_malloc
  38  *
  39  * SYNOPSIS
  40  *
  41  *    void *silc_malloc(size_t size);
  42  *
  43  * DESCRIPTION
  44  *
  45  *    Allocates memory of `size' bytes and returns pointer to the allocated
  46  *    memory area.  Free the memory by calling silc_free.  Returns NULL on
  47  *    error.
  48  *
  49  ***/
  50 void *silc_malloc(size_t size);
  51
  52 /****f* silcutil/SilcMemoryAPI/silc_calloc
  53  *
  54  * SYNOPSIS
  55  *
  56  *    void *silc_calloc(size_t items, size_t size);
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Allocates memory of for an array of `items' elements of `size' bytes
  61  *    and returns pointer to the allocated memory area.  The memory area is
  62  *    also zeroed.  Free the memory by calling silc_free.  Returns NULL on
  63  *    error.
  64  *
  65  ***/
  66 void *silc_calloc(size_t items, size_t size);
  67
  68 /****f* silcutil/SilcMemoryAPI/silc_realloc
  69  *
  70  * SYNOPSIS
  71  *
  72  *    void *silc_realloc(void *ptr, size_t size);
  73  *
  74  * DESCRIPTION
  75  *
  76  *    Change the size of the memory block indicated by `ptr' to the new
  77  *    size of `size' bytes.  The contents of `ptr' will not be changed.
  78  *    If `ptr' is NULL the call is equivalent to silc_malloc.  If the
  79  *    `size' is zero (0) the call is equivalent to silc_free.  Free the
  80  *    memory by calling silc_free.
  81  *
  82  * NOTES
  83  *
  84  *    The pointer returned to the reallocated memory area might not be
  85  *    same as `ptr'.
  86  *
  87  ***/
  88 void *silc_realloc(void *ptr, size_t size);
  89
  90 /****f* silcutil/SilcMemoryAPI/silc_free
  91  *
  92  * SYNOPSIS
  93  *
  94  *    void silc_free(void *ptr);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
  99  *    operation is performed.
 100  *
 101  ***/
 102 void silc_free(void *ptr);
 103
 104 /****f* silcutil/SilcMemoryAPI/silc_memdup
 105  *
 106  * SYNOPSIS
 107  *
 108  *    void *silc_memdup(const void *ptr, size_t size);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Duplicates the memory area indicated by `ptr' which is of size
 113  *    of `size' bytes. Returns pointer to the duplicated memory area.
 114  *    This NULL terminates the dupped memory area by allocating `size' + 1
 115  *    bytes, so this function can be used to duplicate strings that does
 116  *    not have NULL termination.
 117  *
 118  ***/
 119 void *silc_memdup(const void *ptr, size_t size);
 120
 121 #else
 122 #ifndef SILC_DIST_TOOLKIT
 123 #error "The stack trace is not supported in this distribution"
 124 #endif /* SILC_DIST_TOOLKIT */
 125
 126 #include "stacktrace.h"
 127 #endif /* SILC_STACKTRACE */
 128
 129
 130 /* Following functions that use SilcStack as memory source. */
 131
 132 /****f* silcutil/SilcMemoryAPI/silc_smalloc
 133  *
 134  * SYNOPSIS
 135  *
 136  *    void *silc_smalloc(SilcStack stack, SilcUInt32 size);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Allocate memory block of size of `size' from the stack indicated by
 141  *    `stack' and return pointer to it.  Returns NULL on error.  This
 142  *    function allocates aligned memory so it can be used to allocate
 143  *    memory for structures, for example.  If you allocate strings or
 144  *    data buffers using silc_smalloc_ua is recommended instead of this
 145  *    function.
 146  *
 147  * NOTES
 148  *
 149  *    Be careful with this function:  do not free the returned pointer
 150  *    explicitly and do not save the returned pointer to a permanent
 151  *    location.
 152  *
 153  *    If `stack' is NULL this function calls silc_malloc.
 154  *
 155  ***/
 156 void *silc_smalloc(SilcStack stack, SilcUInt32 size);
 157
 158 /****f* silcutil/SilcMemoryAPI/silc_smalloc_ua
 159  *
 160  * SYNOPSIS
 161  *
 162  *    void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
 163  *
 164  * DESCRIPTION
 165  *
 166  *    Allocate unaligned memory block of size of `size' from the stack
 167  *    indicated by `stack' and return pointer to it.  Returns NULL on error.
 168  *
 169  * NOTES
 170  *
 171  *    This function must not be used to allocate memory for structures.
 172  *    Use this function only for strings and data buffers.
 173  *
 174  *    Be careful with this function:  do not free the returned pointer
 175  *    explicitly and do not save the returned pointer to a permanent
 176  *    location.
 177  *
 178  *    If `stack' is NULL this function calls silc_malloc.
 179  *
 180  ***/
 181 void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
 182
 183 /****f* silcutil/SilcMemoryAPI/silc_scalloc
 184  *
 185  * SYNOPSIS
 186  *
 187  *    void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Allocate memory block of size of `size' from the stack indicated by
 192  *    `stack', zero the memory area and return pointer to it.  This
 193  *    function allocates aligned memory.  Returns NULL on error.
 194  *
 195  * NOTES
 196  *
 197  *    Be careful with this function:  do not free the returned pointer
 198  *    explicitly and do not save the returned pointer to a permanent
 199  *    location.
 200  *
 201  *    If `stack' is NULL this function calls silc_calloc.
 202  *
 203  ***/
 204 void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
 205
 206 /****f* silcutil/SilcMemoryAPI/silc_srealloc
 207  *
 208  * SYNOPSIS
 209  *
 210  *    void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
 211  *                        void *ptr, SilcUInt32 size);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Change the size of the memory block indicated by `ptr' to the new
 216  *    size of `size' bytes.  The contents of `ptr' will not be changed.
 217  *    If `ptr' is NULL the call is equivalent to silc_smalloc.  If `size'
 218  *    is zero (0) error will occur.  Returns NULL on error and the old
 219  *    pointer remain intact.
 220  *
 221  * NOTES
 222  *
 223  *    This function reallocates successfully only if the previous allocation
 224  *    to `stack' was `ptr'.  If there was another memory allocation between
 225  *    allocating `ptr' and this call, this routine will return NULL.  The
 226  *    NULL is also returned if the `size' does not fit to current stack
 227  *    and allocating new block would require slow copying of the data.  It
 228  *    is left to the caller to decide whether to allocate new pointer and
 229  *    copy the old data in case this function returns NULL.
 230  *
 231  *    This function can be used to reallocate only aligned memory allocated
 232  *    with silc_smalloc.
 233  *
 234  *    If `stack' is NULL this function calls silc_realloc.
 235  *
 236  ***/
 237 void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
 238                     void *ptr, SilcUInt32 size);
 239
 240 /****f* silcutil/SilcMemoryAPI/silc_srealloc_ua
 241  *
 242  * SYNOPSIS
 243  *
 244  *    void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
 245  *                           void *ptr, SilcUInt32 size);
 246  *
 247  * DESCRIPTION
 248  *
 249  *    Same as silc_srealloc but reallocates unaligned memory.
 250  *
 251  * NOTES
 252  *
 253  *    This function can be used to reallocate only unaligned memory
 254  *    allocated with silc_smalloc_ua.
 255  *
 256  *    If `stack' is NULL this function calls silc_realloc.
 257  *
 258  ***/
 259 void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
 260                        void *ptr, SilcUInt32 size);
 261
 262 /****f* silcutil/SilcMemoryAPI/silc_smemdup
 263  *
 264  * SYNOPSIS
 265  *
 266  *    void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
 267  *
 268  * DESCRIPTION
 269  *
 270  *    Duplicates the memory area indicated by `ptr' which is the size of
 271  *    `size' bytes.  Returns pointer to the duplicated memory area.  This
 272  *    NULL terminates the dupped memory area by allocating `size' + 1
 273  *    bytes, so this function can be used to duplicate strings that does not
 274  *    have NULL termination.  This function allocates aligned memory so
 275  *    it can be used to duplicate also structures.  Returns NULL on error.
 276  *
 277  * NOTES
 278  *
 279  *    Be careful with this function:  do not free the returned pointer
 280  *    explicitly and do not save the returned pointer to a permanent
 281  *    location.
 282  *
 283  *    If `stack' is NULL this function calls silc_memdup.
 284  *
 285  ***/
 286 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
 287
 288 /****f* silcutil/SilcMemoryAPI/silc_sstrdup
 289  *
 290  * SYNOPSIS
 291  *
 292  *    char *silc_sstrdup(SilcStack stack, const char *str);
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Duplicates the string indicated by `str' and returns the duplicated
 297  *    string.  This function allocates unaligned memory.  Returns NULL
 298  *    on error.
 299  *
 300  * NOTES
 301  *
 302  *    Be careful with this function:  do not free the returned pointer
 303  *    explicitly and do not save the returned pointer to a permanent
 304  *    location.
 305  *
 306  *    If `stack' is NULL this function calls silc_strdup.
 307  *
 308  ***/
 309 char *silc_sstrdup(SilcStack stack, const char *str);
 310
 311 #endif /* SILCMEMORY_H */