5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1999 - 2005 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/SILC Memory Interface
24 * Basic utility functions for allocating memory. All SILC routines, and
25 * applications use these functions when they need to allocate, manipulate
28 * Currently all allocation routines assert() that the memory was allocated
29 * successfully. Hence, if memory allocation fails it is fatal error.
38 #ifndef SILC_STACKTRACE
40 /****f* silcutil/SilcMemoryAPI/silc_malloc
44 * void *silc_malloc(size_t size);
48 * Allocates memory of `size' bytes and returns pointer to the allocated
49 * memory area. Free the memory by calling silc_free.
52 void *silc_malloc(size_t size);
54 /****f* silcutil/SilcMemoryAPI/silc_calloc
58 * void *silc_calloc(size_t items, size_t size);
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.
67 void *silc_calloc(size_t items, size_t size);
69 /****f* silcutil/SilcMemoryAPI/silc_realloc
73 * void *silc_realloc(void *ptr, size_t size);
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.
85 * The pointer returned to the reallocated memory area might not be
89 void *silc_realloc(void *ptr, size_t size);
91 /****f* silcutil/SilcMemoryAPI/silc_free
95 * void silc_free(void *ptr);
99 * Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
100 * operation is performed.
103 void silc_free(void *ptr);
105 /****f* silcutil/SilcMemoryAPI/silc_memdup
109 * void *silc_memdup(const void *ptr, size_t size);
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.
120 void *silc_memdup(const void *ptr, size_t size);
123 #ifndef SILC_DIST_TOOLKIT
124 #error "The stack trace is not supported in this distribution"
127 #include "stacktrace.h"
128 #endif /* SILC_STACKTRACE */
131 /* Following functions that use SilcStack as memory source. */
133 /****f* silcutil/SilcMemoryAPI/silc_smalloc
137 * void *silc_smalloc(SilcStack stack, SilcUInt32 size);
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
150 * Be careful with this function: do not free the returned pointer
151 * explicitly and do not save the returned pointer to a permanent
154 * If `stack' is NULL this function calls silc_malloc.
157 void *silc_smalloc(SilcStack stack, SilcUInt32 size);
159 /****f* silcutil/SilcMemoryAPI/silc_smalloc_ua
163 * void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
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.
172 * This function must not be used to allocate memory for structures.
173 * Use this function only for strings and data buffers.
175 * Be careful with this function: do not free the returned pointer
176 * explicitly and do not save the returned pointer to a permanent
179 * If `stack' is NULL this function calls silc_malloc.
182 void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
184 /****f* silcutil/SilcMemoryAPI/silc_scalloc
188 * void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
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.
198 * Be careful with this function: do not free the returned pointer
199 * explicitly and do not save the returned pointer to a permanent
202 * If `stack' is NULL this function calls silc_calloc.
205 void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
207 /****f* silcutil/SilcMemoryAPI/silc_srealloc
211 * void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
212 * void *ptr, SilcUInt32 size);
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.
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.
232 * This function can be used to reallocate only aligned memory allocated
235 * If `stack' is NULL this function calls silc_realloc.
238 void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
239 void *ptr, SilcUInt32 size);
241 /****f* silcutil/SilcMemoryAPI/silc_srealloc_ua
245 * void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
246 * void *ptr, SilcUInt32 size);
250 * Same as silc_srealloc but reallocates unaligned memory.
254 * This function can be used to reallocate only unaligned memory
255 * allocated with silc_smalloc_ua.
257 * If `stack' is NULL this function calls silc_realloc.
260 void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
261 void *ptr, SilcUInt32 size);
263 /****f* silcutil/SilcMemoryAPI/silc_smemdup
267 * void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
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.
280 * Be careful with this function: do not free the returned pointer
281 * explicitly and do not save the returned pointer to a permanent
284 * If `stack' is NULL this function calls silc_memdup.
287 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
289 /****f* silcutil/SilcMemoryAPI/silc_sstrdup
293 * char *silc_sstrdup(SilcStack stack, const char *str);
297 * Duplicates the string indicated by `str' and returns the duplicated
298 * string. This function allocates unaligned memory. Returns NULL
303 * Be careful with this function: do not free the returned pointer
304 * explicitly and do not save the returned pointer to a permanent
307 * If `stack' is NULL this function calls silc_strdup.
310 char *silc_sstrdup(SilcStack stack, const char *str);
312 #endif /* SILCMEMORY_H */