pfm_cleanup() — Apollo

PFM_$CLEANUP                      Domain/OS                       PFM_$CLEANUP


NAME
     pfm_$cleanup - establish a clean-up handler

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

     status_$t pfm_$cleanup(pfm_$cleanup_rec *cleanup_record)

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

     function pfm_$cleanup(
          out cleanup_record: pfm_$cleanup_rec): status_$t;

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/pfm.ins.ftn'

           integer*4 status, cleanup_record(16)

           status = pfm_$cleanup(cleanup_record)

DESCRIPTION
     Pfm_$cleanup establishes a clean-up handler that is executed when a fault
     occurs.  A clean-up handler is a piece of code executed before a program
     exits when a signal is received by the process.  The clean-up handler
     begins where pfm_$cleanup is called; the pfm_$cleanup call registers an
     entry point with the system where program execution resumes when a fault
     occurs.  When a fault occurs, execution resumes after the most recent
     call to pfm_$cleanup.

     There can be more than one clean-up handler in a program.  Multiple
     clean-up handlers are executed consecutively on a last-in/first-out
     basis, starting with the most recently established handler and ending
     with the first clean-up handler.  The system provides a default clean-up
     handler esablished at program invocation.  The default clean-up handler
     is always called last, just before a program exits, and releases any sys-
     tem resources still held, before returning control to the process that
     invoked the program.

     When called to establish a clean-up handler, pfm_$cleanup returns the
     status pfm_$cleanup_set to indicate the clean-up handler was successfully
     established.  When the clean-up handler is entered in response to a fault
     signal, pfm_$cleanup effectively returns the value of the fault that
     triggered the handler.

     cleanup_record
          A record of the context when pfm_$cleanup is called.  A program
          should treat this as an opaque data structure, and not try to alter
          or copy its contents.  It is needed by pfm_$rls_cleanup and
          pfm_$reset_cleanup to restore the context of the calling process at
          the clean-up handler entry point.

NOTES
     Clean-up handler code runs with asynchronous faults inhibited.  When
     pfm_$cleanup returns something other than pfm_$cleanup_set, indicating
     that a fault has occurred, there are four possible ways to leave the
     clean-up code:

          ⊕  The program can call pfm_$signal to start the next clean-up
             handler with a different fault signal.

          ⊕  The program can call pgm_$exit to start the next clean-up handler
             with the same fault signal.

          ⊕  The program can continue with the code following the clean-up
             handler.  It should generally call pfm_$enable to re-enable asyn-
             chronous faults.  Execution continues from the end of the clean-
             up handler code; it does not resume where the fault signal was
             received.

          ⊕  The program can re-establish the handler by calling
             pfm_$reset_cleanup before proceeding.

SEE ALSO
     fault_$intro, pfm_$error_trap, pfm_$signal.
Museum
