libexc(3)

NAME
     trace_back_stack, trace_back_stack_and_print, exc_dladdr - Calls stack
     trace library

SYNOPSIS
     #include <libexc.h>

     int trace_back_stack(int trace_count, __uint64_t *addr_array,
                          char **namep_array, int array_size, int name_max);
     int trace_back_stack_and_print(void);
     void exc_dladdr(__uint64_t addr, char *pname, int name_max,
                     __uint64_t *entry_addr);

DESCRIPTION
     The libexc library provides the functionality for user-level call
     stack unwind.

     trace_back_stack is used to unwind the call stack at the time it is
     called.  The trace_count argument sets the number of stack frames to
     be unwound.  If set to zero, the unwind continues up to main or up to
     _nsproc/_fork for child processes.  The addr_array argument is the
     array that contains the addresses of the callers in the stack after
     the unwind is completed.  The namep_array argument contains the names
     of the functions in the stack after the unwind is completed. If this
     argument is set to NULL, it disables procedure name extraction. The
     array_size argument is the size of the addr_array and namep_array
     arrays, and the name_max argument is the size of the procedure name
     strings.

     An example of one correct way to call this and print the values is the
     following:

     void dotrace1(int tracecount, int framecount, int namesize)
     {
         __uint64_t  *c_addrs;
         char *      *p_names;
         char        *procbuf;
         int         numlevels = 0;
         int         i;

         c_addrs = (__uint64_t *)calloc(framecount, sizeof(__uint64_t));
         p_names = (char **)calloc(framecount, sizeof(char *));
         procbuf = (char *)calloc(framecount * namesize, sizeof(char));

         for (i = 0; i < framecount; i++) {
             p_names[i] = procbuf + i * namesize;
         }

         numlevels = trace_back_stack(tracecount, c_addrs, p_names,
                                      framecount, namesize);

         for (i = 0; i < numlevels; i++) {
             printf("[%2d] 0x%llx %s\n", i, c_addrs[i], p_names[i]);
         }
     }


     trace_back_stack_and_print unwinds the call stack (up to main or up to
     _nsproc/_fork for child processes, up to the thread start for a
     pthread) and prints it to the standard output.  First, the pid of the
     process and the number of frames in the stack are printed and then,
     for each frame, the program counter and the function name are printed.

     trace_back_stack_and_print is limited to 100 levels, and each function
     name in trace_back_stack_and_print is limited to 100 characters.
     Excess characters in a name and excess levels are not printed.

     exc_dladdr maps a text address to the procedure that includes it.  The
     addr argument is the address to be mapped.  The pname must point to
     name_max bytes of space for a string to be stored and will contain the
     procedure name upon return, and the name_max argument is the size of
     the procedure name string.  The entry_addr argument will contain the
     procedure entry address upon return.

ENVIRONMENT VARIABLES
     _LIBEXC_CACHE
          Enables dwarf information caching (N32/64 ABIs only).

     _LIBEXC_NO_PROC_NAME
          Disables procedure name extraction (N32/64 ABIs only).

     _LIBEXC_INIT
          Forces some dwarf information loading at the time of the first
          call to the libexc functions (N32/64 ABIs only).  Alternatively,
          a call to exc_init() would have the same effect of forced pre-
          intialization.

NOTES
     Executables complying to the O32 ABI have to be explicitly linked with
     libexc.

DIAGNOSTICS
     Upon successful completion, both functions return the number of call
     stack frames that were unwound.  In the event of failure, a zero value
     is returned.

BUGS
     trace_back_stack_and_print and trace_back_stack both leak malloc'd
     memory.  The amount is closely related to the size of the procedure
     name strings actually found in the traceback.

SEE ALSO
     speedshop(1)

     exception(3C), libexc(3F)