Working With Signals

Oracle^® Solaris Studio 12.4: Debugging a Program With dbx

Document Information

Using This Documentation

Product Documentation Library

Feedback

Chapter 1 Getting Started With dbx

Compiling Your Code for Debugging

Starting dbx or dbxtool and Loading Your Program

Running Your Program in dbx

Debugging Your Program With dbx

Examining a Core File

Setting Breakpoints

Stepping Through Your Program

Looking at the Call Stack

Examining Variables

Finding Memory Access Problems and Memory Leaks

Quitting dbx

Accessing dbx Online Help

Chapter 2 Starting dbx

Starting a Debugging Session

Debugging a Core File

Debugging a Core File in the Same Operating Environment

If Your Core File Is Truncated

Debugging a Mismatched Core File

To Eliminate Shared Library Problems and Debug a Mismatched Core File

Using the Process ID

dbx Startup Sequence

Setting Startup Properties

Mapping the Compile-Time Directory to the Debug-Time Directory

Setting dbx Environment Variables

Creating Your Own dbx Commands

Compiling a Program for Debugging

Compiling With the g Option

Using a Separate Debug File

How to Create a Separate Debug File

Ancillary Files (Oracle Solaris Only)

Debugging Optimized Code

Parameters and Variables

Inlined Functions

Code Compiled Without the -g Option

Shared Libraries Require the -g Option for Full dbx Support

Completely Stripped Programs

Quitting Debugging

Stopping a Process Execution

Detaching a Process From dbx

Killing a Program Without Terminating the Session

Saving and Restoring a Debugging Run

Using the save Command

Saving a Series of Debugging Runs as Checkpoints

Restoring a Saved Run

Saving and Restoring Using replay

Chapter 3 Customizing dbx

Using the dbx Initialization File

Creating a .dbxrc File

Initialization File Sample

Setting dbxenv Variables

dbxenv Variables and the Korn Shell

Chapter 4 Viewing and Navigating To Code

Navigating To Code

Navigating To a File

Navigating To Functions

Selecting From a List of C++ Ambiguous Function Names

Choosing Among Multiple Occurrences

Printing a Source Listing

Walking the Call Stack to Navigate To Code

Types of Program Locations

Program Scope

Variables That Reflect the Current Scope

Visiting Scope

Components of the Visiting Scope

Changing the Visiting Scope

Qualifying Symbols With Scope Resolution Operators

Backquote Operator

C++ Double-Colon Scope Resolution Operator

Block Local Operator

Linker Names

Locating Symbols

Printing a List of Occurrences of a Symbol

Determining Which Symbol dbx Uses

Scope Resolution Search Path

Relaxing the Scope Lookup Rules

Viewing Variables, Members, Types, and Classes

Looking Up Definitions of Variables, Members, and Functions

Looking Up Definitions of Types and Classes

Debugging Information in Object Files and Executables

Object File Loading

Compiler and Linker Options to Support Debugging

Index DWARF (xs[={yes|no}])

Separate Debug File (z ancillary[=outfile])

Minimizing Debug Information

Listing Debugging Information for Modules

Listing Modules

Finding Source and Object Files

Chapter 5 Controlling Program Execution

Running a Program

Attaching dbx to a Running Process

Detaching dbx From a Process

Stepping Through a Program

Controlling Single Stepping Behavior

Stepping Into a Specific or Last Function

Continuing Execution of a Program

Calling a Function

Call Safety

Using Ctrl+C to Stop a Process

Event Management

Chapter 6 Setting Breakpoints and Traces

Setting Breakpoints

Setting a Breakpoint at a Line of Source Code

Setting a Breakpoint in a Function

Setting Multiple Breakpoints in C++ Programs

Setting Breakpoints in Member Functions of Different Classes

Setting Breakpoints in All Member Functions of a Class

Setting Multiple Breakpoints in Nonmember Functions

Setting Breakpoints in Objects

Setting Data Change Breakpoints (Watchpoints)

Stopping Execution When an Address Is Accessed

Stopping Execution When Variables Change

Stopping Execution on a Condition

Setting Filters on Breakpoints

