Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1999 - 2005 Pekka Riikonen
+ Copyright (C) 1999 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*/
-/****h* silcutil/SILC Memory Interface
+/****h* silcutil/Memory Interface
*
* DESCRIPTION
*
- * Basic utility functions for allocating memory. All SILC routines, and
- * applications use these functions when they need to allocate, manipulate
- * and free memory.
- *
- * Currently all allocation routines assert() that the memory was allocated
- * successfully. Hence, if memory allocation fails it is fatal error.
+ * Routines for allocating and freeing memory.
*
***/
/* Prototypes */
-#ifndef SILC_STACKTRACE
+#ifndef SILC_MEMTRACE
-/****f* silcutil/SilcMemoryAPI/silc_malloc
+/****f* silcutil/silc_malloc
*
* SYNOPSIS
*
* DESCRIPTION
*
* Allocates memory of `size' bytes and returns pointer to the allocated
- * memory area. Free the memory by calling silc_free.
+ * memory area. Free the memory by calling silc_free. Returns NULL on
+ * error and sets silc_errno.
*
***/
void *silc_malloc(size_t size);
-/****f* silcutil/SilcMemoryAPI/silc_calloc
+/****f* silcutil/silc_calloc
*
* SYNOPSIS
*
*
* Allocates memory of for an array of `items' elements of `size' bytes
* and returns pointer to the allocated memory area. The memory area is
- * also zeroed. Free the memory by calling silc_free.
+ * also zeroed. Free the memory by calling silc_free. Returns NULL on
+ * error and sets silc_errno.
*
***/
void *silc_calloc(size_t items, size_t size);
-/****f* silcutil/SilcMemoryAPI/silc_realloc
+/****f* silcutil/silc_realloc
*
* SYNOPSIS
*
***/
void *silc_realloc(void *ptr, size_t size);
-/****f* silcutil/SilcMemoryAPI/silc_free
+/****f* silcutil/silc_free
*
* SYNOPSIS
*
***/
void silc_free(void *ptr);
-/****f* silcutil/SilcMemoryAPI/silc_memdup
+/****f* silcutil/silc_memdup
*
* SYNOPSIS
*
***/
void *silc_memdup(const void *ptr, size_t size);
-#else
-#ifndef SILC_DIST_TOOLKIT
-#error "The stack trace is not supported in this distribution"
-#endif
+/****f* silcutil/silc_strdup
+ *
+ * SYNOPSIS
+ *
+ * char *silc_strdup(const char *str);
+ *
+ * DESCRIPTION
+ *
+ * Duplicates the string indicated by `str' and returns the duplicated
+ * string. Returns NULL on error and sets silc_errno.
+ *
+ ***/
+char *silc_strdup(const char *str);
-#include "stacktrace.h"
-#endif /* SILC_STACKTRACE */
+#else
+#include "memtrace.h"
+#endif /* SILC_MEMTRACE */
/* Following functions that use SilcStack as memory source. */
-/****f* silcutil/SilcMemoryAPI/silc_smalloc
+/****f* silcutil/silc_smalloc
*
* SYNOPSIS
*
* Allocate memory block of size of `size' from the stack indicated by
* `stack' and return pointer to it. Returns NULL on error. This
* function allocates aligned memory so it can be used to allocate
- * memory for structures, for example. If you allocate strings or
- * data buffers using silc_smalloc_ua is recommended instead of this
- * function.
+ * memory for structures, for example.
*
* NOTES
*
***/
void *silc_smalloc(SilcStack stack, SilcUInt32 size);
-/****f* silcutil/SilcMemoryAPI/silc_smalloc_ua
- *
- * SYNOPSIS
- *
- * void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
- *
- * DESCRIPTION
- *
- * Allocate unaligned memory block of size of `size' from the stack
- * indicated by `stack' and return pointer to it. Returns NULL on error.
- *
- * NOTES
- *
- * This function must not be used to allocate memory for structures.
- * Use this function only for strings and data buffers.
- *
- * Be careful with this function: do not free the returned pointer
- * explicitly and do not save the returned pointer to a permanent
- * location.
- *
- * If `stack' is NULL this function calls silc_malloc.
- *
- ***/
-void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size);
-
-/****f* silcutil/SilcMemoryAPI/silc_scalloc
+/****f* silcutil/silc_scalloc
*
* SYNOPSIS
*
***/
void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
-/****f* silcutil/SilcMemoryAPI/silc_srealloc
+/****f* silcutil/silc_srealloc
*
* SYNOPSIS
*
* size of `size' bytes. The contents of `ptr' will not be changed.
* If `ptr' is NULL the call is equivalent to silc_smalloc. If `size'
* is zero (0) error will occur. Returns NULL on error and the old
- * pointer remain intact.
+ * pointer remain intact. This may return different pointer from `ptr'
*
* NOTES
*
- * This function reallocates successfully only if the previous allocation
- * to `stack' was `ptr'. If there was another memory allocation between
- * allocating `ptr' and this call, this routine will return NULL. The
- * NULL is also returned if the `size' does not fit to current stack
- * and allocating new block would require slow copying of the data. It
- * is left to the caller to decide whether to allocate new pointer and
- * copy the old data in case this function returns NULL.
- *
- * This function can be used to reallocate only aligned memory allocated
- * with silc_smalloc.
+ * If the reallocation from `stack' fails, this function will allocate
+ * new block of size of `size' bytes from `stack' and copy the data from
+ * `ptr' to the new memory block.
*
* If `stack' is NULL this function calls silc_realloc.
*
void *silc_srealloc(SilcStack stack, SilcUInt32 old_size,
void *ptr, SilcUInt32 size);
-/****f* silcutil/SilcMemoryAPI/silc_srealloc_ua
- *
- * SYNOPSIS
- *
- * void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
- * void *ptr, SilcUInt32 size);
- *
- * DESCRIPTION
- *
- * Same as silc_srealloc but reallocates unaligned memory.
- *
- * NOTES
- *
- * This function can be used to reallocate only unaligned memory
- * allocated with silc_smalloc_ua.
- *
- * If `stack' is NULL this function calls silc_realloc.
- *
- ***/
-void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
- void *ptr, SilcUInt32 size);
-
-/****f* silcutil/SilcMemoryAPI/silc_smemdup
+/****f* silcutil/silc_smemdup
*
* SYNOPSIS
*
***/
void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
-/****f* silcutil/SilcMemoryAPI/silc_sstrdup
+/****f* silcutil/silc_sfree
+ *
+ * SYNOPSIS
+ *
+ * void silc_scalloc(SilcStack stack, void *ptr);
+ *
+ * DESCRIPTION
+ *
+ * This function can be used to free the `ptr' if `stack' is NULL. This
+ * function does nothing if `stack' is non-NULL. When `stack' is NULL
+ * this function calls silc_free.
+ *
+ ***/
+void silc_sfree(SilcStack stack, void *ptr);
+
+/****f* silcutil/silc_sstrdup
*
* SYNOPSIS
*
* DESCRIPTION
*
* Duplicates the string indicated by `str' and returns the duplicated
- * string. This function allocates unaligned memory. Returns NULL
- * on error.
+ * string. Returns NULL on error.
*
* NOTES
*
projects / runtime.git / blobdiff