5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1999 - 2007 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
35 #ifndef SILC_STACKTRACE
37 /****f* silcutil/SilcMemoryAPI/silc_malloc
41 * void *silc_malloc(size_t size);
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 and sets silc_errno.
50 void *silc_malloc(size_t size);
52 /****f* silcutil/SilcMemoryAPI/silc_calloc
56 * void *silc_calloc(size_t items, size_t size);
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 and sets silc_errno.
66 void *silc_calloc(size_t items, size_t size);
68 /****f* silcutil/SilcMemoryAPI/silc_realloc
72 * void *silc_realloc(void *ptr, size_t size);
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.
84 * The pointer returned to the reallocated memory area might not be
88 void *silc_realloc(void *ptr, size_t size);
90 /****f* silcutil/SilcMemoryAPI/silc_free
94 * void silc_free(void *ptr);
98 * Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
99 * operation is performed.
102 void silc_free(void *ptr);
104 /****f* silcutil/SilcMemoryAPI/silc_memdup
108 * void *silc_memdup(const void *ptr, size_t size);
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.
119 void *silc_memdup(const void *ptr, size_t size);
121 /****f* silcutil/SilcMemoryAPI/silc_strdup
125 * char *silc_strdup(const char *str);
129 * Duplicates the string indicated by `str' and returns the duplicated
130 * string. Returns NULL on error and sets silc_errno.
133 char *silc_strdup(const char *str);
136 #ifndef SILC_DIST_TOOLKIT
137 #error "The stack trace is not supported in this distribution"
138 #endif /* SILC_DIST_TOOLKIT */
140 #include "stacktrace.h"
141 #endif /* SILC_STACKTRACE */
144 /* Following functions that use SilcStack as memory source. */
146 /****f* silcutil/SilcMemoryAPI/silc_smalloc
150 * void *silc_smalloc(SilcStack stack, SilcUInt32 size);
154 * Allocate memory block of size of `size' from the stack indicated by
155 * `stack' and return pointer to it. Returns NULL on error. This
156 * function allocates aligned memory so it can be used to allocate
157 * memory for structures, for example.
161 * Be careful with this function: do not free the returned pointer
162 * explicitly and do not save the returned pointer to a permanent
165 * If `stack' is NULL this function calls silc_malloc.
168 void *silc_smalloc(SilcStack stack, SilcUInt32 size);
170 /****f* silcutil/SilcMemoryAPI/silc_scalloc
174 * void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
178 * Allocate memory block of size of `size' from the stack indicated by
179 * `stack', zero the memory area and return pointer to it. This
180 * function allocates aligned memory. Returns NULL on error.
184 * Be careful with this function: do not free the returned pointer
185 * explicitly and do not save the returned pointer to a permanent
188 * If `stack' is NULL this function calls silc_calloc.
191 void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
193 /****f* silcutil/SilcMemoryAPI/silc_srealloc
197 * void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
198 * void *ptr, SilcUInt32 size);
202 * Change the size of the memory block indicated by `ptr' to the new
203 * size of `size' bytes. The contents of `ptr' will not be changed.
204 * If `ptr' is NULL the call is equivalent to silc_smalloc. If `size'
205 * is zero (0) error will occur. Returns NULL on error and the old
206 * pointer remain intact.
210 * This function reallocates successfully only if the previous allocation
211 * to `stack' was `ptr'. If there was another memory allocation between
212 * allocating `ptr' and this call, this routine will return NULL. The
213 * NULL is also returned if the `size' does not fit to current stack
214 * and allocating new block would require slow copying of the data. It
215 * is left to the caller to decide whether to allocate new pointer and
216 * copy the old data in case this function returns NULL.
218 * If `stack' is NULL this function calls silc_realloc.
221 void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
222 void *ptr, SilcUInt32 size);
224 /****f* silcutil/SilcMemoryAPI/silc_smemdup
228 * void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
232 * Duplicates the memory area indicated by `ptr' which is the size of
233 * `size' bytes. Returns pointer to the duplicated memory area. This
234 * NULL terminates the dupped memory area by allocating `size' + 1
235 * bytes, so this function can be used to duplicate strings that does not
236 * have NULL termination. This function allocates aligned memory so
237 * it can be used to duplicate also structures. Returns NULL on error.
241 * Be careful with this function: do not free the returned pointer
242 * explicitly and do not save the returned pointer to a permanent
245 * If `stack' is NULL this function calls silc_memdup.
248 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
250 /****f* silcutil/SilcMemoryAPI/silc_sfree
254 * void silc_scalloc(SilcStack stack, void *ptr);
258 * This function can be used to free the `ptr' if `stack' is NULL. This
259 * function does nothing if `stack' is non-NULL. When `stack' is NULL
260 * this function calls silc_free.
263 void silc_sfree(SilcStack stack, void *ptr);
265 /****f* silcutil/SilcMemoryAPI/silc_sstrdup
269 * char *silc_sstrdup(SilcStack stack, const char *str);
273 * Duplicates the string indicated by `str' and returns the duplicated
274 * string. Returns NULL on error.
278 * Be careful with this function: do not free the returned pointer
279 * explicitly and do not save the returned pointer to a permanent
282 * If `stack' is NULL this function calls silc_strdup.
285 char *silc_sstrdup(SilcStack stack, const char *str);
287 #endif /* SILCMEMORY_H */