pfm_$cleanup Library Routine

AIX Version 4.3 Communications Technical Reference, Volume 1

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

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.

Implementation Specifics

This Library Routine is part of Network Computing System in Network Support Facilities in Base Operating System (BOS) Runtime.

Related Information

Remote Procedure Call (RPC) Runtime Library (NCS) in AIX Version 4.3 Communications Programming Concepts.