Qualifying Breakpoints With Conditional Filters

Qualifying Breakpoints With Caller Filters

Filters and Multithreading

Tracing Execution

Setting a Trace

Controlling the Speed of a Trace

Directing Trace Output to a File

Executing dbx Commands at a Line

Setting Breakpoints in Dynamically Loaded Libraries

Listing and Deleting Breakpoints

Listing Breakpoints and Traces

Deleting Specific Breakpoints Using Handler ID Numbers

Enabling and Disabling Breakpoints

Efficiency Considerations

Chapter 7 Using the Call Stack

Finding Your Place on the Stack

Walking the Stack and Returning Home

Moving Up and Down the Stack

Moving Up the Stack

Moving Down the Stack

Moving to a Specific Frame

Popping the Call Stack

Hiding Stack Frames

Displaying and Reading a Stack Trace

Chapter 8 Evaluating and Displaying Data

Evaluating Variables and Expressions

Verifying Which Variable dbx Uses

Variables Outside the Scope of the Current Function

Printing the Value of a Variable, Expression, or Identifier

Printing C++ Pointers

Evaluating Unnamed Arguments in C++ Programs

Dereferencing Pointers

Monitoring Expressions

Stop the Display (Undisplaying)

Assigning a Value to a Variable

Evaluating Arrays

Array Slicing

Array Slicing Syntax for C and C++

Array Slicing Syntax for Fortran

Using Slices

Using Strides

Using Pretty-Printing

Invoking Pretty-Printing

Call-Based Pretty-Printing

Pretty-Printing Function Considerations

Possible Failures

Python Pretty-Print Filters (Oracle Solaris)

Using Python on Oracle Solaris

Python Pretty-Print API Documentation

Chapter 9 Using Runtime Checking

Capabilities of Runtime Checking

When to Use Runtime Checking

Runtime Checking Requirements

Using Runtime Checking

Enabling Memory Use and Memory Leak Checking

Enabling Memory Access Checking

Enabling All Runtime Checking

Disabling Runtime Checking

Running Your Program

Using Access Checking

Understanding the Memory Access Error Report

Memory Access Errors

Using Memory Leak Checking

Detecting Memory Leak Errors

Possible Leaks

Checking for Leaks

Understanding the Memory Leak Report

Generating a Leak Report

Combining Leaks

Fixing Memory Leaks

Using Memory Use Checking

Suppressing Errors

Types of Suppression

Suppression by Scope and Type

Suppression of Last Error

Limiting the Number of Errors Reported

Suppressing Error Examples

Default Suppressions

Using Suppression to Manage Errors

Using Runtime Checking on a Child Process

Using Runtime Checking on an Attached Process

Attached Process on a System Running Oracle Solaris

Attached Process on a System Running Linux

Using Fix and Continue With Runtime Checking

Runtime Checking Application Programming Interface

Using Runtime Checking in Batch Mode

bcheck Syntax

bcheck Examples

Enabling Batch Mode Directly From dbx

Troubleshooting Tips

Runtime Checking Limitations

Performance Improves With More Symbols and Debug Information

SIGSEGV and SIGALTSTACK Signals Are Restricted on x86 Platforms

Performance Improves When Sufficient Patch Area Is Available Within 8 MB of All Existing Code (SPARC Platforms Only).

Runtime Checking Errors

Access Errors

Bad Free (baf) Error

Duplicate Free (duf) Error

Misaligned Free (maf) Error

Misaligned Read (mar) Error

Misaligned Write (maw) Error

Out of Memory (oom) Error

Read From Array Out-of-Bounds (rob) Error

Read From Unallocated Memory (rua) Error

Read From Uninitialized Memory (rui) Error

Write to Array Out-of-Bounds Memory (wob) Error

Write to Read-Only Memory (wro) Error

Write to Unallocated Memory (wua) Error

Memory Leak Errors

Address in Block (aib) Error

Address in Register (air) Error

Memory Leak (mel) Error

Chapter 10 Fixing and Continuing

Using Fix and Continue

How Fix and Continue Operates

Modifying Source Using Fix and Continue

Fixing Your Program

