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