Unison/NANO: pthread

NAME

pthread_stackinfo - thread stack information

SYNOPSIS

#include <pthread.h>

int pthread_stackinfo( pthread_ttid , stackinfo_t *info );
typedef struct {: void * si_current; /* current stack pointer */; void * si_base; /* stack base */; size_t si_size; /* stack size */; size_t si_used; /* high water mark. */
} stackinfo_t;

DESCRIPTION

pthread_stackinfo() returns the stack information for the thread tid in the pointer info.

si_current is the current value of the stack pointer.

si_base is the address returned from the kalloc() call used to allocate the stack.

si_size is the size of the stack. Usually the size argument to the kalloc() call.

si_used is only valid if the global variable pthreadStackFill was non-zero when the stack was allocated. If pthreadStackFill was non-zero, then si_used gives the high water mark for stack usage.

RETURN VALUES

pthread_stackinfo() returns 0 on success, and an error number if it failed.

ERRORS

ESRCH: tid is not a valid thread.
ENOSPC: The stack has overflowed.

NOTES

The high water mark is not a guarenteed method of checking for stack usage or overflow. Lets look at an example. The user creates a thread with a stack size of 1000 bytes. The following code fragment shows the start of the thread.

THREAD thread(void)
{
        char bigbuffer[20000];
        int error = 0;

        < initialization code >

        if(mr_receive(bigbuffer, 1, 0, 0, 0) == 0)
                error = RECEIVE_ERROR;

        < rest of thread code >
}

Note that bigbuffer overflows the stack, but the corruption will not be noticed as long as no messages are sent bigger that 1000 bytes. However, if the mr_receive() call ever fails, error will corrupt memory, but the high water mark is still valid since it will only check the 1000 bytes it knows about.