pfm_cleanup(3ncs)
Name
pfm_cleanup − establish a clean-up handler
Syntax
#include <idl/c/base.h>
#include <idl/c/pfm.h>
status_$t pfm_$cleanup(cleanup_record)
pfm_$cleanup_rec *cleanup_record;
Arguments
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.
Description
The pfm_$cleanup routine 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 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 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 established at program invocation. The default clean-up 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.
Diagnostics
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.
This section lists status codes for errors returned by this pfm_$ routine in status.all.
pfm_$bad_rls_order
Attempted to release a clean-up handler out of order.
pfm_$cleanup_not_found
There is no pending clean-up handler.
pfm_$cleanup_set A clean-up handler was established successfully.
pfm_$cleanup_set_signalled
Attempted to use pfm_$cleanup_set as a signal.
pfm_$invalid_cleanup_rec
Passed an invalid clean-up record to a routine.
pfm_$no_space Cannot allocate storage for a clean-up handler.
Note
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 reenable asynchronous 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 reestablish the handler by calling pfm_$reset_cleanup before proceeding.
Files
/usr/include/idl/c/base.h
/usr/include/idl/base.idl
/usr/include/idl/c/pfm.h