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 pfm_$reset_cleanup() (which implicitly performs a pfm_$enable()) before proceeding.

Museum

Related Articles