* allocation by various routines. Returns the pointer to the stack
* that must be freed with silc_stack_free function when it is not
* needed anymore. If the `stack_size' is zero (0) by default a
- * 1 kilobyte (1024 bytes) stack is allocated. If the `stack_size'
- * is non-zero the byte value must be multiple by 8.
+ * 1 kilobyte (1024 bytes) stack is allocated.
*
* If `parent' is non-NULL the created stack is a child of the `parent'
* stack. All of childs the memory is allocated from the `parent' and
* SYNOPSIS
*
* void *silc_stack_realloc(SilcStack stack, SilcUInt32 old_size,
- * *void *ptr, SilcUInt32 size);
+ * void *ptr, SilcUInt32 size);
*
* DESCRIPTION
*
* Attempts to reallocate memory by changing the size of the `ptr' into
* `size'. This routine works only if the previous allocation to `stack'
* was `ptr'. If there is another memory allocation between allocating
- * `ptr' and this call this routine will return NULL. NULL is also
- * returned if the `size' does not fit into the current stack block.
- * If NULL is returned the old memory remains intact.
+ * `ptr' and this call this routine will return NULL (and silc_errno is
+ * set to SILC_ERR_INVALID_ARGUMENT). NULL is also returned if the `size'
+ * does not fit into the current stack block. If NULL is returned the old
+ * memory remains intact.
*
* NOTES
*
***/
SilcUInt32 silc_stack_get_alignment(SilcStack stack);
+/****f* silcutil/SilcStackAPI/silc_stack_purge
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_stack_purge(SilcStack stack);
+ *
+ * DESCRIPTION
+ *
+ * Purges the `stack' from extra unused memory. This purges only `stack'
+ * and not its parent if `stack' is a child. This purges only large
+ * allocations. The 1024, 2048, 4096 and 8192 bytes of allocations remain.
+ * Call this multiple times to purge even more. Returns FALSE when there
+ * is no more to purge. This does not purge memory blocks that currently
+ * have allocations. No memory allocations from the stack are lost, so
+ * this is always safe to call.
+ *
+ ***/
+SilcBool silc_stack_purge(SilcStack stack);
+
#include "silcstack_i.h"
#endif /* SILCSTACK_H */