X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcmemory.h;h=74974e96309472784dd3616f446cb129648980e4;hb=adf03e69c4e96ffdac88e7cfe9c2b4583166eb6e;hp=7bd7bef6d6dddc5ebe555341ea390b9c3d72195b;hpb=d8a2e1ec2b995b6e9142e687e0ed5907f87f5145;p=runtime.git diff --git a/lib/silcutil/silcmemory.h b/lib/silcutil/silcmemory.h index 7bd7bef6..74974e96 100644 --- a/lib/silcutil/silcmemory.h +++ b/lib/silcutil/silcmemory.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - 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 @@ -17,13 +17,11 @@ */ -/****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. + * Routines for allocating and freeing memory. * ***/ @@ -34,7 +32,7 @@ #ifndef SILC_STACKTRACE -/****f* silcutil/SilcMemoryAPI/silc_malloc +/****f* silcutil/silc_malloc * * SYNOPSIS * @@ -44,12 +42,12 @@ * * Allocates memory of `size' bytes and returns pointer to the allocated * memory area. Free the memory by calling silc_free. Returns NULL on - * error. + * error and sets silc_errno. * ***/ void *silc_malloc(size_t size); -/****f* silcutil/SilcMemoryAPI/silc_calloc +/****f* silcutil/silc_calloc * * SYNOPSIS * @@ -60,12 +58,12 @@ void *silc_malloc(size_t size); * 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. Returns NULL on - * error. + * error and sets silc_errno. * ***/ void *silc_calloc(size_t items, size_t size); -/****f* silcutil/SilcMemoryAPI/silc_realloc +/****f* silcutil/silc_realloc * * SYNOPSIS * @@ -87,7 +85,7 @@ void *silc_calloc(size_t items, size_t size); ***/ void *silc_realloc(void *ptr, size_t size); -/****f* silcutil/SilcMemoryAPI/silc_free +/****f* silcutil/silc_free * * SYNOPSIS * @@ -101,7 +99,7 @@ void *silc_realloc(void *ptr, size_t size); ***/ void silc_free(void *ptr); -/****f* silcutil/SilcMemoryAPI/silc_memdup +/****f* silcutil/silc_memdup * * SYNOPSIS * @@ -118,18 +116,28 @@ void silc_free(void *ptr); ***/ 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); +#else #include "stacktrace.h" #endif /* SILC_STACKTRACE */ /* Following functions that use SilcStack as memory source. */ -/****f* silcutil/SilcMemoryAPI/silc_smalloc +/****f* silcutil/silc_smalloc * * SYNOPSIS * @@ -140,9 +148,7 @@ void *silc_memdup(const void *ptr, size_t size); * 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 * @@ -155,32 +161,7 @@ void *silc_memdup(const void *ptr, size_t size); ***/ 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 * @@ -203,7 +184,7 @@ void *silc_smalloc_ua(SilcStack stack, SilcUInt32 size); ***/ void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size); -/****f* silcutil/SilcMemoryAPI/silc_srealloc +/****f* silcutil/silc_srealloc * * SYNOPSIS * @@ -216,20 +197,13 @@ void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size); * 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. * @@ -237,29 +211,7 @@ void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size); 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 * @@ -285,7 +237,22 @@ void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size, ***/ 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 * @@ -294,8 +261,7 @@ void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size); * 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 *