pfm_establish_fault_handler()

PFM_$ESTABLISH_FAULT_HANDLER      Domain/OS       PFM_$ESTABLISH_FAULT_HANDLER


NAME
     pfm_$establish_fault_handler - establish a fault handler

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/pfm.h>

     pfm_$fh_handle_t pfm_$establish_fault_handler(
          int &target_status,
          pfm_$fh_opt_set_t &fh_options,
          pfm_$fault_func_p_t &function_ptr,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/pfm.ins.pas';

     function pfm_$establish_fault_handler(
          in target_status: integer32;
          in fh_options: pfm_$fh_opt_set_t;
          in function_ptr: pfm_$fault_func_p_t;
          out status: status_$t): pfm_$fh_handle_t;

DESCRIPTION
     Pfm_$establish_fault_handler establishes the function at function_ptr as
     a handler for the faults specified by target_status, and returns a handle
     for it.

     target_status
          A value specifying the type of fault the function at function_ptr
          should handle.  Set target_status to pfm_$all_faults to establish a
          handler for all possible faults.  To establish a handler for all
          faults produced by a set of Domain/OS calls, use one of that
          manager's predefined completion status values with the code field
          set to 0.

     fh_options
          This is a small set of options that limit the scope of the fault
          handler.  Specify any combination of the following values:

          pfm_$fh_multi_level
               Establish a "multilevel" handler for faults encountered at the
               current and all subordinate program levels.

          pfm_$fh_backstop
               Establish a "backstop" handler that is called after all non-
               backstop handlers have been called.

               By default, fault handlers are called consecutively on a last-
               in/first-out basis, starting with the most recently established
               handler and ending with the first fault handler established in
               the current program level.  To establish a default handler in
               Pascal, pass an empty set [] for fh_options; in C, pass 0.

     function_ptr
          The address of a function to establish as a fault handler.

     status
          The completion status.

NOTES
     A fault handler remains in effect until released by passing the returned
     handle to pfm_$release_fault_handler.
Museum
