pfm_$intro(3)

NAME

pfm_$intro − fault management

SYNOPSIS (C)

C Syntax

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

Pascal Syntax

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

Remarks

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

DESCRIPTION

pfm_$() calls allow programs to manage signals, faults, and exceptions by establishing cleanup handlers.

NCS software products include a portable subset of the Apollo Domain/OS pfm_$() calls:

pfm_$cleanup() Establish a cleanup handler.

pfm_$enable() Enable asynchronous faults.

pfm_$enable_faults()
Enable asynchronous faults after faults have been inhibited via pfm_$inhibit_faults().

pfm_$inhibit() Inhibit asynchronous faults.

pfm_$inhibit_faults()
Inhibit asynchronous faults but allow time-sliced task switching.

pfm_$init() Initialize the PFM package.

pfm_$reset_cleanup()
Reset a cleanup handler.

pfm_$rls_cleanup()
Release cleanup handlers.

pfm_$signal() Signal the calling process.

Cleanup Handlers

A cleanup handler is a piece of code that allows a program to terminate gracefully when it receives an error. A cleanup handler begins with a pfm_$cleanup() call and usually ends with a call to pfm_$signal() or pgm_$exit(), though it can also simply continue back into the program after the cleanup code.

Include Files in NCS Software

This section describes the include files for the pfm_ interface provided with NCS software.

Version 1.1 of NCK and NIDL, contained a <pfm.h> include file that supports the std_$call() calling convention of Apollo SR9 system software, whereby all parameters of a call are passed by reference rather than by value. For example, a call in C source code to pfm_$reset_cleanup() resembles:

pfm_$reset_cleanup (crec, st)

even though both crec and st are passed by reference to the implementation of pfm_$reset_cleanup(). On Apollo SR9 systems, the C compiler treats these parameters as though each was preceded by the address operator &. On SunOS, ULTRIX, and VMS systems with Version 1.1 of NCK or NIDL, the <pfm.h> file defines macros that convert these parameters to &crec and &st.

In Version 1.5.1 of NCK and NIDL, a new include file for the pfm_$() calls, <ppfm.h>, is provided. This is the include file for the "portable PFM" interface, an interface in the style of ANSI C. When an application invokes a call through this interface, all output parameters must be preceded by an explicit &. For example, a call to pfm_$reset_cleanup() resembles:

pfm_$reset_cleanup (&crec, &st)

since crec and st are output parameters passed by reference. This calling convention is more natural to most C programmers.

The previous include file, <pfm.h>, is still available, providing backward compatibility for programs coded according to the std_$call() convention. However, new programs should include <ppfm.h>.

Include Files in Apollo SR10 Domain/OS Software

In Apollo SR10 system software, the include file <apollo/pfm.h>, defines the pfm_ interface in the style of ANSI C.

Beginning at SR10.2, the file <apollo/ppfm.h>, which includes <apollo/pfm.h> is also provided; /usr/include/ppfm.h is a symbolic link pointing to /usr/include/apollo/ppfm.h.

Thus, the directive

#include <ppfm.h>

can be used both on Apollo SR10.2 systems and on other systems with Version 1.5.1 of NCK or NIDL (including HP-UX Releases 8.0 and 8.05).

The signatures for pfm_$reset_cleanup() and pfm_$rls_cleanup() in the SR10.0 and SR10.1 versions of <apollo/pfm.h> are incorrect. They have been corrected at SR10.2. These corrections may require you to modify an application developed on SR10.0 and SR10.1 Apollo systems in order to compile it on an SR10.2 Apollo system. See the reference descriptions of these calls for details.

Constants

pfm_$init_signal_handlers
A constant used as the flags parameter to pfm_$init(), causing C signals to be intercepted and converted to PFM signals.

Data Types

pfm_$cleanup_rec
An opaque data type for passing process context among cleanup handler calls.

status_$t
A status code. Most NCS calls supply their completion status in this format. The status_$t type is defined as a structure containing a long integer:

struct status_$t {
long all;
}

However, the calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, assign the value of the status code to a union defined as follows:

typedef union {
    struct {
        unsigned fail : 1,
                 subsys : 7,
                 modc : 8;
        short    code;
    } s;
    long all;
} status_u;

where:

all All 32 bits in the status code. If all is equal to status_$ok, the call that supplied the status was successful.

fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module.

subsys This indicates the subsystem that encountered the error.

modc This indicates the module that encountered the error.

code This is a signed number that identifies the type of error that occurred.

Status Codes

pfm_$bad_rls_order
Attempted to release a cleanup handler out of order.

pfm_$cleanup_not_found
There is no pending cleanup handler.

pfm_$cleanup_set
A cleanup handler was established successfully.

pfm_$cleanup_set_signalled
Attempted to use pfm_$cleanup_set as a signal.

pfm_$invalid_cleanup_rec
Passed an invalid cleanup record to a call.

pfm_$no_space
Cannot allocate storage for a cleanup handler.

status_$ok
The call was successful.

Museum

Related Articles