5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1999 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcutil/Memory Interface
24 * Routines for allocating and freeing memory.
33 #ifndef SILC_STACKTRACE
35 /****f* silcutil/silc_malloc
39 * void *silc_malloc(size_t size);
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.
48 void *silc_malloc(size_t size);
50 /****f* silcutil/silc_calloc
54 * void *silc_calloc(size_t items, size_t size);
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.
64 void *silc_calloc(size_t items, size_t size);
66 /****f* silcutil/silc_realloc
70 * void *silc_realloc(void *ptr, size_t size);
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.
82 * The pointer returned to the reallocated memory area might not be
86 void *silc_realloc(void *ptr, size_t size);
88 /****f* silcutil/silc_free
92 * void silc_free(void *ptr);
96 * Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
97 * operation is performed.
100 void silc_free(void *ptr);
102 /****f* silcutil/silc_memdup
106 * void *silc_memdup(const void *ptr, size_t size);
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.
117 void *silc_memdup(const void *ptr, size_t size);
119 /****f* silcutil/silc_strdup
123 * char *silc_strdup(const char *str);
127 * Duplicates the string indicated by `str' and returns the duplicated
128 * string. Returns NULL on error and sets silc_errno.
131 char *silc_strdup(const char *str);
134 #ifndef SILC_DIST_TOOLKIT
135 #error "The stack trace is not supported in this distribution"
136 #endif /* SILC_DIST_TOOLKIT */
138 #include "stacktrace.h"
139 #endif /* SILC_STACKTRACE */
142 /* Following functions that use SilcStack as memory source. */
144 /****f* silcutil/silc_smalloc
148 * void *silc_smalloc(SilcStack stack, SilcUInt32 size);
152 * Allocate memory block of size of `size' from the stack indicated by
153 * `stack' and return pointer to it. Returns NULL on error. This
154 * function allocates aligned memory so it can be used to allocate
155 * memory for structures, for example.
159 * Be careful with this function: do not free the returned pointer
160 * explicitly and do not save the returned pointer to a permanent
163 * If `stack' is NULL this function calls silc_malloc.
166 void *silc_smalloc(SilcStack stack, SilcUInt32 size);
168 /****f* silcutil/silc_scalloc
172 * void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
176 * Allocate memory block of size of `size' from the stack indicated by
177 * `stack', zero the memory area and return pointer to it. This
178 * function allocates aligned memory. Returns NULL on error.
182 * Be careful with this function: do not free the returned pointer
183 * explicitly and do not save the returned pointer to a permanent
186 * If `stack' is NULL this function calls silc_calloc.
189 void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
191 /****f* silcutil/silc_srealloc
195 * void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
196 * void *ptr, SilcUInt32 size);
200 * Change the size of the memory block indicated by `ptr' to the new
201 * size of `size' bytes. The contents of `ptr' will not be changed.
202 * If `ptr' is NULL the call is equivalent to silc_smalloc. If `size'
203 * is zero (0) error will occur. Returns NULL on error and the old
204 * pointer remain intact. This may return different pointer from `ptr'
208 * If the reallocation from `stack' fails, this function will allocate
209 * new block of size of `size' bytes from `stack' and copy the data from
210 * `ptr' to the new memory block.
212 * If `stack' is NULL this function calls silc_realloc.
215 void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
216 void *ptr, SilcUInt32 size);
218 /****f* silcutil/silc_smemdup
222 * void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
226 * Duplicates the memory area indicated by `ptr' which is the size of
227 * `size' bytes. Returns pointer to the duplicated memory area. This
228 * NULL terminates the dupped memory area by allocating `size' + 1
229 * bytes, so this function can be used to duplicate strings that does not
230 * have NULL termination. This function allocates aligned memory so
231 * it can be used to duplicate also structures. Returns NULL on error.
235 * Be careful with this function: do not free the returned pointer
236 * explicitly and do not save the returned pointer to a permanent
239 * If `stack' is NULL this function calls silc_memdup.
242 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
244 /****f* silcutil/silc_sfree
248 * void silc_scalloc(SilcStack stack, void *ptr);
252 * This function can be used to free the `ptr' if `stack' is NULL. This
253 * function does nothing if `stack' is non-NULL. When `stack' is NULL
254 * this function calls silc_free.
257 void silc_sfree(SilcStack stack, void *ptr);
259 /****f* silcutil/silc_sstrdup
263 * char *silc_sstrdup(SilcStack stack, const char *str);
267 * Duplicates the string indicated by `str' and returns the duplicated
268 * string. Returns NULL on error.
272 * Be careful with this function: do not free the returned pointer
273 * explicitly and do not save the returned pointer to a permanent
276 * If `stack' is NULL this function calls silc_strdup.
279 char *silc_sstrdup(SilcStack stack, const char *str);
281 #endif /* SILCMEMORY_H */