| Function silc_stack_push
 
 SYNOPSIS
 
    SilcUInt32 silc_stack_push(SilcStack stack, SilcStackFrame *frame);
DESCRIPTION
    Push the top of the stack down which becomes the new top of the stack.
    For every silc_stack_push call there must be silc_stack_pop call.  All
    allocations between these two calls will be done from the top of the
    stack and all allocated memory is freed after the next silc_stack_pop
    is called.  This returns so called stack pointer for the new stack
    frame, which the caller may use to check that all calls to
    silc_stack_pop has been made.  This call may do a small memory
    allocation in some cases, but usually it does not allocate any memory.
    If this returns zero (0) the system is out of memory.
    If the `frame' is non-NULL then that SilcStackFrame is used as
    stack frame.  Usually `frame' is set to NULL by user.  Statically
    allocated SilcStackFrame should be used when using silc_stack_push
    in recursive function and the recursion may become deep.  In this
    case using statically allocated SilcStackFrame is recommended since
    it assures that frames never run out and silc_stack_push never
    allocates any memory.  If your routine is not recursive then
    setting `frame' to NULL is recommended, unless performance is
    critical.
    This function is used when a routine is doing frequent allocations
    from the stack.  If the stack is not pushed and later popped all
    allocations are made from the stack and the stack eventually runs out
    (it gets enlarged by normal memory allocation).  By pushing and then
    later popping the frequent allocations does not consume the stack.
    If `stack' is NULL this call has no effect.
EXAMPLE
    All memory allocations in silc_foo_parse_packet will be done in
    a fresh stack frame and that data is freed after the parsing is
    completed.
    silc_stack_push(stack, NULL);
    silc_foo_parse_packet(packet, stack);
    silc_stack_pop(stack);
    Another example with recursion and using statically allocated
    SilcStackFrame.  After popping the statically allocated frame can
    be reused if necessary.
    void silc_foo_this_function(SilcStack stack)
    {
      SilcStackFrame frame;
      ...
      silc_stack_push(stack, &frame);
      silc_foo_this_function(stack);   // Call recursively
      silc_stack_pop(stack);
      ...
    }
 
 
 
 |