ct_ffdc.h File

Purpose

Provides data types, definitions, and interface prototypes for the First Failure Data Capture (FFDC) C language library interfaces.

Description

This header file must be included by any C and C++ language source code files that make use of the First Failure Data Capture C language interfaces. This file contains the C language prototypes for the First Failure Data Capture interfaces, the symbolic constants used as return codes from these interfaces, and data type definitions needed by First Failure Data Capture C and C++ language clients.

C Language Interface Selection Control

This file provides the compiler definition FC_VERSION. This definition controls which version of the First Failure Data Capture interfaces should be used during compilation of the source code. Currently, only one version of the First Failure Data Capture interfaces are available, and the value of FC_VERSION is set to a default value of 1. Future versions of the First Failure Data Capture interfaces can be used during compilation—when they become available—by setting the value for FC_VERSION on the compilation command line. If this variable is not set during compilation, the value for FC_VERSION reverts to the default value of 1, and the initial version of the FFDC interfaces is used.

Data Types

The fc_eid_t data type defined by this module is used to store a First Failure Data Capture Failure Identifier. This identifier is created by the fc_push_stack and fc_log_error interfaces whenever these interfaces are successful in recording failure information. This identifier contains information in an encoded form to indicate the system on which the record was made, the time when the record was made, and the location of the record. First Failure Data Capture commands such as fcreport and fcstkrpt can be used at a later time to obtain the exact failure report for problem determination efforts.

FFDC Environment Establishment Codes

A First Failure Data Capture client application uses the fc_init interface to specify how the FFDC Environment should be established. The following selections are supported:

FC_LOG: A basic FFDC Environment is established, which permits the application to record failure information to the AIX® Error Log and the BSD System Log. An FFDC Error Stack is not established for use by the application in this case, unless this value is combined with either the FC_STACK_CREAT or the FC_STACK_INHERIT options described below. This selection would be used by applications making use of the fc_log_error interface only.
FC_STACK_CREAT: Creates an FFDC Error Stack Environment if one was not previously created by an ancestor of this process, or inherits the FFDC Error Stack Environment if an ancestor previously established one. The FFDC Error Stack Environment permits the application to record information to the AIX Error Log, the BSD System Log, and the FFDC Error Stack. This selection is used by applications that wish to use the fc_push_stack interface as well as the fc_log_error interface. This selection is not to be combined with the FC_STACK_INHERIT option described next.
FC_STACK_INHERIT: Inherit an FFDC Error Stack Environment only if an ancestor process previously established an FFDC Error Stack Environment. If an ancestor did not establish such an environment, the application does not make use of an FFDC Error Stack, but may still make use of the AIX Error Log and the BSD System Log. Do not combine this selection with the FC_STACK_CREAT option specified previously.

Record Type Definitions

Seven FFDC Event Types are specified in this file. These event types are used to instruct the fc_log_error interface as to the severity of the condition being logged:

FFDC_EMERG: A severe failure has occurred, and the system is in danger of coming offline. This information is required by the system administrator to bring the system back online. The AIX Error Log type equivalent is PEND. The BSD System Log priority equivalent is LOG_EMERG.
FFDC_ERROR: A permanent failure has occurred, and the condition will persist until it is repaired. The system is not in danger of coming offline. The AIX Error Log type equivalent is PERM. The BSD System Log priority equivalent is LOG_ERR.
FFDC_STATE: An event of some significance has occurred, but the event does not constitute a failure condition. The AIX Error Log type equivalent is INFO. The BSD System Log priority equivalent is LOG_NOTICE.
FFDC_PERF: A condition has been noticed which can or will degrade the system's performance below acceptable levels. The system is not in danger of coming offline, but performance may be unacceptably slow, which can result in random failures in system applications, such as timeout conditions. The AIX Error Log type equivalent is PERF. The BSD System Log priority equivalent is LOG_WARNING.
FFDC_TRACE: This entry identifies the name and location of a trace file generated by an application or system component. Such an entry would be made when a trace has been enabled in an application or a component, to indicate where the trace file resides. The AIX Error Log type equivalent is UNKN. The BSD System Log priority equivalent is LOG_INFO.
FFDC_RECOV: A recovery action has been successfully completed by the system in response to an FFDC_EMERG, FFDC_ERROR, or FFDC_PERF condition. Such an entry would be created only after an FFDC_EMERG, FFDC_ERROR, or FFDC_PERF condition was detected, and a recovery action started in response to that condition completed successfully. The AIX Error Log type equivalent is TEMP. The BSD System Log priority equivalent is LOG_DEBUG.
FFDC_DEBUG: A failure condition was detected. Unlike the FFDC_ERROR case, the failure is not a permanent condition, or the system can continue successfully with the condition present. The AIX Error Log type equivalent is UNKN. The BSD System Log priority equivalent is LOG_DEBUG.

Examples

To use this file in a C or C++ language program, add the following line near the beginning of the source code module:

#include <rsct/ct_ffcd.h>

Location

/opt/rsct/include/ct_ffdc.h

/usr/include/rsct/ct_ffdc.h