pfm_$cleanup Library Routine

Purpose

Establishes a cleanup handler.

Syntax

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

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

Description

The pfm_$cleanup routine 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 with a call to the pfm_$cleanup routine. This routine 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 the pfm_$cleanup routine.

There can be more than one cleanup handler in a program. Multiple cleanup handlers are executed consecutively on a last-in-first-out basis (LIFO), starting with the most recently established handler and ending with the first cleanup handler. The system provides a default cleanup handler 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.

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

Note: Cleanup handler code runs with asynchronous faults inhibited. When the pfm_$cleanup routine returns something other than pfm_$cleanup_set status, which indicates that a fault has occurred, there are four possible ways to leave the cleanup code:

The program can call the pfm_$signal routine to start the next cleanup handler with a different fault signal.
The program can call the pfm_$exit routine to start the next cleanup handler with the same fault signal.
The program can continue with the code following the cleanup handler. It should generally call the pfm_$enable routine 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 handler by calling the pfm_$reset_cleanup routine before proceeding.

Parameters

Input

Item	Description
cleanup_record	A record of the context in which the pfm_$cleanup routine 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 the pfm_$cleanup and pfm_$reset_cleanup routines to restore the context of the calling process at the cleanup handler entry point.

Examples

To establish a cleanup handler for a routine, use the following:

fst = pfm_cleanup(crec)

where fst is of type status_$t and crec is of type pfm_$cleanup_crec.