Added SILC errno API. Added SilcResult, generic error code and

[silc.git] / lib / silcutil / silcmemory.h

diff --git a/lib/silcutil/silcmemory.h b/lib/silcutil/silcmemory.h
index 65286de3faadd762c08de6dd7059088857fd43db..7dc60062ef1b440c5e4af4f14048b5fe46504546 100644 (file)
--- a/lib/silcutil/silcmemory.h
+++ b/lib/silcutil/silcmemory.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 1999 - 2005 Pekka Riikonen
+  Copyright (C) 1999 - 2007 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
@@ -25,9 +25,6 @@
  * 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.
- *
  ***/
 
 #ifndef SILCMEMORY_H
@@ -46,7 +43,8 @@
  * 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.
  *
  ***/
 void *silc_malloc(size_t size);
@@ -61,7 +59,8 @@ 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.
+ *    also zeroed.  Free the memory by calling silc_free.  Returns NULL on
+ *    error.
  *
  ***/
 void *silc_calloc(size_t items, size_t size);
@@ -119,10 +118,24 @@ void silc_free(void *ptr);
  ***/
 void *silc_memdup(const void *ptr, size_t size);
 
+/****f* silcutil/SilcMemoryAPI/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.
+ *
+ ***/
+char *silc_strdup(const char *str);
+
 #else
 #ifndef SILC_DIST_TOOLKIT
 #error "The stack trace is not supported in this distribution"
-#endif
+#endif /* SILC_DIST_TOOLKIT */
 
 #include "stacktrace.h"
 #endif /* SILC_STACKTRACE */
@@ -141,9 +154,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
  *
@@ -156,31 +167,6 @@ 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
  *
  * SYNOPSIS
@@ -229,37 +215,12 @@ void *silc_scalloc(SilcStack stack, SilcUInt32 items, SilcUInt32 size);
  *    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 `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
  *
  * SYNOPSIS
@@ -286,6 +247,21 @@ void *silc_srealloc_ua(SilcStack stack, SilcUInt32 old_size,
  ***/
 void *silc_smemdup(SilcStack stack, const void *ptr, SilcUInt32 size);
 
+/****f* silcutil/SilcMemoryAPI/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/SilcMemoryAPI/silc_sstrdup
  *
  * SYNOPSIS
@@ -295,8 +271,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
  *