Fixing Your File

Continuing After Fixing

Changing an Executed Function

Changing a Function Not Yet Called

Changing a Function Currently Being Executed

Changing a Function Presently on the Stack

Changing Variables After Fixing

Modifying a Header File

Fixing C++ Template Definitions

Chapter 11 Debugging Multithreaded Applications

Understanding Multithreaded Debugging

Thread Information

Thread and LWP States

Viewing the Context of Another Thread

Viewing the Threads List

Resuming Execution

Understanding Thread Creation Activity

Understanding LWP Information

Chapter 12 Debugging Child Processes

Attaching to Child Processes

Following the exec Function

Following the fork Function

Interacting With Events

Chapter 13 Debugging OpenMP Programs

How Compilers Transform OpenMP Code

dbx Functionality Available for OpenMP Code

Single-Stepping Into a Parallel Region

Printing Variables and Expressions

Printing Region and Thread Information

Serializing the Execution of a Parallel Region

Using Stack Traces

Using the dump Command

Using Events

Synchronization Events

Other Events

Execution Sequence of OpenMP Code

Chapter 14 Working With Signals

Understanding Signal Events

Catching Signals

Changing the Default Signal Lists

Trapping the FPE Signal (Oracle Solaris Only)

Determining Where the Exception Occurred

Determining the Cause of the Exception

Sending a Signal to a Program

Automatically Handling Signals

Chapter 15 Debugging C++ With dbx

Using dbx With C++

Exception Handling in dbx

Commands for Handling Exceptions

Examples of Exception Handling

Debugging With C++ Templates

Template Example

Commands for C++ Templates

whereis Command

whatis Command

stop inclass Command

stop infunction Command

Chapter 16 Debugging Fortran Using dbx

Debugging Fortran

Current Procedure and File

Uppercase Letters

Sample dbx Session

How to Run the Sample dbx Session

Debugging Segmentation Faults

Using dbx to Locate Problems

Locating Exceptions

Tracing Calls

Working With Arrays

Fortran Allocatable Arrays

Showing Intrinsic Functions

Showing Complex Expressions

Showing Interval Expressions

Showing Logical Operators

Viewing Fortran Derived Types

Pointer to Fortran Derived Type

Object Oriented Fortran

Allocatable Scalar Type

Chapter 17 Debugging a Java Application With dbx

Using dbx With Java Code

Capabilities of dbx With Java Code

Limitations of dbx With Java Code

Environment Variables for Java Debugging

Starting to Debug a Java Application

Debugging a Class File

Debugging a JAR File

Debugging a Java Application That Has a Wrapper

Attaching dbx to a Running Java Application

To Attach to a Running Java Process

Debugging a C Application or C++ Application That Embeds a Java Application

Passing Arguments to the JVM Software

Specifying the Location of Your Java Source Files

Specifying the Location of Your C Source Files or C++ Source Files

Specifying a Path for Class Files That Use Custom Class Loaders

Setting Breakpoints on Java Methods

Setting Breakpoints in Native (JNI) Code

Customizing Startup of the JVM Software

Specifying a Path Name for the JVM Software

Passing Run Arguments to the JVM Software

Specifying a Custom Wrapper for Your Java Application

Using a Custom Wrapper That Accepts Command-Line Options

Using a Custom Wrapper That Does Not Accept Command-Line Options

Specifying 64-bit JVM Software

dbx Modes for Debugging Java Code

Switching From Java or JNI Mode to Native Mode

Switching Modes When You Interrupt Execution

Using dbx Commands in Java Mode

Java Expression Evaluation in dbx Commands

Static and Dynamic Information Used by dbx Commands

Commands With Identical Syntax and Functionality in Java Mode and Native Mode

Commands With Different Syntax in Java Mode

Commands Valid Only in Java Mode

Chapter 18 Debugging at the Machine-Instruction Level

Using dbx at the Machine-Instruction Level

Examining the Contents of Memory

Using the examine or x Command

Using Addresses

Using Formats

Using Count

Examples of Using an Address

Using the dis Command

Using the listi Command

Stepping and Tracing at Machine-Instruction Level

