exception(3C)

NAME
     exc_resume, exc_setjmp, find_fde, find_fde_name, exc_unwind,
     exc_unwind_name, exc_set_cache, exc_set_dlopen_policy,
     exc_set_demangle_policy, exc_set_unwind_fpregs_policy,
     exc_set_procanme_policy, exc_set_procentry_policy - Exception handling
     facility

SYNOPSIS
     #include <exception.h>

     #if (defined(_LANGUAGE_C) || defined(_LANGUAGE_C_PLUS_PLUS))

     #if (_MIPS_SIM == _MIPS_SIM_NABI32)

     Dwarf_Fde find_fde(long pc);

     Dwarf_Fde find_fde(Elf32_Addr *pc);

     Dwarf_Fde find_fde_name(Elf32_Addr *pc, char **name);

     #else /* if (_MIPS_SIM == _MIPS_SIM_ABI64) */

     Dwarf_Fde find_fde(Elf64_Addr *pc);

     Dwarf_Fde find_fde_name(Elf64_Addr *pc, char **name);

     #endif

     void exc_unwind(struct sigcontext *scp, Dwarf_Fde fde);

     void exc_unwind_name(struct sigcontext *scp, Dwarf_Fde fde, char
     **name);

     int exc_resume(struct sigcontext *scp);

     void exc_setjmp(struct sigcontext *scp);

     void exc_set_cache(int level);

     void exc_set_dlopen_policy(int do_dlopen);

     void exc_set_demangle_policy(int do_demangle);

     void exc_set_unwind_fpregs_policy(int unwind_fpregs);

     void exc_set_procanme_policy(int save_procname);

     void exc_set_procentry_policy(int save_procentry);

DESCRIPTION
     This version of the exception handling facility is completely
     different from the previous versions.  This version is for the -n32
     and -64 ABIs and extracts information from the .debug_frame section
     instead of the runtime procedure table as in the o32 versions.  The
     functions (exception_dispatcher, find_rpd, set_unhandled_exception and
     unwind) are not supported for -n32 or -64 ABI applications.

     To handle exceptions from UNIX signals and to minimize the cost at
     runtime until an exception is encountered, the loader collects per-
     procedure exception information and frame information so that the
     stack unwinds easily at the point of exception.

     The data structure Dwarf_Fde is specified in the (.debug_frame)
     section.  See the dwarf(4) man page for additional information.

     At runtime the following procedures are provided in libexc.so:

     * find_fde returns the Frame Description Entry(FDE) specified by the
       pc argument, if there is one, otherwise it returns NULL.

     * find_fde_name does the same thing as find_fde but in addition
       returns the name of the procedure through the parameter name.  Use
       free to deallocate the returned strings after they are used.  (See
       the free(3C) man page for details on its use.)

     * exc_unwind takes the sigcontext scp argument and virtually unwind by
       changing the fields to reflect the next frame on the stack.  A
       sigreturn call can be called with this scp upon return and returns
       to the frame unwind set up.  The fde argument is used as the Frame
       Description Entry argument.  If it is NULL, exc_unwind calls
       find_fde on scp->sc_pc to get it.  If exc_unwind is unable to unwind
       the stack, it sets the sc_pc field of the scp parameter to 1,
       indicating invalid address.

       An sc_pc value of 0, 1, 2, or 3 (not just 1) should be understood to
       mean that the stack is fully unwound (whether due to error or just
       because the unwind is finished).

     * exc_unwind_name does the same thing as exc_unwind but in addition
       returns the name of the procedure of the current sigcontext through
       the parameter name.  Use free to deallocate the returned strings
       after they are used.  (See the free(3C) man page for details on its
       use.)  If 0 is passed as the parameter name then the parameter is
       ignored.

     * exc_setjmp is like setjmp, except that it saves V0 and also sets a
       special magic number so that exc_resume can tell which degree of
       restoration is required.

     * exc_resume is like longjmp, except that it restores the v0 that
       exc_setjmp saved and performs one of the three different degress of
       restoration, according to the magic number in the sigcontext.

     * exc_set_cache(int level). If level is set to 0, libexc does not
       cache any of the data found while unwinding. A level of 1 saves some
       of data used to unwind depending on a PC hash key. The memory usage
       should be constant. If level is set to 2, libexc caches everything
       for a fast retrieval. The memory can grow depending on the number of
       elements traversed during the unwinding. By default, level is 0.

     * exc_set_dlopen_policy(int do_dlopen). If do_dlopen is set to 1,
       libexc saves the dlopen handle of each of the DSOs touched during
       the unwind. If do_dlopen is set to 0, dlopen is not called. For an
       application doing call stack unwinding from inside the application,
       the dlopen handle is not necessary. do_dlopen can be set to 0 to
       save some time. If, for any reason, the dlopen handle is requested,
       unpredictible results can happen. By default, do_dlopen is 1.

     * exc_set_demangle_policy(int do_demangle). If do_demangle is set to
       1, libexc calls demangle(3C++) on each symbol name. If set to 0,
       libexc doesn't call demangle(3C++) and returns mangled names for
       C++. For C or Fortran applications, avoiding the demangling can save
       some time. By default, do_demangle is 1.

     * exc_set_unwind_fpregs(int unwind_fpregs). If unwind_fpregs is set to
       1, libexc unwinds the FP (floating point) registers. If set to 0,
       the FP registers are not unwound and they remain exactly as they
       were before the exception was raised. For applications doing call
       stack unwinding, FP registers are not used to retrieve the caller
       address, and unwind_fpregs can be set to 0. For applications doing
       exception handling, it must not be set to 0 or unpredictible results
       happen. By default, unwind_fpregs is 1.

     * exc_set_procname_policy(int save_procname). If save_procname is set
       to 1, libexc saves the function name of each function saved in the
       cache. If set to 0, libexc doesn't look for the function name,
       improving the performance of the unwinding. For applications doing
       exception handling, save_procname should be set to 0 to gain
       performance and save memory. For application doing call stack
       unwinding, saving the function name can be better for performance if
       unwind_name is called. By default save_procname is 1.

     * exc_set_procentry_policy(int save_procentry). If save_procentry is
       set to 1, libexc saves the function entry point of each PC traversed
       during the unwind. If set to 0, libexc does not look for the
       function entry point. The entry point of a function is useful in
       order to find the name of the function. If save_procname is set to
       0, save_procentry can also be set to 0 unless the app is doing later
       calls to exc_dladdr, in which case if the function entry is saved,
       the function name is faster for libexc to find. By default
       save_procentry is 1.

BUGS
     As a result of implementation details, stack traces through signal
     handlers and the libc _sigtramp function work properly but the
     presence of _sigtramp on the stack is not shown.

EXAMPLES
          cc  main.o -lexc -ldwarf -lelf

SEE ALSO
     free(3C), libexc(3), malloc(3C)

     dwarf(4)