lib/silcutil/silcmemory.h

   1 /*
   2
   3   silcmemory.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1999 - 2008 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/Memory Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Routines for allocating and freeing memory.
  25  *
  26  ***/
  27
  28 #ifndef SILCMEMORY_H
  29 #define SILCMEMORY_H
  30
  31 /* Prototypes */
  32
  33 #ifndef SILC_STACKTRACE
  34
  35 /****f* silcutil/silc_malloc
  36  *
  37  * SYNOPSIS
  38  *
  39  *    void *silc_malloc(size_t size);
  40  *
  41  * DESCRIPTION
  42  *
  43  *    Allocates memory of `size' bytes and returns pointer to the allocated
  44  *    memory area.  Free the memory by calling silc_free.  Returns NULL on
  45  *    error and sets silc_errno.
  46  *
  47  ***/
  48 void *silc_malloc(size_t size);
  49
  50 /****f* silcutil/silc_calloc
  51  *
  52  * SYNOPSIS
  53  *
  54  *    void *silc_calloc(size_t items, size_t size);
  55  *
  56  * DESCRIPTION
  57  *
  58  *    Allocates memory of for an array of `items' elements of `size' bytes
  59  *    and returns pointer to the allocated memory area.  The memory area is
  60  *    also zeroed.  Free the memory by calling silc_free.  Returns NULL on
  61  *    error and sets silc_errno.
  62  *
  63  ***/
  64 void *silc_calloc(size_t items, size_t size);
  65
  66 /****f* silcutil/silc_realloc
  67  *
  68  * SYNOPSIS
  69  *
  70  *    void *silc_realloc(void *ptr, size_t size);
  71  *
  72  * DESCRIPTION
  73  *
  74  *    Change the size of the memory block indicated by `ptr' to the new
  75  *    size of `size' bytes.  The contents of `ptr' will not be changed.
  76  *    If `ptr' is NULL the call is equivalent to silc_malloc.  If the
  77  *    `size' is zero (0) the call is equivalent to silc_free.  Free the
  78  *    memory by calling silc_free.
  79  *
  80  * NOTES
  81  *
  82  *    The pointer returned to the reallocated memory area might not be
  83  *    same as `ptr'.
  84  *
  85  ***/
  86 void *silc_realloc(void *ptr, size_t size);
  87
  88 /****f* silcutil/silc_free
  89  *
  90  * SYNOPSIS
  91  *
  92  *    void silc_free(void *ptr);
  93  *
  94  * DESCRIPTION
  95  *
  96  *    Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
  97  *    operation is performed.
  98  *
  99  ***/
 100 void silc_free(void *ptr);
 101
 102 /****f* silcutil/silc_memdup
 103  *
 104  * SYNOPSIS
 105  *
 106  *    void *silc_memdup(const void *ptr, size_t size);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Duplicates the memory area indicated by `ptr' which is of size
 111  *    of `size' bytes. Returns pointer to the duplicated memory area.
 112  *    This NULL terminates the dupped memory area by allocating `size' + 1
 113  *    bytes, so this function can be used to duplicate strings that does
 114  *    not have NULL termination.
 115  *
 116  ***/
 117 void *silc_memdup(const void *ptr, size_t size);
 118
 119 /****f* silcutil/silc_strdup
 120  *
 121  * SYNOPSIS
 122  *
 123  *    char *silc_strdup(const char *str);
 124  *
 125  * DESCRIPTION
 126  *
 127  *    Duplicates the string indicated by `str' and returns the duplicated
 128  *    string.  Returns NULL on error and sets silc_errno.
 129  *
 130  ***/
 131 char *silc_strdup(const char *str);
 132
 133 #else
 134 #include "stacktrace.h"
 135 #endif /* SILC_STACKTRACE */
 136
 137
 138 /* Following functions that use SilcStack as memory source. */
 139
 140 /****f* silcutil/silc_smalloc
 141  *
 142  * SYNOPSIS
 143  *
 144  *    void *silc_smalloc(SilcStack stack, SilcUInt32 size);
 145  *
 146  * DESCRIPTION
 147  *
 148  *    Allocate memory block of size of `size' from the stack indicated by
 149  *    `stack' and return pointer to it.  Returns NULL on error.  This
 150  *    function allocates aligned memory so it can be used to allocate
 151  *    memory for structures, for example.
 152  *
 153  * NOTES
 154  *
 155  *    Be careful with this function:  do not free the returned pointer
 156  *    explicitly and do not save the returned pointer to a permanent
 157  *    location.
 158  *
 159  *    If `stack' is NULL this function calls silc_malloc.
 160  *
 161  ***/
 162 void *silc_smalloc(SilcStack stack, SilcUInt32 size);
 163
 164 /****f* silcutil/silc_scalloc
 165  *
 166  * SYNOPSIS
 167  *
 168  *    void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Allocate memory block of size of `size' from the stack indicated by
 173  *    `stack', zero the memory area and return pointer to it.  This
 174  *    function allocates aligned memory.  Returns NULL on error.
 175  *
 176  * NOTES
 177  *
 178  *    Be careful with this function:  do not free the returned pointer
 179  *    explicitly and do not save the returned pointer to a permanent
 180  *    location.
 181  *
 182  *    If `stack' is NULL this function calls silc_calloc.
 183  *
 184  ***/
 185 void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
 186
 187 /****f* silcutil/silc_srealloc
 188  *
 189  * SYNOPSIS
 190  *
 191  *    void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
 192  *                        void *ptr, SilcUInt32 size);
 193  *
 194  * DESCRIPTION
 195  *
 196  *    Change the size of the memory block indicated by `ptr' to the new
 197  *    size of `size' bytes.  The contents of `ptr' will not be changed.
 198  *    If `ptr' is NULL the call is equivalent to silc_smalloc.  If `size'
 199  *    is zero (0) error will occur.  Returns NULL on error and the old
 200  *    pointer remain intact.  This may return different pointer from `ptr'
 201  *
 202  * NOTES
 203  *
 204  *    If the reallocation from `stack' fails, this function will allocate
 205  *    new block of size of `size' bytes from `stack' and copy the data from
 206  *    `ptr' to the new memory block.
 207  *
 208  *    If `stack' is NULL this function calls silc_realloc.
 209  *
 210  ***/
 211 void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
 212                     void *ptr, SilcUInt32 size);
 213
 214 /****f* silcutil/silc_smemdup
 215  *
 216  * SYNOPSIS
 217  *
 218  *    void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
 219  *
 220  * DESCRIPTION
 221  *
 222  *    Duplicates the memory area indicated by `ptr' which is the size of
 223  *    `size' bytes.  Returns pointer to the duplicated memory area.  This
 224  *    NULL terminates the dupped memory area by allocating `size' + 1
 225  *    bytes, so this function can be used to duplicate strings that does not
 226  *    have NULL termination.  This function allocates aligned memory so
 227  *    it can be used to duplicate also structures.  Returns NULL on error.
 228  *
 229  * NOTES
 230  *
 231  *    Be careful with this function:  do not free the returned pointer
 232  *    explicitly and do not save the returned pointer to a permanent
 233  *    location.
 234  *
 235  *    If `stack' is NULL this function calls silc_memdup.
 236  *
 237  ***/
 238 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
 239
 240 /****f* silcutil/silc_sfree
 241  *
 242  * SYNOPSIS
 243  *
 244  *    void silc_scalloc(SilcStack stack, void *ptr);
 245  *
 246  * DESCRIPTION
 247  *
 248  *    This function can be used to free the `ptr' if `stack' is NULL.  This
 249  *    function does nothing if `stack' is non-NULL.  When `stack' is NULL
 250  *    this function calls silc_free.
 251  *
 252  ***/
 253 void silc_sfree(SilcStack stack, void *ptr);
 254
 255 /****f* silcutil/silc_sstrdup
 256  *
 257  * SYNOPSIS
 258  *
 259  *    char *silc_sstrdup(SilcStack stack, const char *str);
 260  *
 261  * DESCRIPTION
 262  *
 263  *    Duplicates the string indicated by `str' and returns the duplicated
 264  *    string.  Returns NULL on error.
 265  *
 266  * NOTES
 267  *
 268  *    Be careful with this function:  do not free the returned pointer
 269  *    explicitly and do not save the returned pointer to a permanent
 270  *    location.
 271  *
 272  *    If `stack' is NULL this function calls silc_strdup.
 273  *
 274  ***/
 275 char *silc_sstrdup(SilcStack stack, const char *str);
 276
 277 #endif /* SILCMEMORY_H */