STACK(3)

NAME
stack - procedures for managing stacks in libmagicutils.a

SYNOPSIS
#include magic.h
#include stack.h

Stack *StackNew(sincr)
int sincr;

StackFree(stack)
Stack *stack;

ClientData StackPop(stack)
Stack *stack;

ClientData StackLook(stack)
Stack *stack;

StackPush(arg, stack)
ClientData arg;
Stack *stack;

StackEnum(stack, func, cdata)
Stack *stack;
int (*func)(item, i, cdata)
ClientData item, cdata;
int i;

StackCopy(src, dest, copystr)
Stack *src, **dest;
bool copystr;

bool StackEmpty(stack)
Stack *stack;

ClientData STACKPOP(stack)
Stack *stack;

ClientData STACKLOOK(stack)
Stack *stack;

STACKPUSH(arg, stack)
ClientData arg;
Stack *stack;

DESCRIPTION
These procedures implement a simple stack mechanism, allowing stacks containing an arbitrary number of one-word elements to be created, manipulated, and destroyed.

StackNew creates and returns a new Stack. This stack grows automatically as new items are pushed on it. The number of new elements for which space is added each time the stack grows is specified by sincr. When the stack is through being used, StackFree frees it.

Elements can be pushed on the stack using StackPush. The top of the stack can be viewed without removing it by using StackLook, or removed by StackPop. Both return the top element from the stack, or NULL if the stack is empty. Fast macro versions exist for each of these functions: STACKPUSH, STACKLOOK, and STACKPOP. To test whether stack is empty, one can call StackEmpty, which returns TRUE if the stack is empty, or FALSE if it contains any entries.

StackEnum visits all the elements in stack without popping them. It applies (*func)() to each element. The arguments to (*func)() are item, the stack element being visited, i, its index on the stack (1 for the top of the stack, increasing as one moves down the stack), and the same cdata as was passed to StackEnum. If (*func)() returns a non-zero value, the enumeration of the stack aborts and StackEnum returns 1; otherwise, StackEnum returns 0 after visiting all elements in the stack.

StackCopy is used to make a copy of a stack src. It leaves *dest pointing to the copy. If the parameter copystr is TRUE, then the elements of src are interpreted as pointers to NULL-terminated ASCII strings, which are copied into newly allocated memory before the address of the new string is stored in *dest; otherwise, the elements of src are just copied to *dest.

BUGS
There should be a way of declaring a Stack that pushes or pops more than a single word at a time.

SEE ALSO
magicutils(3)