pfm_$cleanup(3)

NAME

pfm_$cleanup − establish a cleanup handler

SYNOPSIS (C)

C Syntax

#include <idl/c/base.h>
#include <ppfm.h>

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

Pascal Syntax

%include ’/sys/ins/base.ins.pas’;
%include ’/sys/ins/ppfm.ins.pas’;

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

Remarks

To view this manual entry via the man(1) command, use the function name shown above without the “$” character.

DESCRIPTION

pfm_$cleanup establishes a cleanup handler that is executed when a fault occurs. A cleanup handler is a piece of code executed before a program exits when a signal is received by the process. The cleanup 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 cleanup handler in a program. Multiple cleanup handlers are executed consecutively on a last-in/first-out basis, starting with the most recently established cleanup handler and ending with the first cleanup handler.

On Apollo systems, a default cleanup handler is established at program invocation. The default cleanup handler is always called last, just before a program exits, and releases any system resources still held before returning control to the process that invoked the program.

On other systems, there is no default cleanup handler.

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

See the reference description of pfm_$init for a list of the C signals that the PFM package intercepts.

cleanup_record Is 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 cleanup handler entry point.

NOTE

The pfm_$cleanup call implicitly performs a pfm_$inhibit. Cleanup handler code hence 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 cleanup code:

• The program can call pfm_$signal to start the next cleanup handler with a fault signal you specify.

• The program can call pgm_$exit to start the next cleanup handler with a status of status_$ok.

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

• The program can re-establish the cleanup handler by calling >I pfm_$reset_cleanup (which implicitly performs a pfm_$enable) before proceeding.

Museum

Related Articles