Single-Stepping at the Machine-Instruction Level

Tracing at the Machine-Instruction Level

Setting Breakpoints at the Machine-Instruction Level

Setting a Breakpoint at an Address

Using the regs Command

Platform-Specific Registers

SPARC Register Information

x86 Register Information

AMD64 Register Information

Chapter 19 Using dbx With the Korn Shell

ksh-88 Features Not Implemented

Extensions to ksh-88

Renamed Commands

Rebinding of Editing Functions

Chapter 20 Debugging Shared Libraries

Dynamic Linker

Link Map

Startup Sequence and .init Sections

Procedure Linkage Tables

Fix and Continue

Setting Breakpoints in Shared Libraries

Setting a Breakpoint in an Explicitly Loaded Library

Appendix A Modifying a Program State

Impacts of Running a Program Under dbx

Commands That Alter the State of the Program

Appendix B Event Management

Event Handlers

Creating Event Handlers

Manipulating Event Handlers

Using Event Counters

Event Safety

Setting Event Specifications

Breakpoint Event Specifications

in Event Specification

at Event Specification

infile Event Specification

infunction Event Specification

inmember Event Specification

inmethod Event Specification

inclass Event Specification

inobject Event Specification

Data Change Event Specifications

access Event Specification

change Event Specification

cond Event Specification

System Event Specifications

dlopen and dlclose Event Specification

fault Event Specification

lwp_exit Event Specification

sig Event Specification

sysin Event Specification

sysout Event Specification

sysin | sysout Event Specifications

Execution Progress Event Specifications

exit Event Specification

next Event Specification

returns Event Specification

step Event Specification

throw Event Specification

Tracked Thread Event Specifications

omp_barrier Event Specification

omp_taskwait Event Specification

omp_ordered Event Specification

omp_critical Event Specification

omp_atomic Event Specification

omp_flush Event Specification

omp_task Event Specification

omp_master Event Specification

omp_single Event Specification

Other Event Specifications

attach Event Specification

detach Event Specification

lastrites Event Specification

proc_gone Event Specification

prog_new Event Specification

stop Event Specification

sync Event Specification

syncrtld Event Specification

thr_create [thread-ID] Event Specification

thr_exit Event Specification

timer Event Specification

Event Specification Modifiers

-count n, -count infinity Modifier

Parsing and Ambiguity

Using Predefined Variables

Variables Valid for when Command

$handlerid

Variables Valid for when Command and Specific Events

Event Handler Examples

Setting a Breakpoint for Store to an Array Member

Implementing a Simple Trace

Enabling a Handler While Within a Function

Determining the Number of Lines Executed

Determining the Number of Instructions Executed by a Source Line

Enabling a Breakpoint After an Event Occurs

Resetting Application Files for replay

Checking Program Status

Catch Floating-Point Exceptions

Appendix C Macros

Additional Uses of Macro Expansion

Macro Definitions

Compiler and Compiler Options

Tradeoffs in Functionality

Limitations

Skimming Errors

Using the pathmap Command to Improve Skimming

Appendix D Command Reference

collector archive Command

Syntax

collector dbxsample Command

Syntax

collector disable Command

collector enable Command

collector heaptrace Command

Syntax

collector hwprofile Command

Syntax

collector limit Command

Syntax

collector pause Command

collector profile Command

Syntax

collector resume Command

collector sample Command

Syntax

collector show Command

Syntax

collector status Command

collector store Command

Syntax

collector synctrace Command

Syntax

collector tha Command

Syntax

collector version Command

fortran_modules Command

loadobject -dumpelf Command

Syntax

loadobject -exclude Command

Syntax

loadobject -hide Command

Syntax

loadobject -list Command

Syntax

loadobject -load Command

Syntax

loadobject -unload Command

Syntax

loadobject -use Command

omp_serialize Command

Example (SPARC platform)

rtc skippatch Command

Index Numbers and Symbols

Language:

Chapter 14

This chapter describes how to use dbx to work with signals.

This chapter contains the following sections.

Understanding Signal Events
Catching Signals
Sending a Signal to a Program
Automatically Handling Signals