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,
     exc_set_objlist_update_policy, exc_set_obj_store_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);

     void exc_set_objlist_update_policy(int obj_update);

     void exc_set_obj_store_policy( enum __exc_elf_obj_policy
     store_policy);

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:

     * 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 unwinds
       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 an 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 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 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 applications 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 application 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.

     * exc_set_objlist_update_policy(int obj_update). If obj_update is set
       to 1, libexc will handle calls to dlopen(3C), sgidladd(3C),
       sgidlopen_version(3C), or dlclose(3C) and automatically update its
       internal list of objects.  If obj_update is set to 0, libexc will
       update its list every time it needs to find in which object an
       address is defined.  In that case, the performance impact can be
       huge.
       By default obj_update is 1.

     * exc_set_obj_store_policy(enum __exc_elf_obj_policy store_policy).

          * If store_policy is set to EXC_LIBELF_USE_MMAP_EACH, libexc will
            mmap(2) each ELF section seperately and only when needed by
            libexc.

          * If set to EXC_LIBELF_USE_ONE_BIG_MMAP, libexc will mmap the
            entire file at once.

          * If set to EXC_LIBELF_USE_MALLOC_EACH, libexc will use
            malloc(3C) to allocate and read in each ELF section seperately
            and only when needed by libexc.

          * If set to EXC_LIBELF_USE_ONE_BIG_MALLOC, libexc will use malloc
            to allocate the memory space necessary to read in the entire
            file.

       exc_set_obj_store_policy lets the user choose the memory managment
       of the ELF objects, either by using mmap or malloc and by
       restricting the memory usage to the ELF sections or the entire file.
       Mmap'ing a read only file is usually faster but may interfere with
       the heap in the application address space, especially with 32-bit
       applications. The system also performs mapping operations over whole
       pages. Therefore, if the system page size is too big, it may lead to
       memory waste. libexc needs a few and usually small sections of the
       ELF object; thus mmaping or mallocing the entire file can improve
       the performance, but also wastes some memory space.
       By default store_policy is EXC_LIBELF_USE_MMAP_EACH.

EXAMPLES
          cc  main.c -lexc -ldwarf -lelf

SEE ALSO
     mmap(3), libexc(3), malloc(3C), free(3C), dlopen(3C), sgidladd(3C),
     sgidlopen_version(3C), dlclose(3C), dwarf(4)