Component balst_objectfileformat [Package balst]

Provide platform-dependent object file format trait definitions. More...

Namespaces
namespace	balst

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • DWARF Information
    • Implementation Note
  • Usage
    • Example 1: Accessing balst::ObjectFileFormat Information at Run Time

Purpose:

Provide platform-dependent object file format trait definitions.

Classes:

balst::ObjectFileFormat

namespace for object file format traits

See also:

Description:

This component defines a set of traits that identify and describe a platform's object file format properties. For example, the balst::ObjectFileFormat::ResolverPolicy trait is ascribed a "value" (i.e., Elf or Xcoff) appropriate for each supported platform. The various stack trace traits are actually types declared in the bdescu_ObjectFileFormat struct. These types are intended to be used in specializing template implementations or to enable function overloading based on the prevalent system's characteristics. #defines are also provided by this component to facilitate conditional compilation depending upon object file formats.

DWARF Information:

DWARF is a format for detailed debugging information. It is not a complete format, but is used within other formats. It is used within ELF on Linux, but not (yet) on Solaris at Bloomberg (currently the ELF format on Solaris still uses STABS). It is used within the Mach-O format (also known as the Dladdr format in this file) used on Darwin. It is also used by the Clang compiler (which uses ELF).

For all these platforms, parsing the DWARF information is necessary for the stack trace to get source file names and line numbers (the ELF format gives source file names, but only in the case of file-scope static functions).

DWARF is implemented for g++ versions earlier than 7.1.0 on Linux.

Implementation Note:

Linux g++ 7.1.0 uses DWARF version 4, while g++ 5.4.0 and before use DWARF version 3. At the moment the required system header, dwarf.h, is not available in the Bloomberg production build chroot environment, so support for dwarf formats is disabled.

DWARF support on Clang is problematic and not currrently implemented, see the long comment in balst_stacktraceresolverimpl_elf.cpp, which explains exactly how it could be implemented when that becomes a priority.

We have not yet investigated implementing DWARF for Dladdr (Darwin).

Usage:

In this section we show the intended usage of this component.

Example 1: Accessing balst::ObjectFileFormat Information at Run Time:

The templated (specialized) typeTest function returns a unique, non-zero value when passed an object of types balst::ObjectFileFormat::{Elf,Xcoff,Windows}, and 0 otherwise.

  template <typename TYPE>
  int typeTest(const TYPE &)
  {
      return 0;
  }

  int typeTest(const balst::ObjectFileFormat::Elf &)
  {
      return 1;
  }

  int typeTest(const balst::ObjectFileFormat::Xcoff &)
  {
      return 2;
  }

  int typeTest(const balst::ObjectFileFormat::Windows &)
  {
      return 3;
  }

  int main() ...

We define an object policy of type balst::ObjectFileFormat::Policy, which will be of type ...Elf, ...Xcoff, or ...Windows appropriate for the platform.

      balst::ObjectFileFormat::Policy policy;

We now test it using typeTest:

      assert(typeTest(policy) > 0);

  #if defined(BALST_OBJECTFILEFORMAT_RESOLVER_ELF)
      assert(1 == typeTest(policy));
  #endif

  #if defined(BALST_OBJECTFILEFORMAT_RESOLVER_XCOFF)
      assert(2 == typeTest(policy));
  #endif

  #if defined(BALST_OBJECTFILEFORMAT_RESOLVER_WINDOWS)
      assert(3 == typeTest(policy));
  #endif
  }