007 2579 006

User Manual: 007-2579-006

Open the PDF directly: View PDF .
Page Count: 398

Download
Open PDF In Browser	View PDF

ProDevTM WorkShop: Debugger User’s
Guide

007–2579–006

CONTRIBUTORS
Written by Jenn Byrnes
Edited by Rick Thompson
Illustrated by Chrystie Danzer
Production by Diane Ciardelli
COPYRIGHT
© 1996, 1999, 2001 Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated
elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic
documentation in any manner, in whole or in part, without the prior written permission of Silicon Graphics, Inc.
LIMITED AND RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in the Rights in Data clause at FAR 52.227-14
and/or in similar or successor clauses in the FAR, or in the DOD, DOE or NASA FAR Supplements. Unpublished rights reserved
under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre Pkwy.,
Mountain View, CA 94043-1351.
TRADEMARKS AND ATTRIBUTIONS
IRIS, IRIX, and Silicon Graphics are registered trademarks and Developer Magic, ProDev, and the Silicon Graphics logo are trademarks
of Silicon Graphics, Inc.
Open Software Foundation, Motif, OSF, OSF/Motif are trademarks of the Open Software Foundation, Inc. PostScript is a trademark of
Adobe Systems, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open
Company Limited. X/Open is a trademark of X/Open Company Ltd. The X device is a trademark of the Open Group.
Cover design by Sarah Bolles, Sarah Bolles Design, and Dany Galgani, SGI Technical Publications.

New Features in This Guide

This revision of the ProDev WorkShop: Debugger User’s Guide supports the 2.9 release
of ProDev WorkShop tools. New features include the following:
• Improved GUI Usability
• MPI Single System Image Debugging support
• More Improvements in 6.5 pthreads support
• F90 Debugging support
• General Fortran Debugging support

007–2579–006

iii

Record of Revision

007–2579–006

Version

Description

004

June 1998
Revised to reflect changes for the ProDev WorkShop 2.7 release.

005

April 1999
Revised to reflect changes for the MIPSpro WorkShop 2.8 release.

005

August 1999
Document released under new online and print format.

006

June 2001
Supports the ProDev WorkShop 2.9 release.

Contents

About This Guide

. . . .

. . .

. . . .

. . xxxi

Related Publications

. xxxii

Obtaining Publications

. xxxii

Conventions

. xxxiii

. xxxiv

Reader Comments

1. WorkShop Debugger Overview
Main Debugger Features

The Debugger Main View Window
About Traps

Viewing Program Data

. .

. . .

. . . .

. .

Integrating the Debugger with Other WorkShop Tools

Accessing the Performance Analyzer from the Main View Window
Accessing the Static Analyzer from the Main View Window
Accessing Editors from the Main View Window

Debugging with Fix+Continue

Debugging with the X/Motif Analyzer

Customizing the Debugger
Additional Information

Accessing Configuration Management Tools
Recompiling from the Main View Window

. . . .

. .

2. Basic Debugger Usage
Getting Started with the Debugger
007–2579–006

. . . .
.

. . .
.

. . . .
.

vii

Contents

Basic Tips and Features

Fortran 90 Code Example and Short Tutorial
C Code Example and Short Tutorial

Options for Controlling Program Execution
Setting Traps

Options for Viewing Variables

Viewing Variables Using the cvd Command Line
Viewing Variables Using Click To Evaluate

Viewing Variables Using the Variable Browser

Viewing Variables Using the Expression View Window
Viewing Variables Using the Array Browser
Subscript Controls Field
How to Change Values

Viewing Variables Using the Structure Browser Window
Searching

Using the Call Stack

Stopping at Functions or Subroutines

Suggestions for Debugging for Serial Execution of Scientific Programs
Step 1: Use lint

Step 3: Check for Uninitialized Variables Being Used in Calculations

Step 4: Find Divisions by Zero and Overflows

Step 2: Check for Out-of-Bounds Array Accesses

Step 5: Perform Core File Analysis

Step 6: Troubleshoot Incorrect Answers

. . . .

. .

3. Selecting Source Files
How to Load Source Files
viii

. .
.

. . . .
.

. . .
.

. . . .
.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Load Directly into the Main View Window

Load from the File Browser Dialog Box

Load from the Open Dialog Box
Path Remapping

. . . .

. .

Case Example for Path Remapping

4. Tutorial: The jello Program
Starting the Debugger

Run the jello Program
Perform a Search

. . .

. . . .

Edit Your Source Code

Setting Traps

Examining Data

. . . .

. .

Exiting the Debugger

5. Setting Traps
Traps Terminology

. . . .

. . .

. . . .

Trap Triggers

Trap Types

Setting Traps

Setting Traps with the Mouse

Setting Traps Using the cvd Command Line

Setting Traps Using the Traps Menu in the Main View Window
Setting Traps in the Trap Manager Window

Setting Single-Process and Multiprocess Traps

Syntaxes

Setting a Trap in filename at line-number

007–2579–006

Contents

Setting a Trap on instruction-address

Setting a Watchpoint on Specified expression

Setting a Watchpoint for address and size

Setting a Trap at signal-name

Setting a Trap on Entry to sys-call-name

Setting a Trap on Exit from sys-call-name

Setting a Trap at time Interval

Setting a Trap on Entry to function

Setting a Trap on Exit from function

Setting a Trap for C++ Exception
Setting a Trap Condition

Setting a Trap Cycle Count

Setting a Trap with the Traps Menu
Moving around the Trap Display Area
Enabling and Disabling Traps

Saving and Reusing Trap Sets

. . . .

. .

Setting Traps by Using Signal Panel and System Call Panel

6. Controlling Program Execution
The Main View Window Control Panel

. .
.

. . .
.

Features of the Main View Window Control Panel
Execution Control Buttons

Controlling Program Execution Using the PC Menu

Execution View

. . . .

. .

7. Viewing Program Data

. . . .

Traceback Through the Call Stack Window
Options for Viewing Variables

. . . .

. . .

. . . .

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Using the cvd Command Line

Using Click to Evaluate

Using the Array Browser

Using the Structure Browser

100

Using the Variable Browser

100

Using the Expression View

100

Evaluating Expressions

101

Expression View Window

101

Assigning Values to Variables

105

Evaluating Expressions in C

105

106

107

C Function Calls

Evaluating Expressions in C++
Limitations

Evaluating Expressions in Fortran
Fortran Variables

Fortran Function Calls

108

. . . .

. .

109

8. Debugging with Fix+Continue
Introduction to Fix + Continue
Fix+Continue Functionality

. .

. . .

. . . .

109

110

Fix+Continue Integration with Debugger Views

How Redefined Code Is Distinguished from Compiled Code
The Fix+Continue Interface

Debugger with Fix+Continue Support

111

Change ID, Build Path, and Other Concepts
Restrictions on Fix+Continue

112

Fix+Continue Tutorial

113

Setting up the Sample Session
007–2579–006

Contents

Redefining a Function: time1 Program
Editing a Function
Changing Code

114

115

117

118

Deleting Changed Code

Changing Code from the Debugger Command Line
Saving Changes

Setting Breakpoints in Redefined Code
Viewing Status

120

121

123

Comparing Original and Redefined Code

Switching between Compiled and Redefined Code
Comparing Function Definitions
Comparing Source Code Files
Ending the Session

124

125

126

. . . .

. .

127

9. Detecting Heap Corruption
Typical Heap Corruption Problems
Finding Heap Corruption Errors

. . . .
.

127

128

129

130

131

. . . .

. .

137

Trapping Heap Errors Using the Malloc Library
Heap Corruption Detection Tutorial

10. Multiple Process Debugging
Using the Multiprocess View Window

. . .

. . . .

138

139

Using Multiprocess View Control Buttons

140

Starting a Multiprocess Session
Viewing Process Status

xii

. . . .

Compiling with the Malloc Library
Setting Environment Variables

. . .

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Multiprocess Traps

140

Viewing Pthreaded Applications

140

Adding and Removing Processes

141

Multiprocess Preferences

141

142

144

Using the Trap Manager to Control Trap Inheritance

146

Bringing up Additional Main View Windows
Debugging a Multiprocess C Program

Launch the Debugger in Multiprocess View
Using Multiprocess View to Control Execution

Debugging a Multiprocess Fortran Program
General Fortran Debugging Hints

Fortran Multiprocess Debugging Session
Debugging Procedure

148

149

150

154

User-Level Continue of Single 6.5 POSIX Pthread

155

Debugging a Pthreaded Program

Scheduling Anomalies
Blocking Anomalies

156

157

How to Continue a Single POSIX 6.5 Pthread
Other Pthread Debugging Hints

Differences between 6.4 and 6.5 Pthreads
Pthread Debugging Session

158

159

. . . .

. .

163

Debugging an MPI Single System Image Application

11. X/Motif Analyzer

. . .

. . . .

Introduction to the X/Motif Analyzer
Examiners Overview
Examiners and Selections

007–2579–006

. . .

. . . .

163

164

xiii

Contents

Inspecting Data

164

165

Restrictions and Limitations

165

X/Motif Analyzer Tutorial

165

Setting up the Sample Session

166

Launching the X/Motif Analyzer

167

Navigating the Widget Structure

167

171

173

Using Additional Features of the Analyzer

176

Ending the Session

180

. . . .

. .

181

Inspecting the Control Flow
Tracing the Execution

Examining Widgets

Setting Callback Breakpoints

12. Customizing the Debugger

. . .

Customizing the Debugger with Scripts
Using a Startup File

. . .

. . . .

181

Implementing User-Defined Buttons

182

Changing X Window System Resources

183

186

. . . .

. .

187

DUMPCORE Environment Variable

Appendix A. Debugger Reference
Main View Window

. .

. . .

. . . .

187

Admin Menu

194

Views Menu

196

Query Menu

197

Source Menu

198

200

201

Display Menu
Perf Menu

xiv

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Traps Menu
PC Menu

203

205

206

Fix+Continue Menu

Show Difference Submenu
View Submenu

207

Preferences Submenu

207

Keyboard Accelerators

209

210

211

212

Help Menu

Some Additional Views
.

Execution View
Multiprocess View

Status of Processes

Multiprocess View Control Buttons

Multiprocess View Administrative Functions
Controlling Preferences
.

212

214

217

Charts Menu

218

Scale Menu

219

Source View
Process Meter

Controlling Multiple Processes
Ada-specific Windows

220

Admin Menu

221

Config Menu

222

Layout Menu

222

223

226

Task View

Display Menu
Exception View

X/Motif Analyzer Windows

007–2579–006

Contents

Global Objects

227

228

Examine Menu

228

Examiner Tabs

229

Return Button

230

233

Event-Handler Breakpoints Examiner

235

Resource-Change Breakpoints Examiner

237

238

Admin Menu

Breakpoints Examiner

Callback Breakpoints Examiner

Timeout-Procedure Breakpoints Examiner
Input-Handler Breakpoints Examiner

239

State-Change Breakpoints Examiner

240

241

243

X-Event Breakpoints Examiner

X-Request Breakpoints Examiner
Trace Examiner

244

246

247

Callback Examiner

249

Window Examiner

250

251

252

Widget Examiner
Tree Examiner

Event Examiner

Graphics Context Examiner
Pixmap Examiner

253

Widget Class Examiner

254

255

Trap Manager Windows
Trap Manager

256

Config Menu

257

Traps Menu

257

258

Display Menu
xvi

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Signal Panel

258

Syscall Panel

260

262

266

Data Examination Windows
Array Browser Window
Spreadsheet Menu
Format Menu

267

Render Menu

268

Color Menu

268

Scale Menu

270

271

273

Examiner Viewer Controls
Examiner Viewer Menu
Call Stack Window

276

278

Expression View Window

278

Config Menu

Display Menu

Config Menu

Display Menu

279

280

281

282

284

Language Pop-up Menu
Format Pop-up Menu
File Browser Window

Structure Browser Window

Using the Structure Browser Overview Window to Navigate
Entering Expressions

Working in the Structure Browser Display Area

284

Structure Browser Display Menu

285

Node Menu

287

Formatting Fields

289

Variable Browser Window

293

007–2579–006

xvii

Contents

Entering Variable Values

Changing Variable Column Widths
Viewing Variable Changes

293

294

Machine-level Debugging Windows

295

The Disassembly View Window

296

297

Similarities with Main View Window
The Disassemble Menu

297

The Config Menu Preferences Dialog

299

The Register View Window

301

302

Changing the Register View Display

303

The Register View Window

The Memory View Window

Viewing a Portion of Memory

305

306

Changing the Contents of a Memory Location
Changing the Memory Display Format

Moving around the Memory View Display Area
Fix+Continue Windows

Fix+Continue Status Window

307

Admin Menu

309

View Menu

309

Fix+Continue Menu

310

Fix+Continue Error Messages Window

311

Admin Menu

312

View Menu

312

Fix+Continue Build Environment Window
Changes to Debugger Views
Main View

Command Line Interface
xviii

314

315

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

316

Trap Manager

316

Debugger Command Line

317

331

. . . .

. .

333

Call Stack

Syntax for dbx-style Commands
Blocking Kernel System Calls

Appendix B. Using the Build Manager
Build View Window

Build Process Control Area

. . .

. . . .

333

334

Transcript Area

335

Error List Area

335

Build View Admin Menu

336

Build View Preferences
Build Options

337

338

Build Analyzer Window

339

Build Specification Area

340

341

Build Graph Control Area

342

343

Using Build View

Build Graph Area

Build Analyzer Overview Window
Build Analyzer Menus

344

Admin Menu

344

Build Menu

345

Filter Menu

345

Query Menu

345

. .

347

Index

. . . .

007–2579–006

. . . .

. . .

. . . .

xix

Figures

Figure 1-1

The WorkShop Debugger Main View Window

Figure 2-1

Evaluation Pop-Up Menu

Figure 2-2

Expression View Window

Figure 2-3

Array Browser Window

Figure 2-4

Search Window

Figure 2-5

Call Stack Window

Figure 2-6

Trap Manager Window

Figure 3-1

File Browser Window

Figure 3-2

Open Dialog Box

Figure 3-3

Path Remapping Dialog Box

Figure 4-1

The Main View Window with jello Source Code

Figure 4-2

The jello Window

Figure 4-3

The Search Dialog

Figure 4-4

Search Target Indicators

Figure 4-5

Stop Trap Indicator

Figure 4-6

Trap Manager Window

Figure 4-7

Call Stack at spin Stop Trap

Figure 4-8

Variable Browser at spin

Figure 4-9

Variable Browser after Changes

Figure 4-10

Expression View with Language and Format Menus Displayed

Figure 4-11

Structure Browser Window with jello_conec Structure

Figure 4-12

Structure Browser Window with Next Pointer De-referenced

Figure 4-13

Array Browser Window for shadow Matrix

007–2579–006

xxi

Contents

Figure 4-14

Subscript Controls Panel in Array Browser Window

Figure 5-1

Traps Menu in the Main View Window

Figure 5-2

Typical Trap Icons

Figure 5-3

Trap Manager Config, Traps, and Display Menus

Figure 5-4

Trap Examples

Figure 5-5

Signal Panel and System Call Panel

Figure 6-1

The Main View Window Control Panel

Figure 6-2

Pop-up Menu and Step Dialog

Figure 6-3

Pop-up Menu and Next Dialog

Figure 7-1

Call Stack Window

Figure 7-2

Tracing through Call Stack

Figure 7-3

Expression View with Major Menus Displayed

Figure 7-4

Change Indicator in Expression View

Figure 8-1

Program Results in Execution View

Figure 8-2

Selecting a Function for Redefinition

Figure 8-3

Redefined Function

Figure 8-4

Stopping after Breakpoints in Redefined Code

Figure 8-5

102

104

114

116

117

122

Comparing Compiled and Redefined Function Code

125

Figure 9-1

Heap Corruption Warning Shown in Execution View

133

Figure 9-2

Call Stack at Boundary Overrun Warning

134

Figure 9-3

Main View at Bus Error

135

139

146

154

160

161

Figure 10-1

Multiprocess View

Figure 10-2

Examining Process State Using Multiprocess View

Figure 10-3

Comparing Variable Values from Two Processes

Figure 10-4

Initial MPI start up screen display

Figure 10-5

Reaching the MPI application breakpoint screen display

xxii

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 11-1

First View of the X/Motif Analyzer (Widget Examiner)

Figure 11-2

Widget Hierarchy Displayed by the Tree Examiner

Figure 11-3

Adding a Breakpoint for a Widget

Figure 11-4

Setting Breakpoints for a Widget Class

Figure 11-5

168

170

172

173

Callback Context Displayed by the Callback Examiner

174

Figure 11-6

Window Attributes Displayed by the Window Examiner

176

Figure 11-7

Selecting the Breakpoints Tab from the Overflow Area

178

Figure 11-8

Breakpoint Results Displayed by the Call Stack

Figure 12-1

User-Defined Button Example

179

182

188

193

Figure A-1

Major Areas of the Main View Window

Figure A-2

Show/Hide Annotations Button in the Main View Window

Figure A-3

Perf Menu and Subwindows

Figure A-4

Process Menu

Figure A-5

Source View Window

Figure A-6

Process Meter

Figure A-7

Process Menu

Figure A-8

Task View Window

Figure A-9

Exception View

202

210

215

218

219

221

224

227

229

232

Figure A-10

Launching the X/Motif Analyzer Window

Figure A-11

Examiner Tabs

Figure A-12

Breakpoints Examiner Display in the X/Motif Analyzer Window

Figure A-13

Callback Breakpoints Examiner

Figure A-14

Event-Handler Breakpoints Examiner

Figure A-15

Timeout-Procedure Breakpoints Examiner

Figure A-16

Input-Handler Breakpoints Examiner

Figure A-17

State-Change Breakpoints Examiner

Figure A-18

X-Event Breakpoints Examiner

007–2579–006

234

236

238

239

240

242
xxiii

Contents

Figure A-19

X-Request Breakpoints Examiner

243

Figure A-20

Request Type Selection Dialog

244

Figure A-21

Trace Examiner

245

Figure A-22

Widget Examiner

246

Figure A-23

Tree Examiner

247

Figure A-24

Tree Examiner Window Graphical Buttons

248

Figure A-25

Callback Examiner

250

Figure A-26

Window Examiner

251

Figure A-27

Event Examiner

252

Figure A-28

Graphics Context Examiner

253

Figure A-29

Pixmap Examiner

Figure A-30

254

Widget Class Examiner

255

Figure A-31

Trap Manager Window

256

Figure A-32

Signal Panel

259

Figure A-33

Syscall Panel

261

263

264

Figure A-34

Array Browser with Display Menu Options

Figure A-35

Subscript Controls Area in the Array Browser

Figure A-36

Array Browser Spreadsheet Area

266

Figure A-37

Example of Wrapped Array

267

Figure A-38

Color Exception Portion of Array Browser Window

269

Figure A-39

Array Browser Graphic Modes

270

272

275

Figure A-40

Examiner Viewer with Controls and Menus

Figure A-41

Examiner Viewer Preference Sheet Dialog

Figure A-42

Call Stack

Figure A-43

Expression View

Figure A-44

Expression View Format Popup with Submenus

Figure A-45

File Browser Window

xxiv

277

279

281

282

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure A-46

Structure Browser with Menus Displayed

Figure A-47

Tree and Linked List Arrangements of Structures

Figure A-48

Node Menu

283

286

287

289

Figure A-50

Structure Browser Type Formatting Dialog

291

Figure A-51

Variable Browser with Menus Displayed

294

Figure A-52

Variable Browser Change Indicator

295

Figure A-53

The Disassembly View Window with the Disassembly Menu Displayed

296

Figure A-54

The Disassemble From Address Dialog

298

Figure A-55

The Disassemble Function Dialog

298

Figure A-56

The Disassemble File Dialog

299

Figure A-57

The Disassembly View Preferences Dialog with Display Format Menu

300

Figure A-58

The Register View Window

Figure A-59

The Register View Preferences Dialog

Figure A-60

The Memory View Window with the Mode Submenu Displayed

Figure A-61

Fix+Continue Status Window

Figure A-62

Fix+Continue Status Window Menus

Figure A-63

Fix+Continue Build Environment Window

Figure A-64

Debugger Main View Window

Figure A-65

Command Line Interface with Redefined Function

Figure A-66

Call Stack

Figure A-67

Trap Manager Window with Redefined Function

Figure B-1

Build Process Control Area in Build View Window

Figure B-2

Build View Window with Typical Data

Figure B-3

Build View Preferences Dialog

Figure B-4

Build Options Dialog

Figure B-5

Build Analyzer Window

007–2579–006

Figure A-49

Structure Browser Preferences Dialog

302

304

305

308

309

313

315

316

317

334

335

337

338

340
xxv

Contents

Figure B-6

Build Graph Icons

Figure B-7

Build Graph Control Area

Figure B-8

xxvi

342

343

Build Analyzer Overview Window with Build Analyzer Graph

344

007–2579–006

Tables

Table 7-1

Valid C Operations

Table 7-2

Valid Fortran Operations

Table A-1

Fix+Continue Keyboard Accelerators

007–2579–006

105

107

209

xxvii

Examples

Example 2-1

Fortran 90 Example

Example 2-2

C Code Example

007–2579–006

xxix

About This Guide

This publication documents the ProDev WorkShop Debugger, released with the 2.9
version of ProDev WorkShop tools running on IRIX systems.
The Debugger is a source-level debugging tool that allows you to see program data,
monitor program execution, and fix code for Ada, C, C++, Fortran 77, and Fortran 90.
This manual contains the following chapters:
• Chapter 1, "WorkShop Debugger Overview", page 1, gives you an introductory
functional overview of the ProDev WorkShop Debugger.
• Chapter 2, "Basic Debugger Usage", page 11, outlines principles and procedures of
the debugging process and how to approach them using the WorkShop Debugger.
• Chapter 3, "Selecting Source Files", page 39, describes how to manage source files.
• Chapter 4, "Tutorial: The jello Program", page 47, presents a short Debugger
tutorial based on demonstration programs provided with your WorkShop tools.
• Chapter 5, "Setting Traps", page 71, describes how to set various types of traps.
• Chapter 6, "Controlling Program Execution", page 89, describes methods for
controlling process execution.
• Chapter 7, "Viewing Program Data", page 95, explains how to examine Debugger
data.
• Chapter 8, "Debugging with Fix+Continue", page 109, presents a short tutorial
using Fix and Continue.
• Chapter 9, "Detecting Heap Corruption", page 127, describes heap corruption
problems and how to detect them.
• Chapter 10, "Multiple Process Debugging", page 137, describes debugging
multiprocess programs.
• Chapter 11, "X/Motif Analyzer", page 163, presents a short tutorial using the
X/Motif Analyzer.
• Chapter 12, "Customizing the Debugger", page 181, gives you tips on how you can
customize the Debugger to the requirements of your working environment.

007–2579–006

xxxi

About This Guide

• Appendix A, "Debugger Reference", page 187, describes all of the Debugger
windows, menus, and other features in detail.
• Appendix B, "Using the Build Manager", page 333, describes the use of the Build
Manager.

Related Publications
The following documents contain additional information that may be helpful:
• C++ Language System Library
• C++ Language System Overview
• C++ Language System Release 3.0.1 Product Reference Manual
• C++ Programmer’s Guide
• ProDev WorkShop: Performance Analyzer User’s Guide
• Developer Magic: ProDev WorkShop Overview
• Developer Magic: Static Analyzer User’s Guide
• Fortran 77 Language Reference Manual
• dbx User’s Guide

Obtaining Publications
Silicon Graphics maintains publications information at the following web site:
http://techpubs.sgi.com/library

This library contains information that allows you to browse documents online, order
documents, and send feedback to Silicon Graphics.
To order a printed Silicon Graphics document, call 1–800–627–9307.
Customers outside of the United States and Canada should contact their local service
organization for ordering and documentation information.

xxxii

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Conventions
The following conventions are used throughout this document:
Convention

Meaning

command

This fixed-space font denotes literal items such as
commands, files, routines, path names, signals,
messages, and programming language structures.

manpage(x)

Man page section identifiers appear in parentheses after
man page names. The following list describes the
identifiers:
1

User commands

User commands ported from BSD

System calls

Library routines, macros, and opdefs

Devices (special files)

Protocols

File formats

Miscellaneous topics

DWB-related information

Administrator commands

Some internal routines (for example, the
_assign_asgcmd_info() routine) do not have man
pages associated with them.

007–2579–006

variable

Italic typeface denotes variable entries and words or
concepts being defined.

user input

This bold, fixed-space font denotes literal items that the
user enters in interactive sessions. Output is shown in
nonbold, fixed-space font.

[]

Brackets enclose optional portions of a command or
directive line.

...

Ellipses indicate that a preceding element can be
repeated.

xxxiii

About This Guide

Reader Comments
If you have comments about the technical accuracy, content, or organization of this
document, please tell us. Be sure to include the title and part number of the
document with your comments. (Online, the document number is located in the
frontmatter of the manual. In printed manuals, the document number is located at
the bottom of each page.)
You can contact us in any of the following ways:
• Send electronic mail to the following address:
techpubs@sgi.com

• Send a facsimile to the attention of “Technical Publications” at fax number
+1 650 932 0801.
• Use the Feedback option on the Technical Publications Library World Wide Web
page:
http://techpubs.sgi.com

• Call the Technical Publications Group, through the Technical Assistance Center,
using one of the following numbers:
For Silicon Graphics IRIX based operating systems: +1 800 800 4SGI
For UNICOS or UNICOS/mk based operating systems or CRAY Origin2000
systems: +1 800 950 2729 (toll free from the United States and Canada) or
+1 651 683 5600
• Send mail to the following address:
Technical Publications
Silicon Graphics, Inc.
1600 Amphitheatre Pkwy.
Mountain View, California 94043–1351
We value your comments and will respond to them promptly.

xxxiv

007–2579–006

Chapter 1

WorkShop Debugger Overview

The Silicon Graphics ProDev WorkShop Debugger is a UNIX source-level debugging
tool for Silicon Graphics MIPS systems. It displays program data and execution status
in real time. This tool can be used to debug Ada, C, C++, FORTRAN 77, and Fortran
90.
Note: Currently, the Debugger does not accommodate Fortran 90 derived type arrays
with multiple word elements in the Array Browser. It does accommodate Fortran 90
array syntax.
For an introductory tutorial to the principles of debugging, particularly with the
WorkShop Debugger, see Chapter 2, "Basic Debugger Usage", page 11.
This chapter presents an overview of the WorkShop Debugger and is divided into the
following sections:
• "Main Debugger Features", page 1
• "Debugging with Fix+Continue", page 8
• "Debugging with the X/Motif Analyzer", page 8
• "Customizing the Debugger", page 9

Main Debugger Features
The following sections outline the primary features and functions of the WorkShop
Debugger and include references to comprehensive information found throughout
this manual:
• "The Debugger Main View Window", page 2
• "About Traps", page 3
• "Viewing Program Data", page 4
• "Integrating the Debugger with Other WorkShop Tools", page 5

007–2579–006

1: WorkShop Debugger Overview

The Debugger Main View Window
When you start the Debugger with an executable file, the Main View window
displays, loaded with source code, ready to execute your program with your specified
arguments. Most of your debugging work takes place in the Main View window,
which includes the following:
• A menu bar for performing debugger functions.
• A control panel for specifying and controlling program execution.
• A source code display area which displays the code for the program you are
debugging.
• A source filename field which tells gives you the path to the file displayed in the
source code display area.
• A status area for viewing the current status of the program.
• The Debugger command line in which to enter debugging commands (see
"Debugger Command Line", page 317, for command syntax).
The major areas of the Main View window are shown in Figure 1-1, page 3.
Note: For a comprehensive description of the Main View window, see "Main View
Window", page 187.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Menu bar
Control panel

Status area
Source code
display area

Annotation
column

Source filename
Debugger
command line

Figure 1-1 The WorkShop Debugger Main View Window

About Traps
Part of the debugging process requires that you inspect data at various points during
program execution. A trap is a mechanism for gathering this data. Traps are also
referred to as breakpoints, watchpoints, samples, signals, and system calls. There are
two categories of traps:
• A stop trap halts a process so that you can manually examine data.
• A sample trap collects specific performance data without stopping.
007–2579–006

1: WorkShop Debugger Overview

The Debugger lets you set traps at the following points:
• At a line in a file (a breakpoint). These are the most commonly used stop traps.
You can set them by clicking in the annotation column to the left of an executable
statement in the source code display panel. (See the annotation column in Figure
1-1.)
• At an instruction address.
• On entry to or exit from a function.
• When a signal is received (a signal trap).
• When a system call is made, at either the entry or exit point (a system call).
• When a given variable or address is written to, read from, or executed (a
watchpoint).
• At set time intervals (a pollpoint).
For more information on traps, refer to Chapter 5, "Setting Traps", page 71.

Viewing Program Data
When you stop a process, the Views menu at the Main View window menu bar
provides several options for viewing your data. These Views menu options allow you
to inspect the following types of data:
• Call Stack
This option allows you to inspect the call stack at the breakpoints.
• Expression View
This option allows you to inspect the value of specified expressions.
• Variable Browser
This option allows you to inspect the values, types, or addresses of variables.
• Structure Browser
This option allows you to inspect data structures.
• Multiprocess View

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

This option allows you to inspect the values of multiple and / or pthreaded
processes.
• Array Browser
This option allows you to inspect the values of an array variable.
• Memory View
This option allows you to inspect the values in specified memory locations.
• Register View
This option allows you to inspect registers.
• Disassembly View
This option allows you to inspect the disassembled code.

Integrating the Debugger with Other WorkShop Tools
ProDev WorkShop tools are designed so that you can move easily between them in a
work session.
Accessing the Performance Analyzer from the Main View Window

You can run the Performance Analyzer from the Main View window as follows:
Note: If you are in the middle of a run, you must first terminate it.
1. Select the following from the menu bar:
Perf
Select Task
Task in List
2. Click on the Run button in the Control Panel.
The executable is run.
3. Select the following from the menu bar:

007–2579–006

1: WorkShop Debugger Overview

Perf
Examine Results
The Performance Analyzer window will display your results. For more
information on the Performance Analyzer, see the ProDev WorkShop: Performance
Analyzer User’s Guide.
Accessing the Static Analyzer from the Main View Window

The Static Analyzer displays information that makes it easier to determine where to
set traps in your source code. To launch the Static Analyzer, select the following from
the menu bar:
Admin
Launch Tool
Static Analyzer
For more information on the Static Analyzer, see the Developer Magic: Static Analyzer
User’s Guide.
Accessing Editors from the Main View Window

Once you have isolated your code problem with the WorkShop tools, you will want
to correct and recompile your source. WorkShop offers several ways to do this:
1. You can select the following from the Source Menu to make code changes in the
source pane of the Main View window:
a.

Select Source > Make Editable. Make your changes accordingly. (Make
Editable toggles with Make Read Only.)

Select Source > Save to save your changes.

Select Source > Recompile to recompile your changed code.

2. You can invoke an editor from the Views menu that is a separate window in
which to edit your code:
Views
Source View
Note: You must select Make Editable from the File menu at this point to proceed.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

3. You can call up a fork editor window to launch your own editor as follows (first
path):
Source
Fork Editor
4. You can call up a fork editor window to launch your own editor as follows
(second path):
Views
Source View
Then, from the Source View window select the following:
File
Fork Editor
Accessing Configuration Management Tools

If you use ClearCase (a Silicon Graphics product), RCS, or SCCS for configuration
management, you can integrate the tool into the WorkShop environment by entering
the following command:
cvconfig [clearcase | rcs | sccs]

This will allow you to use Versioning source control (from the Source menu) to check
files in and out.
Recompiling from the Main View Window

You can recompile your code from the Build View window, accessible from the menu
bar as follows:
Source
Recompile
For more on the Build View window, see "Build View Window", page 333.
To examine build dependencies for your code, launch the Build Analyzer from the
menu bar as follows:

007–2579–006

1: WorkShop Debugger Overview

Admin
Launch Tool
Build Analyzer
For more on the Build Analyzer window, see "Build Analyzer Window", page 339.
For general information on the Build Manager tools, see Appendix B, "Using the
Build Manager", page 333.

Debugging with Fix+Continue
Fix+Continue gives you the ability to make changes to a program written in C or C++
without having to recompile and link the entire program before continuing to debug
the code. With Fix+Continue, you can edit a function, parse the new functions, and
continue execution of the program being debugged. Fix+Continue commands may be
issued from the Fix+Continue window, which you launch from the Fix+Continue
item on the Main View menu bar.
You can also issue Fix+Continue commands from the Debugger’s command line.
See Chapter 8, "Debugging with Fix+Continue", page 109, for a comprehensive
description of the theory and operation of Fix+Continue, including a short tutorial.

Debugging with the X/Motif Analyzer
The X/Motif Analyzer provides specific debugging support for X/Motif applications.
The X/Motif analyzer is integrated with the Debugger. You issue X/Motif analyzer
commands graphically from the X/Motif analyzer subwindow of the Debugger Main
View. Select the following from the Main View window to access this subwindow:
Views
X/Motif Analyzer
See Chapter 11, "X/Motif Analyzer", page 163 for a comprehensive description of the
theory and operation of the X/Motif Analyzer, including a short tutorial.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Customizing the Debugger
WorkShop provides you with a number of ways that you can customize your
Debugger as best suited to the needs of your development environment.
See Chapter 12, "Customizing the Debugger", page 181, for more tips on customizing
the Debugger to your specific needs.

Additional Information
In addition to this manual and the manuals listed in "About This Guide," page 7, you
should consult the following sources regarding the WorkShop Debugger:
• The WorkShop 2.9 Release Notes are installed on any system running WorkShop 2.9.
These notes provide the following information:
– Installation instructions
– Changes and additions since the last release
– Bug fixes
– Known problems and their workarounds
There are two ways to view the release notes:
– Enter the following command to view the relnotes as simple text:
% relnotes WorkShop

See the relnotes(1) man page for additional information.
– Enter the following command to view the relnotes through the graphical
release notes viewer:
% grelnotes WorkShop

See the grelnotes(1) man page for additional information.
• The online Help menu includes a FAQ option. Consult this for a list of frequently
asked questions and operating tips.

007–2579–006

Chapter 2

Basic Debugger Usage

The WorkShop Debugger can be used with the following compilers: C, C++, Ada,
FORTRAN 77, and Fortran 90.
This chapter includes information regarding principles and procedures of the
debugging process and how these are to be approached with the WorkShop Debugger.

Getting Started with the Debugger
Before starting a Debugger session from a remote workstation, you must first enter
the following from a window:
xhost + machine_name
Where machine_name is the name or IP address of the machine where the program
that you would like to debug will be run.
On the machine where your program will be running, enter the following:
echo $DISPLAY

The machine_name of your workstation should appear, followed by :0.0. If it does
not, enter the following on the machine where your program will run (if you are
using the csh or tcsh shells):
setenv DISPLAY machine_name:0.0

For other shells, see their respective man pages.

Basic Tips and Features
Note: You can find short Debugger tutorials in "Fortran 90 Code Example and Short
Tutorial", page 13 and "C Code Example and Short Tutorial", page 15 for Fortran 90
and C, respectively.
See also Appendix A, "Debugger Reference", page 187 for a comprehensive
description of Debugger functions.

007–2579–006

2: Basic Debugger Usage

To provide debugging information to the Debugger, compile your program with the
-g option (this disables optimization and produces information for symbolic
debugging).
To begin a Debugger session enter:
%cvd executable &

The Debugger Main View window will automatically appear along with an icon for
the Execution View window.
If your program requires data to be read from a file named input, for example, then
type the following in the command (cvd) pane of the Main View window:
cvd> run < input

(See Figure 1-1, page 3.)
The Execution View window receives all the output from running your program that
would normally go directly to your screen. The Main View window controls your
Debugger session, displaying your source code in its center pane. If you want to see
the line numbers for your program, select the following from the Main View window
menu bar:
Display
Show Line Numbers
Context sensitive help is enabled by default. This will pop-up a help phrase or
statement for some menu items, data entry fields, and buttons. It can be enabled and
disabled by selecting the following from the Main View window menu bar:
Display
Show Tooltips / Hide Tooltips
At the bottom of the Main View window there is a window with the cvd> prompt
from which you can enter all dbx commands to the Debugger.
The Debugger allows you to run your program and stop at selected places so you can
view current values of program variables to help you find bugs in your program. To
stop at a selected statement in your program, you may either set a breakpoint (also
called a stop trap) at the desired statement or set a breakpoint prior to the desired
statement and then use either the Step or Next buttons to reach the desired stopping
point. The statement where your program has stopped is indicated in green. A
statement highlighted in red indicates that a breakpoint has been set on this line.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

When the Debugger causes your program to stop at a breakpoint that you have set,
the executable statement immediately prior to the breakpoint has been executed, and
the executable statement on which the breakpoint has been set has yet to be executed.
Note: Programs featured in this chapter are located in the following directory:
/usr/demos/WorkShop/getstarted.

Fortran 90 Code Example and Short Tutorial
Use the Fortran 90 files prog.f and dot.f in
/usr/demos/WorkShop/getstarted to demonstrate the Debugger features in the
following tutorial.
Example 2-1 Fortran 90 Example

• The Fortran 90 code in the file prog.f is as follows:
program prog
parameter ( n=3 )
double precision A(n,n), x(n), y(,) sum xydot

007–2579–006

initialize arrays
x = 2.0d0
do i = 1, n
y(i) = i
do j = 1, n
A(i,j) = i*j - i
enddo
enddo

compute the dot product of x and y
call dot(x,y,n,xydot)
print *, ’dot product of x & y = ’, xydot

compute y = Ax
do i = 1, n
sum = 0.0
do j = 1, n
sum = sum + A(i,j)*x(j)
enddo
y(i) = sum
13

2: Basic Debugger Usage

enddo
print *, ’y = ’, y
stop
end

• It includes subroutine dot in file dot.f, as follows:
subroutine dot(a,b,m,answer)
double precision a(m), b(m), answer
integer m
answer = 0.0d0
do i = 1, m
answer = answer + a(i)*b(i)
enddo
end

Perform the following steps with these files to demonstrate Debugger features:
1. Enter the following command in the /usr/demos/WorkShop/getstarted
directory to produce the executable program:
% f90 -g -o progf prog.f dot.f

This produces the executable progf.
2. Launch the WorkShop Debugger with your newly-compiled executable as follows:
% cvd progf &

The WorkShop Debugger Main View displays the source for your prog.f file
(see Example 2-1, page 13).
3. Select the following from the Main View menu bar to turn on file line numbering:
Display
Show Line Numbers
The line numbers will display to the left of the source code.
4. Enter a breakpoint at line 15 as follows at the cvd> prompt at the bottom of the
Main View window. This will enable you to execute through the end of the
initialization of the y array for the sample code:
cvd> stop at 15

Line 15 is highlighted in red and a stop icon appears in the left column.
14

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

5. Run the program. There are two ways that you can do this:
a.

Click on the Run button at the top of the Main View window.
OR

Enter the following at the cvd> prompt:
cvd> run

The program executes up to Line 15 and waits for further instruction.
6. Enter the following command at the cvd> prompt to print the y array for this
example:
cvd> print y
The following displays in the cvd> command pane:
y =
(1) = 1.0
(2) = 2.0
(3) = 3.0
cvd>

Note: You should expand this pane (or use the slider at the right side of the
pane) if you do not see the printout.
7. At this point, you can experiment with other commands described in this chapter,
notably the execution control buttons described in "Options for Controlling
Program Execution", page 19.
8. Select the following to end this tutorial for the Fortran 90 demo program.
Admin
Exit

C Code Example and Short Tutorial
Use the C file prog.c and dot.c in /usr/demos/WorkShop/getstarted to
demonstrate the Debugger features in the following tutorial.

007–2579–006

2: Basic Debugger Usage

Example 2-2 C Code Example

The following is the same example as the Fortran 90 example in "Fortran 90 Code
Example and Short Tutorial", page 13, but it is written in C. Use this example to see
how the Debugger can be used to view C structures.
• The C code in the file prog.c is as follows:
#include
#define N 3
double dot(double v[],double w[], int m);
void main(){
int i,j;
double a[N][N],x[N],y[N],sum,xydot;
struct node
{
int value;
struct node *next;
} *list,start;
/* Initialize arrays */
for(i=0;inext=(struct node *) malloc(sizeof(struct node));
list=list->next;
list->value=i;
}
list->next=NULL;
printf("list: ");
list=&start;
for(i=0;ivalue);
list=list->next;
}
printf("\n");
}

• It includes function dot in file dot.c, as follows:
double dot(double v[],double w[], int m){
int i;
double sum;
for(i=0;i prompt at the bottom of the
Main View window. This will enable you to execute up to the end of the y array
for the sample code:
cvd> stop at 23

Line 23 is highlighted in red and a stop icon appears in the left column.
5. Run the program. There are two ways that you can do this:
a.

Click on the Run button at the top of the Main View window.
OR

Enter the following at the cvd> prompt:
cvd> run

The program executes up to Line 23 and waits for further instruction.
6. Enter the following command at the cvd> prompt to print the y array for this
example:
cvd> print y
The following displays in the cvd command pane:
y = {
[0] 0.00000000000000000e+00
[1] 1.0
[2] 2.0
}

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

cvd>

7. At this point, you can experiment with other commands described in this chapter,
notably the execution control buttons described in "Options for Controlling
Program Execution", page 19.
8. Select the following to end this tutorial for the C demo program.
Admin
Exit

Options for Controlling Program Execution
There are a number of buttons in the Main View window that allow you to control
the execution of your program. The following summarizes their functions:
• Run creates a new process to execute your program and starts execution. It can
also be used to rerun your program.
• Kill kills the active process that is executing your program.
• Stop stops execution of your program. The first executable statement after the
statement where your program has stopped is highlighted.
• Cont continues program execution until a breakpoint or some other event stops
execution, or program execution terminates. (See also "How to Continue a Single
POSIX 6.5 Pthread", page 157.)
• Step steps to the next executable statement and into function and subroutine calls.
Thus, if you set a breakpoint at a subroutine call, click on the Run button so the
call to the subroutine is highlighted in green, then click on the Step button to step
into this subroutine — source code for this subroutine will automatically be
displayed in the Main View window.
By clicking the right mouse button on the Step button you can select the number
of steps the Debugger takes. Left-click on the Step button to take one step.
• Next steps to the next executable statement and steps over function and
subroutine calls. Thus, if you set a breakpoint at a subroutine call, click on the
Run button so the call to the subroutine is highlighted in green, then click the
Next button to step over this subroutine to the next executable statement
displayed in the source pane of the Main View window.
007–2579–006

2: Basic Debugger Usage

Right-click on the Next button to select the number of steps the Debugger takes.
Left-click on the Next button to take one step.
• Return executes the remaining instructions in the current function or subroutine.
Execution stops upon return from that function or subroutine.

Setting Traps
A trap (also called a breakpoint) can be set if you click your cursor in the area to the
left of the statement in the area underneath the word Status in the Main View
window. When you do this, the line in your program will be highlighted in red. To
remove the breakpoint, click in the same place and the red highlighting will
disappear. Clicking on the Run button will cause your program to run and stop at
the first breakpoint encountered. To continue program execution, click on the
Continue button. Breakpoints can only be set at executable statements.

Options for Viewing Variables
There are many ways to view current values of variables with the Debugger. Before
you can do this, you must first run your program under the Debugger and stop
execution at some point. The following sections list ways of viewing current values of
variables with the Debugger. It is suggested that you try each of the following
methods to determine which you would prefer to use.
Viewing Variables Using the cvd Command Line

At the bottom of the Main View window is the command/message pane. Here, you
can give the Debugger various instructions at the cvd command line.
Example 1: Value of array x
If you want to know the current value of array x, enter either of the following two
commands in the command/message pane:
cvd> print x

or
cvd> p x

The current values for x will be printed.
Example 2: Value of x(2)
20

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

If your program is written in Fortran and you only want the value of x(2), enter:
cvd> print x(2)

For a C program, enter:
cvd> print x[2]

Example 3: Change value of x(2) to 3.1
To change the value of x(2) to 3.1 in a Fortran program, enter:
cvd> assign x(2) = 3.1

For a C program, enter:
cvd> assign x[2] = 3.1

The value of x(2) will now be 3.1 when execution is resumed.
Such changes are only active during the current Debugger run of your program. In
the preceding examples, if x is a large array, you may want to use the Array Browser
window (see "Viewing Variables Using the Array Browser", page 24).
To view the components of the structure start in the prog.c example, enter:
cvd> print start

The current values of each component of start will be printed.
To view what the pointer list points to in the prog.c example, enter:
cvd> print *list

Note: This pointer must be initialized before you can perform this function.
A complete list of the instructions that can be entered at the cvd command line can
be found in "Debugger Command Line", page 317.
Viewing Variables Using Click To Evaluate

Perform the following to view variables with Click To Evaluate:
1. Right-click in the window that contains your source code to bring up the
following pop-up menu:

007–2579–006

2: Basic Debugger Usage

Figure 2-1 Evaluation Pop-Up Menu

2. Select Click To Evaluate from this menu. You can now click on any variable and
its value will appear. For example:
• If you click on the x in x(i), the address of x will appear.
• If you click-drag to highlight x(i), the current value of x(i) displays.
• If you highlight an expression, the current value of the expression displays.
Viewing Variables Using the Variable Browser

Perform the following to view variables with the Variable Browser:
1. Select the following from the Main View window to call up the Variable Browser:
Views
Variable Browser
The Variable Browser automatically displays values of all variables valid within
the routine in which you have stopped as well as the address location for each
array.
Values of variables can be changed by typing in their new value in the Result
column and then hitting the ENTER key (or RETURN key, for some keyboards).
Viewing Variables Using the Expression View Window

The Expression View window allows you to enter the variables and/or expressions
for which you would like to know values.
1. Select the following from the Main View window menu bar to display the
Expression View window:
22

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Views
Expression View

Figure 2-2 Expression View Window

2. To view, for example, the value component of the structure start in prog.c, enter
the following in the Expression column:
start.value

As you step through your program, for example with Step Over, the values of all
the entries in this window will be updated to their current values.
Values of variables can be changed by typing in their new value in the Result
column and then pressing ENTER.

007–2579–006

2: Basic Debugger Usage

To enter an expression from your source code into the Expression View window:
1. Left-click and drag on the expression in your source code.
The expression is highlighted.
2. Left-click in a field in the Expression column.
The cursor appear in the field.
3. Middle-click your mouse.
The desired value appears in the field.
Viewing Variables Using the Array Browser

To view array values, select the following from the Main View window menu bar to
call up the Array Browser:
Views
Array Browser

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 2-3 Array Browser Window

To view the values of an array in the Array Browser:
1. Enter the name of this array in the Array field
2. Press ENTER

007–2579–006

2: Basic Debugger Usage

Here, the current values of, at most, two dimensions of the array will display in the
lower pane of the Array Browser window. The values of the array will be updated to
their current values as you step through your program.
Subscript Controls Field
If the array is large or has more than two dimensions, the Subscript Controls panel
in the middle of the Array Browser window allows you to specify portions of the
array for viewing. You may also use the slide bars at the bottom and right of the
window to view hidden portions of an array.
How to Change Values

Perform the following to change values of array elements:
1. Click on the box with the array value in the lower portion of the Array Browser
window.
Note: Once the element is selected, the array index and value appear in the two
fields below the Subscript Controls panel in the center of the Array Browser
window.
For example, if you click on the value for array element A(2,3), then A(2,3)
appears in the box above the display of the array values, and its value appears in
the box to the right of A(2,3). Simply click in this box, and enter a new value for
A(2,3). (Press ENTER to change the value of A(2,3) to the new value.)
2. Enter your change into the Value field described in the note above.
3. If you would like to view a second array at the same time, select the following in
the Array Browser window that you have already opened:
Admin
Clone
This will bring up a second Array Browser window.
4. Select the following from this new window:

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Admin
Active
You can now enter the name of the second array you would like to view.
Viewing Variables Using the Structure Browser Window

Perform the following to view values of a C structure:
1. Select the following from the Main View window menu bar to call up the
Structure Browser window:
Views
Structure Browser
2. Enter the name of the structure in the Expression field.
This will bring up a window listing the name of the structure, the names of its
components in the left column, and their values in the right column.
3. If one of these components is a pointer, you can see what is being pointed to by
double-clicking on its value to the right of the pointer name. This will bring up a
new window showing what is being pointed at and an arrow will appear
showing this relationship. This can aid in debugging linked lists, for example.

Searching
Often it is useful to search for the occurrences of a variable or some character string
in your program so you can set breakpoints. Perform a search as follows:
1. Call up the search utility from the Main View window menu bar as follows to call
up the Search window:

007–2579–006

2: Basic Debugger Usage

Source
Search

Figure 2-4 Search Window

2. Enter the character string for which you would like to search in this window, then
click on the Apply button.
All occurrences of this string are highlighted.
3. Click on Cancel to remove highlighting.

Using the Call Stack
As the Debugger executes, it may stop during a program function or subroutine, or in
a system routine. When this happens, you can locate where the Debugger is in your
program by examining the call stack.
There are two ways to examine the call stack:
• You can enter the following in the command/message pane:
cvd> where

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

This will list the functions and subroutines that were called to bring the Debugger
to this place. This call list will include not only your program
functions/subroutines but may also include system routines that have been used.
You can now move up or down the call tree by issuing, for example:
cvd> up [n]

In this case, the source code for a function or subroutine that is ‘up’ n items in the
call stack will appear in the Main View window. If you omit [n] you move up
one item in the call stack.
• You can select the following from the Main View window menu bar:
Views
Call Stack
This brings up the Call Stack window.

Figure 2-5 Call Stack Window

If you double-click on an item here, the source code for the function or subroutine,
if available, will display in the Main View window.

007–2579–006

2: Basic Debugger Usage

Stopping at Functions or Subroutines
In the debugging process, it is sometimes useful to stop at each occurrence of a
function or subroutine. The Debugger permits you to do this in either of two ways:
• Using the cvd command/message pane.
1. Enter the following in the command/message pane of the Main Window:
cvd> stop in name

For name, specify the name of the function or subroutine in your program
where you would like the Debugger to stop.
2. Click on the Run button and the Debugger will stop each time it encounters
this function or subroutine.
3. To remove this stopping condition enter the following in the
command/message pane:
cvd> status

For the Stop in command above, the trap in the list would appear as:
[n] Stop entry name...

Here, the value of n is a positive integer and name is the name of the function
or subroutine where the stop has been set.
4. To delete this stop, enter:
cvd> delete n

• Using the Trap Manager.
1. Select the following from the Main View window menu bar to use the trap
manager:
Views
Trap Manager
This will call up the Trap Manager window.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 2-6 Trap Manager Window

2. In the text field to the right of the word Trap enter:
stop in name

3. Click on the Add button or press Enter. This will add your breakpoint at your
desired function or subroutine.
Note: To remove the stopping condition so the Debugger will not stop at each
occurrence of name, click on the Delete button in the Trap Manager window.
If you have multiple traps displayed, click on the trap that you wish to delete
before you click on the Delete button.

Suggestions for Debugging for Serial Execution of Scientific Programs
This section offers tips and suggestions for debugging programs written for scientific
applications; but many of the suggestions will apply to debugging other types of
applications as well.

007–2579–006

2: Basic Debugger Usage

Note: This section deals only with debugging programs that are running serially and
not in parallel.
Programs can sometimes appear to have no bugs with some sets of data because all
paths through the program may not be executed. To debug your program, therefore,
it is important to test it with a variety of different data sets so that, one would hope,
all paths in your program can be tested for errors.
Now, assume that your program compiles and produces an executable, but the
program execution either does not complete, or it completes but produces wrong
answers. In this case, go through the following steps to find many of the commonly
occurring bugs.
Note: All compiler options mentioned in the following sections are valid for
FORTRAN 77, Fortran 90, C and C++ compilers unless indicated otherwise.

Step 1: Use lint
If your program is written in C, you should use the lint utility. This will help you
identify problems with your code at the compile step. For example, if your C
program is in a file named prog.c, invoke lint with:
> lint prog.c

The output from this command is directed to your screen.
Note: There is a public domain version of lint for FORTRAN 77 called ftnchek.
You can get ftnchek from the /pub directory at the anonymous ftp site
ftp.dsm.fordham.edu at Fordham University.

Step 2: Check for Out-of-Bounds Array Accesses
A common programming error is the use of array indices outside their declared
limits. For help finding these errors, compile your program as follows:
> -g -DEBUG:subscript_check=ON

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Then run the generated executable under cvd and click on the RUN button. (See the
DEBUG_group(5) man page for more information on this option.)
The following list explains compiling dependencies when working with
out-of-bounds array accesses:
• If you are running a C or C++ program, your program will stop at the first
occurrence of an array index going out of bounds. You can now examine the value
of the index that caused the problem by using any of the methods described in
"Options for Viewing Variables", page 20. If you compile with the -g option, the
compiler generates symbolic debugging information so your program will execute
under cvd. It also disables optimization. Sometimes, disabling optimization will
cause the bug to disappear. If this happens, you should still carefully go through
each of these steps as best as you can.
• If you are using the Fortran 90 compiler, after compiling with the preceding
options and after running the generated executable under cvd, enter the following
in the cvd pane:
cvd> stop in __f90_bounds_check

Note: __f90 in this command has two lead “_” characters.
Now, click on the RUN button. Next select the following from the Main View
window menu bar:
Views
Call Stack
Next, double click on the function or subroutine immediately below
__f90_bounds_check. This will cause the source code for this function or
subroutine to display in the Main View window, and the line where cvd has
stopped will be highlighted. You can now find the value of the index that caused
the out-of-bounds problem.
• If you are using the FORTRAN 77 compiler, after compiling with the preceding
options and after running the generated executable under cvd, enter the following
in the cvd> pane:
cvd> stop in s_rnge

Now, click on the RUN button. Next, select the following from the Main View
menu bar:

007–2579–006

2: Basic Debugger Usage

Views
Call Stack
Double-click on the function or subroutine immediately below s_rnge. This will
cause the source code for this function or subroutine to display in the Main View
window and the line where the Debugger stopped will be highlighted. You can
now find the value of the index that caused the out-of-bounds problem.
Note: For Fortran programs, bounds checking cannot be performed in
subprograms if arrays passed to a subprogram are declared with extents of 1 or *
instead of passing in their sizes and using this information in their declarations.
An example of how the declarations should be written to allow for bounds
checking is: SUBROUTINE SUB(A,LDA,N, ...) INTEGER LDA,N REAL A(LDA,N)

Step 3: Check for Uninitialized Variables Being Used in Calculations
To find uninitialized REAL variables being used in floating-point calculations, compile
your program with the following:
-g -DEBUG:trap_uninitialized=ON

This will force all uninitialized stack, automatic, and dynamically allocated variables
to be initialized with 0xFFFA5A5A. When this value is used as a floating-point
variable involving a floating-point calculation, it is treated as a floating-point NaN
and it will cause a floating-point trap. When it is used as a pointer or as an address a
segmentation violation may occur. For example, if x and y are real variables and the
program is compiled as described previously, x = y will not be detected when y is
uninitialized since no floating point calculations are being done. However, the
following will be detected:
x = y + 1.0

After you compile your program with the preceding options, enter the following:
cvd executable

Then click the RUN button. To find out where your program has stopped, select the
following from the Main View window menu bar:
Views
Call Stack

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Here, you will see that many routines have been called. Double-click on the routine
closest to the top of the displayed list that is not a system routine. (You will probably
recognize the name of this source file.) This will bring up the source code for this
routine and the line where the first uninitialized variable (subject to the
above-mentioned conditions) was used. You can now examine the values of the
indices which caused the problem using any of the methods described in "Options for
Viewing Variables", page 20.
Note: You cannot use cvd to detect the use of uninitialized INTEGER variables.

Step 4: Find Divisions by Zero and Overflows
If you are using a csh or tsch shell, perform the following to find floating-point
divisions by zero and overflows.
1. Enter the following:
setenv TRAP_FPE ON

Note: For other shells, see their man pages.
2. Compile your program using the following options:
-g -lfpe

3. Enter the following:
cvd executable

4. In the cvd command/message pane enter:
cvd> stop in _catch

5. Click on the RUN button.
6. Select the following from the Main View window:

007–2579–006

2: Basic Debugger Usage

Views
Call Stack
7. Double-click on the routine closest to the top of the displayed list that is not a
system routine. (You will probably recognize the name of this source file.)
The line where execution stopped is highlighted in the source code display area
of the Main View window.
You may now use any of the methods to find variable values, described in
"Options for Viewing Variables", page 20, to discover why the divide-by-zero or
overflow occurred.
For more information on handling floating-point exceptions, see the
handle_sigfpes(3) and fsigfpe(3f) man pages.
Perform the following to find integer divisions by zero:
1. Compile your program using the following options:
-g -DEBUG:div_check=1

2. Enter the following:
cvd executable

3. Click the Run button.
The program will automatically stop at the first line where an integer
divide-by-zero occurred. You may now use any of the methods to find variable
values, described in "Options for Viewing Variables", page 20, to discover why the
divide-by-zero occurred.

Step 5: Perform Core File Analysis
Sometimes during program execution a core file is produced and the program does
not complete execution. The file is placed in your working directory and named core.
Some machines are configured to not produce a core file. To find out if this is the case
on the machine you are using, enter the following:
% limit

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

If the limit on coredumpsize is zero, no corefile will be produced. If the limit on
coredumpsize is not large enough to hold the program’s memory image, the core
file produced will not be usable.
To change the configuration to allow core files to be produced enter the following:
% unlimit coredumpsize

Once you have a core file, you can perform the following analysis:
1. You can find the place in your program where the execution stopped and the core
file was produced by entering:
cvd executable core

Here, executable is the executable that you were running.
The Main View window will come up and the source line where execution
stopped may be highlighted in green.
2. If the source line is not highlighted in green, select the following from the Main
View window menu bar:
Views
Call Stack
3. Double-click on the routine closest to the top of the displayed list that is not a
system routine. (You will probably recognize the name of this source file.) This
will bring up the source code for this routine, and the last line executed will be
highlighted in green.
If the executable was formed by compiling with the -g option, then you can view
values of program variables when program execution stopped.
To find the assembly instruction where execution stopped, select the following from
the Main View window menu bar:
Views
Disassembly View
Remember that this is the last statement executed before the core file was produced.
It therefore does not necessarily mean that the bug in your program is in this line of
code. For example, a program variable may have been initialized incorrectly; but the
core was not produced until the variable was used later in the program.

007–2579–006

2: Basic Debugger Usage

Step 6: Troubleshoot Incorrect Answers
Assume that the preceding steps have been taken and that all detected problems have
been corrected. Your program now completes execution, but obtains incorrect
answers. What you do at this point will likely depend on special circumstances. The
following is a list of some commonly used debugging tips that may or may not apply
to your situation.
1. Try running your program on a very small size problem where you can easily
obtain intermediate results. Run your program under cvd on this small problem
and compare with the known correct results.
2. If you know that a certain answer being calculated is not correct, set breakpoints
in your program so you can monitor the value of the answer at various points in
your program.
3. You may want to set breakpoints on each call to a selected function or subroutine
where you suspect there may be problems. (See"Options for Viewing Variables",
page 20 for suggested methods.)
4. Debug COMMON blocks and EQUIVALENCE statements in Fortran. Variables used
in these statements must have the same type and dimension everywhere they
appear and they must occur in the same order. Normally ftnchek, for
FORTRAN 77 programs, and cflint, for Fortran 90 programs, will find these
errors. However, for FORTRAN 77 programs it is best to use an include statement
for each COMMON block. For Fortran 90 programs, it is best to use a module for
each COMMON block. It is best not to use EQUIVALENCE statements.
5. Save local data that is otherwise not saved. In Fortran, values of local variables
are not guaranteed to be saved from one execution of the subprogram to the next
unless they are either initialized in their declarations or they are declared to have
the SAVE attribute. Some compilers and machines automatically give all local
variables the SAVE attribute, so moving a working program from one compiler or
machine to a compiler or machine that does not do this may cause this bug to
manifest. The Fortran standards require that you give all uninitialized local
variables the SAVE attribute if you would like their values saved.

007–2579–006

Chapter 3

Selecting Source Files

This chapter shows you how to select source files for the source pane of the Main
View window of the Debugger (see Figure 1-1, page 3). It covers the following topics:
• "How to Load Source Files", page 39
• "Path Remapping", page 42

How to Load Source Files
The following sections show you the three ways you can load source files for
debugging.
Note: For demonstration purposes, before you begin this section, perform the
following from your shell:
%
%
%
%
%
%

mkdir demos
mkdir demos/jello
cd demos/jello
cp /usr/demos/WorkShop/jello/* .
make
cvd &

Load Directly into the Main View Window
Perform the following steps to load your source file directly into, or run your
executable from, the Debugger Main View window:
• Enter the source file directly.
Enter the name (or full pathname, if necessary) of the source file in the File field.
For example enter:
File: jello.c

if you launched cvd & from within the jello/demos directory.

007–2579–006

3: Selecting Source Files

• Enter the executable directly.
Enter the name (or full pathname, if necessary) of the executable in the Command
field.
For example, enter:
Command: jello

if you launched cvd & from within the jello/demos directory.

Load from the File Browser Dialog Box
You can load source files from the File Browser dialog box, available as follows from
the menu bar of the Main View window:
Views
File Browser
The File Browser window is shown in Figure 3-1.

Figure 3-1 File Browser Window

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

This dialog box provides you with a list of the source files that your executable file
can use, including any files in linked libraries.
locate a file

To locate a file, enter your desired filename in the
Search field.

load a file

To load a file directly into the Main View window from
the File Browser dialog box, simply double-click on the
file name.

Note: You may be unable to locate some files because the source supports system
routines. Source for these routines may not be available on your system.

Load from the Open Dialog Box
You can load source files from the Open dialog box, available as follows from the
menu bar of the Main View window:
Source
Open
The standard dialog box lists all available files and the currently selected directory in
the Selection field. You can change this directory as you wish.

007–2579–006

3: Selecting Source Files

File list
display area

Drop pocket
Selection field

Figure 3-2 Open Dialog Box

There are several ways to load a file. You can:
• double-click on the file name.
• type the full pathname of the file in the Selection field and click the OK button.
• drag the file icon into the drop pocket. (Use an application like fm to produce file
icons.)
If you specify a file name without a full path, the Debugger uses the current path
remapping information to try to locate the file (see Path Remapping, "Path
Remapping", page 42).

Path Remapping
Path remapping allows you to modify mappings to redirect file names, located in
your executable file, to their actual source locations on your file system. Since
42

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

WorkShop uses full (that is, absolute) path names, path remapping generally is not
necessary. However, if you have mounted executable files on a different tree from the
one on which they were compiled, you will need to remap the root prefix to get
access to the source files in that hierarchy.
The most basic remapping is for “.”, which allows you to specify the directories to be
searched for files. This basic function works just like dbx and can be modified by
using use/full_path_name(blank) and dir/full_path_name(blank) in the command line.
Open the Path Remapping window as follows from the menu bar of the Main View
window:
Admin
Remap Paths
The following displays:

Figure 3-3 Path Remapping Dialog Box

For each prefix listed in the Prefix list, there is an ordered set of substitutions used to
find a real file. By default, path remapping is initialized so that “.” is mapped to the
current directory. The Substitution Set for ’.’ list shows the substitution list for the
currently highlighted item in the Prefix list. The Prefix list represents where the
007–2579–006

3: Selecting Source Files

source file(s) used to be and the Substitution Set indicates where the source file(s) are
currently. You can perform the following operations through the Path Remapping
dialog box:
• To view the substitution set for a different prefix, click that prefix.
• To add a new prefix, enter the new value in the Value field below the Prefix list
and click the Add button. A new substitution set is created with the prefix name
as the first element. Click on this element to highlight it.
Next, type the desired substitution in the Value field below the Substitution Set
list and insert it by clicking on either the Insert Before button or the Insert After
button.
• To modify the currently selected prefix, edit the string in the Value field and click
the Modify button.
• To remove the current prefix and its substitution set, select the prefix and click the
Remove button.

Case Example for Path Remapping
In some cases, if source files have been moved to new locations, path remapping is
required to help the Debugger find the source files again.
The following tutorial shows you a case for remapping. It includes demo files
bundled with your WorkShop Debugger:
1. Create a new directory in your_home_directory:
% mkdir jellodemos

2. Change to the new directory:
% cd jellodemos

3. Copy the Jello demo files from the Workshop demo directory into your new
directory:
% cp /usr/demos/WorkShop/jello/* .

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

4. Enter the following to ensure that the jello executable contains the jello
demos source path:
% make clobber
% make

5. Create another new directory in your jellodemos directory:
% mkdir ./newdir

6. Move the Jello source files to a new location:
% mv ./*.c ../newdir

7. Start the WorkShop Debugger:
% cvd ./jello &

The Main View window will display with no source in the source pane. The
following message appears:
Unable to find file cd /usr/demos/WorkShop/jello

2. List the contents of this directory:
>ls

3. Enter the following to make the program if jello is not listed (from Step 2):
> make jello

4. Invoke the Debugger with the jello program:
> cvd jello &

The Main View window appears, as shown in Figure 4-1, page 50, and scrolls
automatically to the main function.
In addition to the Main View window, the Execution View icon also appears.
When you run the jello program, the command you used to invoke jello is
displayed in this window.
The Execution View window is the interface between the program and the user
for programs that use standard input/output or generate stderr messages.

007–2579–006

4: Tutorial: The jello Program

Target process
command

Execution control
buttons
Current process
information

Source code
display area

Source code
annotation column

Source code file
Debugger
command line
Source code
buffer status

Figure 4-1 The Main View Window with jello Source Code

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Note: The Main View window brings up the source file in read-only mode. You
can change this to read/write mode if you select the following from the Main
View window menu bar (provided you have the proper file access permissions):
Source
Make Editable
5. Click the Run button in the upper-right corner of the Main View window to run
the jello program.
The jello window opens on your display (see Figure 4-2, page 52). Enlarge this
window to watch the program execute. The polyhedron is initially suspended in
the center of the cube.
If you wish, you can perform the following with the jello program:
a.

Click the left mouse button anywhere inside the jello window.
The polyhedron drops to the floor of the cube.

Hold down the right mouse button to display the pop-up menu and select
spin.
The cube rotates and the polyhedron bounces inside the cube.

Hold down the right mouse button to display the pop-up menu and select the
display option.
This opens a submenu that allows you to change the appearance of the
jello polyhedron.

d. Feel free to select (right-click) from this menu to see how the jello display
changes.
Note: You may encounter flashing colors inside windows while running
jello. This is normal.

007–2579–006

4: Tutorial: The jello Program

Figure 4-2 The jello Window

6. Right-click and select exit from the pop-up menu to exit this demonstration
executable.

Perform a Search
This part of the tutorial covers the search facility in the Debugger. You will search
through the jello source file for a function called spin. The spin function
recalculates the position of the cube.
1. Select the following from the Main View menu bar:
Source
Search
The Search dialog box appears.
2. Type spin in the Search field in the dialog box, as shown in Figure 4-3.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 4-3 The Search Dialog

3. Click the Apply button.
The search takes place on the displayed source files. Each instance of spin is
highlighted in the source code and flagged with target indicators in the scroll bar
to the right of the display area. (See search target indicators in Figure 4-4, page
54.) The Next and Prev buttons in the Search dialog box let you move from one
occurrence to the next in the order indicated.
For more information on Search, see "Source Menu", page 198.
4. Click the Close button and the dialog box disappears.
5. Click the middle mouse button on the last search target indicator at the right side
of the source code pane (see the figure below). This scrolls the source code down
to the last occurrence of spin, the location of the spin function.

007–2579–006

4: Tutorial: The jello Program

Search
target
indicators

Figure 4-4 Search Target Indicators

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

6. Proceed to "Edit Your Source Code" to edit your code.

Edit Your Source Code
To edit and recompile your source code, follow these steps:
1. Select the following from the Main View menu bar:
Source
Fork Editor
A text editor will appear. (In this case, if you are proceeding from "Perform a
Search", page 52, notice that the spin function is displayed.)
Note: If you use source control, you can check out the source code through the
configuration management shell by selecting the following from the menu bar:
Source
Versioning
CheckOut
2. Edit the source code as follows:
Change all occurrences of 3600 to 3000 in the following code:
if ((a+=1)>3600) a -= 3600;
if ((b+=3)>3600) b -= 3600;
if ((c+=7)>3600) c -= 3600;

Save your changes.
3. Select the following from the menu bar to recompile your code:
Source
Recompile
The Build View window displays and starts the compile. Your makefile will
determine which files need to be recompiled and linked to form a new executable.
Any compile errors are listed in the window, and you can access the related
source code by clicking the errors.

007–2579–006

4: Tutorial: The jello Program

Note: This does not apply to warnings generated by the compiler.
For more information on compiling, see Using the Build Manager, Appendix B,
"Using the Build Manager", page 333.
When the code is successfully rebuilt, the new executable file reattaches
automatically to the Debugger and the Static Analyzer. Previously set traps are
intact unless you have traps triggered at line numbers and have changed the line
count.

Setting Traps
Stop traps (also called breakpoints and watchpoints) stop program execution at a
specified line in the code. This allows you to track the progress of your program and
to check the values of variables at that point. Typically, you set breakpoints in your
program prior to running it under the Debugger. For more information on traps, refer
to Chapter 5, "Setting Traps", page 71.
In this part of the tutorial, you set a breakpoint at the spin function.
1. Click the Run button to run the jello executable.
The demo window will display.
2. Click the left mouse button in the Main View source code annotation column next
to the line containing if ((a+=1)>3600) a -= 3600;, or if
((a+=1)>3000) a -= 3000;, if you are proceeding from the previous section).
A stop trap indicator appears in the annotation column as shown in Figure 4-5,
page 57.
3. Right-click on the jello window and select spin from the pop-up menu.
The program runs up to your stop trap and halts at the beginning of the next call
to the spin function. When the process stops, an icon appears and the line is
highlighted. Note that the Status field indicates the line at which the stop
occurs.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Stop trap
indicator

Figure 4-5 Stop Trap Indicator

4. Click the Continue button at the upper-left corner of the Main View window
several times. Observe that the jello window goes through a spin increment
with each click.
5. Select the following from the Main View window menu bar:

007–2579–006

4: Tutorial: The jello Program

Views
Trap Manager
The Trap Manager window appears as shown in Figure 4-6, page 59.
The Trap Manager window lets you list, add, edit, disable, or remove traps in a
process. In Step 2, you set a breakpoint in the spin function by clicking in the
source code annotation column. The trap now displays in the trap display area of
the Trap Manager window.
The Trap Manager window also permits you to do the following:
• Define other traps.
• Set conditional traps in the Condition field near the top of the window.
• Specify the number of times a trap should be encountered before it activates
by using the Cycle Count field.
• Manipulate traps by using trap controls (Modify, Add, Clear, Delete).
• View all traps (active and inactive) in the trap display area.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Trap specification
Trap condition specification
Cycle count
Current count
Trap controls

Trap display area

Search field

Figure 4-6 Trap Manager Window

6. Click the button to the left of the stop trap in the trap display area.
The trap is temporarily disabled. (If you click again in this box, the trap will be
re-enabled.)
7. Click the Clear button, move the cursor to the Trap field, then type:
watch display_mode

Click the Add button.
This sets a watchpoint for the display_mode variable. A watchpoint is a trap
that causes an interrupt when a specified variable or address is read, written, or
executed.

007–2579–006

4: Tutorial: The jello Program

8. Click the Cont button in the Main View window to restart the process.
The process now runs somewhat slower but still at a reasonable speed for
debugging.
9. Hold down the right mouse button in the jello window to display the pop-up
menu. From this menu, select display and then select the conecs option with the
right mouse button.
This triggers the watchpoint and stops the process.
10. Go to the Trap Manager window and click the button next to the display_mode
watchpoint to deactivate it. Then, click the button next to the spin stop trap to
reactivate it.
11. Enter 100 in the Cycle Count field and click the Modify button. Notice how the
trap description changes in the Trap Manager window.
12. Click the Continue button in the Main View window.
This takes the process through the stop trap for the specified number of times
(100), provided no other interruptions occur.
The Current Count field keeps track of the actual number of iterations since the
last stop, which is useful if an interrupt occurs. Note that it updates at interrupts
only.
13. Select Close from the Admin menu to close the Trap Manager window.

Examining Data
This part of the tutorial describes how to examine data after the process stops.
1. Select the following from the Main View window menu bar:
Views
Call Stack
The Call Stack window appears as shown in Figure 4-7, page 62. The Call Stack
window shows each frame in the call stack at the time of the breakpoint, with the
calling parameters and their values. Through the Call Stack > Display menu,
you can also display the calling parameters’ types and locations, as well as the
program counter (PC) . The program counter is the address at which the program

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

has stopped. For more information about the program counter, see "Traceback
Through the Call Stack Window", page 95.
In this example, the spin and main stack frames are displayed in the Call Stack
window, and the spin stack frame is highlighted, indicating that it is the current
stack frame.
2. Select the following from the Call Stack window menu bar:
Admin
Active
Notice that the Active toggle button is turned on. Active views are those that
have been specified to change their contents at stops or at call stack context
changes. If the toggle is on, the call stack is updated automatically whenever the
process stops.

007–2579–006

4: Tutorial: The jello Program

Figure 4-7 Call Stack at spin Stop Trap

3. Double-click the main stack frame.
This shifts the stack frame to the main function, scrolls the source code in the
Main View window (or Source View) to the place in main where spin was
called, and highlights the call. Any active views are updated according to the
new stack frame.
4. Double-click the spin stack frame.
This returns the stack frame to the spin function.
Select Variable Browser from the Views menu in the Main View window.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

The Variable Browser window appears. This window shows you the value of
local variables at the breakpoint. The variables appear in the left column
(read-only), and the corresponding values appear in the right column (editable).
Your Variable Browser window should resemble the one in Figure 4-8, although
you may need to enlarge the window to see all the variables (the values will be
different).
The jello program uses variables a, b, and c as angles (in tenths); ca, cb, cc as
their corresponding cosines; and sa, sb, sc as their sines. Whenever you stop at
spin, these values change.

Figure 4-8 Variable Browser at spin

007–2579–006

4: Tutorial: The jello Program

5. Double-click some different frames in Call Stack and observe the changes to
Variable Browser and the Main View window.
These views update appropriately whenever you change frames in Call Stack.
Notice also the change indicators in the upper-right corners of the Result fields in
Figure 4-9, page 64. These appear if the value has changed. If you click the folded
corner, the previous value displays (and the indicator appears unfolded). You can
then toggle back to the current value.

Change
indicator

Figure 4-9 Variable Browser after Changes

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

6. Select Close from the Admin menu in Variable Browser and Close from the
Admin menu in Call Stack to close them.
7. Select Expression View from the Views menu in the Main View window.
The Expression View window appears. It lets you evaluate an expression
involving data from the process. The expression can be typed in, or more simply,
cut and pasted from your source code. You can view the value of variables (or
expressions involving variables) any time the process stops. Enter the expression
in the left column, and the corresponding value appears in the right column. For
more information, see "Evaluating Expressions", page 101.
8. Hold down the right mouse button in the Expression column to bring up the
Language menu. Then hold down the right mouse button in the Result column
to display the Format menu.
The Language menu (shown on the left side of Figure 4-10, page 65) lets you
apply the language semantics to the expression.
The Format menu (shown on the right side of Figure 4-10, page 65) lets you view
the value, type, address, or size of the result. You can further specify the display
format for the value and address.

Column sash

Figure 4-10 Expression View with Language and Format Menus Displayed

007–2579–006

4: Tutorial: The jello Program

9. Click on the first Expression field in the Expression View window. Then enter
(a+1)>3600 in the field and press Enter.
This is a test performed in jello to ensure that the value of a is less than 3600.
This uses the variable a that was displayed previously in Variable Browser. After
you press Enter, the result is displayed in the right column; 0 signifies FALSE.
10. Select the following from the Expression View window menu bar to close that
window:
Admin
Close
11. Select the following from the Main View window to open the Structure Browser:
Views
Structure Browser
12. Enter jello_conec in the Expression field and press Enter.
The Structure Browser window displays the structure for the given expression;
field names are displayed in the left column, and values in the right column. If
only pointers are available, the Structure Browser will de-reference the pointers
automatically until actual values are encountered. You can then perform any
further de-referencing by double-clicking pointer addresses in the right column of
the data structure objects. A window similar to the one shown in Figure 4-11 now
appears.

Figure 4-11 Structure Browser Window with jello_conec Structure

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

13. Click once to focus, then double-click the address of the next field (in the right
column of the jello_conec structure).
Double-clicking the address corresponding to a pointer field de-references it.
Double-clicking the field name displays the complete name of the field in the
Expression field at the top of the Structure Browser window. (See Figure 4-12,
page 67.)

Figure 4-12 Structure Browser Window with Next Pointer De-referenced

14. Select Close from the Admin menu of Structure Browser window to close it.
15. Select the following from the Main View window menu bar:
Views
Array Browser
The Array Browser lets you see or change values in an array variable. It is
particularly valuable for finding bad data in an array or for testing the effects of
values you enter.
16. Type shadow in the Array field and press Enter.
You can now see the values of the shadow matrix, which displays the
polyhedron’s shadow on the cube. The Array Browser template should resemble
Figure 4-13, page 68, but with different data values. If any areas are hidden, hold
down the left mouse button and drag the sash buttons at the lower right of the
array specification and subscript control areas to expose the area.
007–2579–006

4: Tutorial: The jello Program

Array specification
area
Subscript control
area

Spreadsheet area

Figure 4-13 Array Browser Window for shadow Matrix

17. Select the Col button next to the $k index in the Subscript Controls pane (you
may need to scroll down to it).
The Array Browser can handle matrices containing up to six dimensions but
displays only two dimensions at a time. Selecting the Col button for $k has the
effect of switching from a display of $i by $j to a display of $i by $k.
Figure 4-14, page 69, shows a close-up view of the subscript control area.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Row/column toggles
Index identifiers
Index values
Index sliders
Index minimums
Index maximums
Horizontal scroll bar
Step indicators
Vertical scroll bar

Figure 4-14 Subscript Controls Panel in Array Browser Window

The row and column toggles indicate whether a particular dimension of the array
appears as a row, column, or not at all in the spreadsheet area. Although an array
may be of 1 to 6 dimensions, you can view only one or two dimensions at a time.
The index values shown as Min and Max initially exhibit the lower and upper
bounds of the dimension indicated. The values may be changed to allow the user
to display a subset of the available index range in that dimension. The index
sliders let you move the focus cell along the particular dimension. The focus cell
may also be changed by selecting a cell with the left mouse button. The index
slider for a dimension whose row and column toggles are both off may be used to
select a different two–dimensional plane of a multidimensional array. Use the
horizontal and vertical scroll bars to expose hidden portions of the Array Browser
window.
18. Select Surface from the Render menu.
The Render menu displays the data from the selected array variable graphically,
in this case as a three-dimensional surface. The selected cell is highlighted by a
rectangular prism. The selected subscripts correspond to the x- and y-axes in the
rendering with the corresponding value plotted on the z-axis. The data can be
rendered as a surface, bar chart, multiple lines, or points.

007–2579–006

4: Tutorial: The jello Program

Exiting the Debugger
There are several ways to exit the Debugger:
• Select Exit from the Admin menu.
• Type quit at the Debugger command line as follows:
cvd> quit

• Double-click on the icon in the upper-left corner of the Main View window.
• Press Ctrl-c in the same window where you entered the cvd command.

007–2579–006

Chapter 5

Setting Traps

Traps are also referred to as breakpoints, watchpoints, samples, signals, and system
calls. Setting traps is one of the most valuable functions of a debugger or performance
analyzer. A trap enables you to select a location or condition within your program at
which you can stop the execution of the process, or collect performance data and
continue execution. You can set or clear traps from the Main View window or the
Trap Manager window. You can also specify traps in the Debugger command line at
the bottom of the Main View window. For signal traps, you can also use the Signal
Panel window; and for system call traps, use the Syscall Panel window.
When you are debugging a program, you typically set a trap in your program to
determine if there is a problem at that point. The Debugger lets you inspect the call
stack, examine variable values, or perform other procedures to get information about
the state of your program.
Traps are also useful for analyzing program performance. They let you collect
performance data at the selected point in your program. Program execution continues
after the data is collected.
This chapter covers the following topics:
• "Traps Terminology ", page 71
• "Setting Traps", page 74
• "Setting Traps in the Trap Manager Window", page 78
• "Setting Traps by Using Signal Panel and System Call Panel", page 87
For a tutorial on the use of traps, see "Setting Traps", page 56.

Traps Terminology
A trap is an intentional process interruption that can either stop a process or capture
data about a process. It has two parts:
trigger

007–2579–006

Specifies when the trap fires

5: Setting Traps

action

Specifies what happens when the trap fires

Trap Triggers
You can set traps at a specified location in your program or when a specified event
occurs. You can set a trigger at any of the following points:
• At a given line in a file (often referred to as a breakpoint)
• At a given instruction address
• At the entry or exit for a given function
• After set time intervals (referred to as a pollpoint)
• When a given variable or address is read, written, or executed (referred to as a
watchpoint)
• When a given signal is received
• When a given system call is entered or exited
In addition, you can use an expression to specify a condition that must be met before
a trap fires. You can also specify a cycle count, which specifies the number of passes
through a trap before firing it.
Note: When you set a breakpoint in C++ code that uses templates, that breakpoint
will be set in each instantiation of the template.

Trap Types
Traps can effect any of a number of actions in your debugging process. The following
is a list of the variety of traps and their functions:
Note: See "Syntaxes", page 81 for trap syntaxes.
• A stop trap will cause one or all processes to stop. In single process debugging, a
stop trap stops the current process. In multiprocess debugging, you can specify a
stop trap to stop all processes or only the current process.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

• A pending trap is a trap with a destination address that does not resolve at the
initial startup of the debugger: it allows you to place breakpoints on names that
do not yet exist. By enabling pending traps, you make unknown function names
acceptable breakpoint locations or entries. Because of this, the trap manager will
not error a pending trap off if it can not be found in the executable. Instead, when
a dlopen of a DSO (dynamic shared object) occurs, and the function name is found
that matches the trap, the trap is resolved and becomes active.
There are two ways to enable pending traps.
– You can add the following line to your .Xdefaults file:
*AllowPendingTraps: true

– You can enable pending traps by entering the following in the cvd> pane of
the Main View window:
set $pendingtraps=true

The default for this variable is false.
Note: Only “stop entry” / “stop in” and “stop exit” traps can be pending traps,
not “stop at” traps. The debugger will only accept a “stop at” trap on a DSO
(dynamic shared object) and line number loaded at startup. (See "Syntaxes", page
81 for trap syntaxes.)
To get around this, set a pending “stop in” trap and run to the trap location. Now
you can set “stop at” traps because the DSO is loaded. The debugger will then
remember these traps if you run, kill, and re-run within a single session.
Pending traps display with the prefix (pending) preceding the normal trap
display line.
Note: Breakpoints on misspelled names are not flagged as errors when pending
traps are enabled. This is because the Debugger has no way of knowing if a
pending trap will ever be tripped.
• A sample trap collects performance data. Sample traps are used only in performance
analysis, not in debugging. They collect data without stopping the process. You
can specify sample traps to collect such information as call stack data, function
counts, basic block counts, PC profile counts, mallocs/frees, system calls, and

007–2579–006

5: Setting Traps

page faults. Sample traps can use any of the triggers that stop traps use. Sample
traps are often set up as pollpoints so that they collect data at set time intervals.
• An exception trap fires when a C++ exception is raised.
You can add a conditional expression to an exception trap through the Trap
Manager window. However, the context in which the expression is evaluated is not
that of the throw; the context is the exception handling of the C++ runtime library.
Therefore, only global variables have unambiguous interpretation in the if clause.
You should not include complex expressions involving operators such as * and &
in your type specification for an exception trap. If you create an exception trap
with a specific base type, however, you will also stop your program on throws of
pointer, reference, const, and volatile types. For example, if:
cvd> stop exception char

then your program will stop at type char, char*, char&, const char&, and so
forth.

Setting Traps
You can set traps directly in the Main View window by using the Traps menu or by
clicking the mouse in the source annotation column. You can also specify traps at the
Debugger cvd command line.
The following sections describe the ways that traps can be set:
• "Setting Traps with the Mouse", page 74
• "Setting Traps Using the cvd Command Line", page 75
• "Setting Traps Using the Traps Menu in the Main View Window", page 75

Setting Traps with the Mouse
The following lists ways to set traps by using your mouse:
• The quickest way to set a trap is to click in the source annotation column in the
Main View or Source View windows. A subsequent click removes the trap.
• If data collection mode has been specified in the Performance Data window,
clicking produces a sample trap; otherwise, a stop trap is entered.
74

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

To determine if data collection is on, look at the upper-right corner of the Main
View window to see which debugging option is selected (Debug Only,
Performance, or Purify).
When the trap is set, a trap icon appears.

Setting Traps Using the cvd Command Line
The cvd command line is discussed in . stop commands similar to those found in
dbx, or as documented in "Setting Single-Process and Multiprocess Traps", page 79,
may be entered into the command line portion of the Main View window as an
alternative way to set traps.

Setting Traps Using the Traps Menu in the Main View Window
To set a trap using the Traps menu, you first need to know which type of trap you
wish to set, then select the location in your program at which to set the trap.
To set a stop trap or sample trap at a line displayed in the Main View window (or the
Source View window), click in the source code display area next to the desired line in
the source code, or click-drag to highlight the line. Then, select either of the following
from the menu bar:
Traps
Set Trap
Stop
or
Traps
Set Trap
Sample
The Traps menu in the Main View window is shown in Figure 5-1.

007–2579–006

5: Setting Traps

Figure 5-1 Traps Menu in the Main View Window

For a trap at the beginning or end of a function, highlight the function name in the
source code display area and select one of the following from the Traps > Set Traps
submenu as is appropriate to your needs:
• Stop At Function Entry
• Stop At Function Exit
• Sample At Function Entry
• Sample At Function Exit
Traps are indicated by icons in the source annotation column (and also appear in the
Trap Manager window if you have it open). Figure 5-2, page 77, shows some typical
trap icons. Sampling is indicated by a dot in the center of the icon. Traps appear in
normal color or grayed out, depending on whether they are active or inactive. A
transcript of the trap activity appears in the Debugger command line area. The
active/inactive nature of traps is discussed in "Enabling and Disabling Traps", page 86.
The Clear Trap selection in the Traps menu deletes the trap on the line containing the
cursor. You must designate a Stop or Sample trap type, since both types can exist at
the same location appearing superimposed on each other.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

When the Group Trap Default toggle is checked (ON), the pgrp option is added into
the resulting trap when a trap is set. This option causes the trap to apply to all
processes/pthreads in the group of which the current process is a member.
When the Stop All Defaults toggle is checked (ON), the all option is added into the
resulting trap when a trap is set. This option causes the trap to apply to all
processes/pthreads in the current debugging session.

Annotation column

Active stop trap
Inactive stop trap
Active sample trap

Inactive sample trap

Debugger command
line transcript

Figure 5-2 Typical Trap Icons

007–2579–006

5: Setting Traps

Setting Traps in the

Trap Manager

Window

The Trap Manager window is brought up by selecting the following from the Main
View window menu bar:
Views
Trap Manager
This tool helps you manage all traps in a process. Its two major functions are to:
• List all traps in the process (except signal traps)
• Add, delete, modify, or disable the traps listed
The Trap Manager window appears in Figure 5-3 with the Config, Traps, and
Display menus shown.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Trap specification
Trap condition
specification
Cycle Count
Current Count
Trap controls
Trap display area

Search field

Figure 5-3 Trap Manager Config, Traps, and Display Menus

Setting Single-Process and Multiprocess Traps
New or modified traps are entered in the Trap field. Traps have the following general
form:
[stop | sample] [all] [pgrp] location | condition
The entry [stop | sample] refers to the trap action. You can set a default for the
action by using the Stop Trap Default or Sample Trap Default selections of the Traps
menu and omitting it on the command line.

007–2579–006

5: Setting Traps

The entries [all] and [pgrp] are used in multiprocess analysis. The [all] entry
causes all processes in the process group to stop or sample when the trap fires. The
[pgrp] entry sets the trap in all processes within the process group that contains the
code where the trap is set. You can set a default for the action by setting the Stop All
Default or Group Trap Default toggles in the Traps menu.
After you enter the trap (by using the Add or Modify button or by pressing Enter),
the full syntax of the specification appears in the field. The Clear button clears the
Trap and Condition fields and the cycle fields.
Some typical trap examples are provided in Figure 5-4, page 80. The entries made in
the Trap field are shown in the left portion of the figure, the trap display in the Trap
Manager window resulting from these entries is shown on the right, and the trap
display shown at the command line in the Main View window is shown at the bottom.

Trap entries

Resulting command line
display in Main View

Figure 5-4 Trap Examples

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Syntaxes

Specific command syntaxes that may be entered in the Trap text field are shown in
the following sections:
Note: A backslash (\) shown at the end of a line in these examples indicates that the
command is continued. Do not enter a backslash in the text field.

Setting a Trap in filename at line-number

[stop | sample] [all] [pgrp] at [{file] filename]\
[[line] line-number]
This command sets a trap at the specified line in the specified file, for example:
Trap: stop at 1449.
Setting a Trap on instruction-address

[stop | sample] [all] [pgrp] addr instruction-address
This command sets a trap on the specified instruction address. Instruction addresses
may be obtained from the Disassembly View window, which is brought up from the
Views submenu on the Main View window menu bar. The addresses may be entered
as shown, such as ’0af8cbb8’X, or as 0x0af8cbb8. For example:
Trap: stop addr 0x0af8cbb8

Setting a Trap on Entry to function

[stop | sample] [all] [pgrp] entry function \
[[file] filename]
[stop | sample] [all] [pgrp] in function\
[[file] filename]

007–2579–006

5: Setting Traps

This command sets a trap on entry to the specified function. For example:
Trap: stop entry anneal

or
Trap: stop in anneal

If the filename is given, the function is assumed to be in that file’s scope.
Setting a Trap on Exit from function

[stop | sample] [all] [pgrp] exit function\
[[file] filename]
This command sets a trap on exit from the specified function. For example:
Trap: stop exit anneal file generic.c

If the filename is given, the function is assumed to be in that file’s scope.
Setting a Watchpoint on Specified expression

[stop | sample] [all] [ pgrp] watch expression \ [
[for] read | write | execute [access]]
This command sets a watchpoint on the specified expression (using the address and
size of the expression for the watchpoint span). The watchpoint may be specified to
fire on write, read, or execute (or some combination thereof). If not specified, the
write condition is assumed. This syntax has no provision for looking on only a
portion of an array. The next syntax item can handle such a request. For example:
Trap: stop watch x for write

Setting a Watchpoint for address and size

[stop | sample] [all] [pgrp] watch addr[ess] address \
[[size] size] [[for] read | write | execute \
[access]]

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

This command sets a watchpoint for the specified address and size in bytes. Typically
the expression is the name of a variable. The watchpoint may be specified to fire on
write, read, or execute (or some combination thereof) of memory in the given
span. If not specified, the size defaults to 4 bytes. Also, if not specified, the write
condition is assumed. Addresses may be found by choosing the following from the
Main View window menu bar:
Views
Variable Browser
or
Views
Structure Browser
The window displays addresses for arrays and has options to display addresses for
other variables. Addresses may be entered in the form 0x0123fabc or
’0123fabc’X. For example:
Trap: stop watch addr 0x0123fabc 16

If the array you are watching at address 0x0123fabc is defined such that each
element is 4 bytes long, this example trap would be watching 4 adjacent array
elements and would cause a stop if any of those 4 elements were updated, since a
size of 16 is specified.
Setting a Trap at signal-name

[stop | sample] [all] [pgrp] signal signal-name
This command sets a trap upon receipt of the given signal. This is the same as the
dbx(1) catch subcommand. (For a list of signals, or an alternative way to set traps
involving signals, see "Setting Traps by Using Signal Panel and System Call Panel",
page 87.) For example:
Trap: stop signal SGIFPE

Setting a Trap on Entry to sys-call-name

[stop | sample] [all] [pgrp] syscall entry sys-call-name

007–2579–006

5: Setting Traps

This command sets a trap on entry to the specified system call. This is slightly
different from setting a trap on entry to the function by the same name. A syscall
entry trap sets a trap on entry to the actual system call. A function entry trap sets a
trap on entry to the stub function that calls the system call. (For a list of system calls,
or an alternative way to set traps involving system calls, see "Setting Traps by Using
Signal Panel and System Call Panel", page 87.) For example:
Trap: stop syscall entry write

Setting a Trap on Exit from sys-call-name

[stop | sample] [all] [pgrp] syscall exit sys-call-name
This command sets a trap on exit from the specified system call. This is slightly
different from setting a trap on exit from the function by the same name. A syscall
exit trap sets a trap on exit from the actual system call. A function exit trap sets a
trap on exit from the stub function that calls the system call. (For a list of signals, or
an alternative way to set traps involving signals, see "Setting Traps by Using Signal
Panel and System Call Panel", page 87.) For example:
Trap: stop syscall exit read

Setting a Trap at time Interval

[stop | sample] pollpoint [interval] time [seconds]
This command sets a trap at regular intervals of seconds. This is typically used only
for sampling. For example:
Trap: stop pollpoint 3

Setting a Trap for C++ Exception

[stop | sample] exception [all | item] itemname
This command sets a trap on all C++ exceptions, or exceptions that throw the base
type item.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

[stop | sample] exception unexpected [all | [item [, item]]]
Stops on all C++ exceptions that have either no handler or are caught by an
unexpected handler. If you specify item, stops on executions that throw the base type
item.

Setting a Trap Condition
The Condition field in the Trap Manager window lets you specify the condition
necessary for the trap to be fired. A condition can be any legal expression and is
considered to be true if it returns a nonzero value when the corresponding trap is
encountered.
The expression must be valid in the context in which it will be evaluated. For
example, a Fortran condition like a .gt .2 cannot be evaluated if it is tested while
the program is stopped in a C function.
There are two possible sequences for entering a trap with a condition:
1. Define the trap.
2. Define the condition.
3. Click Add.
or
1. Define the trap.
2. Click Add.
3. Define the condition.
4. Click Modify (or press Enter).
An example of a trap with a condition is shown in Figure 5-4, page 80. The
expression i==1 has been entered in the Condition field. (If you were debugging in
Fortran, you would use the Fortran expression i .eq .1 rather than i==1.) After
the trap has been entered, the condition appears as part of the trap definition in the
display area. During execution, any requirements set by the trigger must be satisfied
first for the condition to be tested. A condition is true if the expression (valid in the
language of the program you are debugging) evaluates to a nonzero value.

007–2579–006

5: Setting Traps

Setting a Trap Cycle Count
The Cycle Count field in the Trap Manager window lets you pass through a trap a
specific number of times without firing. If you set a cycle count of n, the trap will fire
every nth time the trap is encountered. The Current Count field indicates the number
of times the process has passed the trap since either the cycle count was set or the
trap last fired. The current count updates only when the process stops.

Setting a Trap with the Traps Menu
The Traps menu of the Trap Manager window lets you specify traps in conjunction
with the Main View or Source View windows. Clicking At Source Line sets a trap at
the line in the source display area that is currently selected. To set a trap at the
beginning or end of a function, highlight the function name in the source display and
click Entry Function or Exit Function.

Moving around the Trap Display Area
The trap display area displays all traps set for the current process. There are vertical
and horizontal scroll bars for moving around the display area. The Search field lets
you incrementally search for any string in any trap.

Enabling and Disabling Traps
Each trap has an indicator to its left for toggling back and forth between active and
inactive trap states. This feature lets you accumulate traps and turn them on only as
needed. Thus, when you do not need the trap, it will not be in your way. When you
do need it, you can easily activate it.

Saving and Reusing Trap Sets
The Load Traps selection in the Config menu lets you bring in previously saved trap
sets. This is useful for reestablishing a set of traps between debugging sessions. The
Save Traps... selection of the Config menu lets you save the current traps to a file.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Setting Traps by Using

Signal Panel

and

System Call Panel

You can trap signals by using the Signal Panel and set system calls by using System
Call Panel (see Figure 5-5, page 87).

Figure 5-5 Signal Panel and System Call Panel

You can select either panel from the Views menu of the Main View window menu
bar. The Signal Panel sets a trap on receipt of the signal(s) selected. The System Call
Panel sets a trap at the selected entry to or return from the system call.
Note: When debugging IRIX 6.5 pthreads, the Signal Panel is inaccessible if more
than one thread is active.

007–2579–006

Chapter 6

Controlling Program Execution

This chapter shows you how to control the execution of your program with
WorkShop Debugger. It includes the following topics:
• "The Main View Window Control Panel", page 89
• "Controlling Program Execution Using the PC Menu", page 93
• "Execution View", page 94

The Main View Window Control Panel
The Main View window control panel allows you to choose an executable, and
control its execution:

Target command
Execution control
buttons
Status line

Figure 6-1 The Main View Window Control Panel

Features of the Main View Window Control Panel
The control panel includes the following:

007–2579–006

Command field

Use this field to enter commands (with arguments) to
run your program.

Status field

Displays information about the execution status of your
program. The top line in this box indicates whether the
program is running or stopped. The message No
executable displays if no executable is loaded. When
89

6: Controlling Program Execution

your program stops at a breakpoint, an additional
status line lists the current stack frame.
Note: To see all of the stack frames, select the following
from the Menu Bar:
Views > Call Stack

Execution Control Buttons
The execution control buttons enable you to control program execution. Most of these
buttons are not active until the Run button has been selected and the program is
executed.
Note: The Print button does not affect program execution. It is described in
Appendix A, "Debugger Reference", page 187.

Run

Creates a new process for your program and starts its
execution. The Run button is also used to re-run a
program.

Kill

Kills the active process.

Stay Focused/Follow
Interesting

If the lock icon is locked, it indicates that the focus of
Main View will attempt to stay focused on this thread.
If the lock is unlocked, the debugger will follow the
interesting thread. This means it will focus on threads
that reach a user breakpoint.

All/Single

If set to All, the Cont, Stop, Step, Next, and Return
actions apply to all processor or threads. If set to
Single, then only the currently focused process or
thread will be acted upon.

Cont

Resumes program execution after a halt and continues
until a breakpoint or other event stops execution.

Stop

Stops execution of your program. When program
execution stops, the current source line is highlighted in
the Main View window and annotated with an arrow.

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Step

Steps to the next source line and into function or
subroutine calls. To step a specific number of lines,
right-click on the button. This displays the pop-up
menu shown in Figure 6-2, page 91. You can select one
of the fixed values or enter your own number of steps
by selecting N Selecting N displays the dialog box
shown at the right in Figure 6-2, page 91.

Figure 6-2 Pop-up Menu and Step Dialog

007–2579–006

6: Controlling Program Execution

Steps over function or subroutine calls to the next
source line. To step a specific number of lines,
right-click on this button to display the pop-up menu
shown in Figure 6-3, page 92. You can select one of the
fixed values or enter your own number of steps by
selecting N. If you select N, the dialog box shown at the
right in Figure 6-3, page 92 displays.

Figure 6-3 Pop-up Menu and Next Dialog

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Return

Executes the remaining instructions in the current
function or subroutine, and stops execution at the
return from this subprogram.

Sample

Collects performance data. Before this button is
operative, a performance task must have been
previously specified in the Performance Task window
and data collection must have been enabled.
For further information about using the Performance
Analyzer, see ProDev WorkShop: Performance Analyzer
User’s Guide

Controlling Program Execution Using the

The PC (program counter) menu in the Main View window includes two tools,
Continue To and Jump To, which allow you to control program execution without
setting breakpoints.
These tools are inoperative until a process has been executing and is stopped. At that
point, you must place your cursor on a source line you wish to target, then select
from the PC menu depending on your requirements. The program counter tools are
described as follows:

007–2579–006

Continue To

This tool lets you select a target location in the current
program (by placing the cursor in the line). The process
proceeds from the current program counter to that
point, provided there are no interruptions. It then stops
there, as it would for a stop trap. Continue To is
equivalent to setting a one-time trap. If the process is
interrupted before reaching your target location, then
the command is cancelled.

Jump To

This tool lets you select a target location in the current
program (by placing the cursor in the line). This
location must be in the same function. Instead of
starting from the current program counter, Jump To
skips over any intervening code and restarts the process
at your target. This is particularly useful if you want to
get around bad code or irrelevant portions of the

6: Controlling Program Execution

program. It also lets you back up and reexecute a
portion of code.

Execution View
The Execution View window is a simple shell that lets you set environment variables
and inspect error messages. If your program is designed to be interactive using
standard I/O, this interaction will take place in the Execution View window. Any
standard I/O that is not redirected by your Target Command is displayed in the
Execution View window.
Note: When you launch the debugger, the Execution View window is launched in
iconified form.

007–2579–006

Chapter 7

Viewing Program Data

After you set traps (breakpoints) in your program, use the Run button to execute
your program. When a trap stops a process, you can view your program data using
the tools described in this chapter. This chapter covers:
• "Traceback Through the Call Stack Window", page 95
• "Evaluating Expressions", page 101
The Debugger also lets you examine data at the machine level. The tools for viewing
disassembled code, machine registers, and data by specific memory location are
described in Appendix A, "Debugger Reference", page 187.

Traceback Through the

Call Stack

Window

The Views menu may be used to bring up the Call Stack window. This window
displays the functions/subroutines (that is, the “frames”) in the call stack when the
process associated with your program has stopped. This display provides a traceback
of subprograms from the system routine which starts your executable, found at the
bottom of the list, to the routine in which you are currently stopped, found at the top
of the list. If the trap/breakpoint at which you are currently stopped is located in
your source code, that code is displayed in the source pane of the Main View
window. If the trap/breakpoint is located in a system routine, the Call Stack allows
you to double-click on another routine’s name to bring up that routine’s source and
associated data. A typical Call Stack window is shown in Figure 7-1, page 96.

007–2579–006

7: Viewing Program Data

Figure 7-1 Call Stack Window

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

The Call Stack window lets you see the argument names, values, types, and locations
of functions, as well as the program counter (PC).
If symbolic information for the arguments has been stripped from the executable file,
the label appears in place of the arguments. By default call stack depth
is set to 10, but you can reset the depth of the Call Stack by selecting the following
from the Main View window:
Config
Preferences
To move through the call stack, double-click a frame in the stack. The frame becomes
highlighted to indicate the current context. The source display in the Main View or
Source View windows scrolls automatically to the location where the function was
called and any other active views update.
The source display has two special annotations:
• The location of the current program state is indicated by a large arrow. This
represents the PC (program counter).
• The location of the call to the function selected in the Call Stack window is
indicated by a smaller arrow. This represents the current context, and the source
line is highlighted.
Figure 7-2, page 98, illustrates the correspondence between a frame and the source
code when a frame is clicked in the Call Stack window. In this example, the stack
frame spin has been selected; the Main View display scrolls to the place where the
trap occurred. If the second stack (main) had been selected, the window would have
scrolled to the place where the function main calls spin.

007–2579–006

7: Viewing Program Data

Figure 7-2 Tracing through Call Stack

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Options for Viewing Variables
The WorkShop Debugger provides several options for viewing variables or
expressions involving these variables. In this section only brief descriptions of these
options will be provided along with references where further information may be
obtained elsewhere in this document.

Using the cvd Command Line
At the bottom of the Main View window is the cvd command/message pane. Here,
you can enter print xxx commands to obtain the current value of variable xxx.
For examples of these commands, see "Viewing Variables Using the cvd Command
Line", page 20.
For the syntax of these commands (such as assign, print, printd, printo,
printx, and so on), see "Syntax for dbx-style Commands", page 317.

Using Click to Evaluate
In the Main View window’s source pane, a click of the right mouse button will bring
up a pop-up menu from which you can select Click to Evaluate. When this option is
on, a click on a variable will cause its value to appear. If you click on a subscript
variable, its address will appear. If you hold down the left mouse button and wipe
across a variable and its subscripts to highlight them, the current value will be
displayed. The same is true if an expression in the source is highlighted.

Using the Array Browser
To view values of arrays, select the following from the Main View menu bar:
Views
Array Browser
This calls up the Array Browser window. When the name of an array is entered into
the Array field, the values of 1–dimensional arrays or the values in a selected plane of
a multi-dimensional array are displayed.
See "Viewing Variables Using the Array Browser", page 24 for short description of the
Array Browser. Also, "Array Browser Window", page 262, “Array Browser Window”,

007–2579–006

7: Viewing Program Data

provides a more detailed description and graphic of the window and associated
submenus.

Using the Structure Browser
To view C structures, select the following from the Main View menu bar:
Views
Structure Browser
This calls up the Structure Browser window. When the name of a structure is entered
into the Expression field, the objects in the structure display in the lower portion of
the window.
See "Viewing Variables Using the Structure Browser Window", page 27 for a short
description of the Structure Browser. Also, "Structure Browser Window", page 282,
“Structure Browser Window”, provides a more detailed description and graphic of
the window and associated submenus.

Using the Variable Browser
To call up the Variable Browser window, select the following from the Main View
menu bar:
Views
Variable Browser
This window lists the names and values of variables associated with the current
routine in which the process has stopped.
See "Viewing Variables Using the Variable Browser", page 22 for a short description
of the Variable Browser. Also, "Variable Browser Window", page 293, “Variable
Browser Window”, provides a more detailed description and graphic of the window
and associated submenus.

Using the Expression View
Select the following from the Main View menu bar to bring up the Expression View
window:

100

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Views
Expression View
Expressions may be entered into this window in the Expression column; and the
corresponding Results entry will display the value of the evaluated expression using
values of variables associated with the current routine in which the process has
stopped.
See "Viewing Variables Using the Expression View Window", page 22 for a short
description of the Expressions View window. Also, "Expression View Window", page
278, Expression View Window, provides a more detailed description and graphic of
the window and associated submenus.
The next section of this chapter, “Evaluating Expressions”, gives further details on
how to create acceptable expressions for the Expression View.

Evaluating Expressions
You can evaluate any valid expression at a stopping point and trace it through the
process. Expressions are evaluated by default in the frame and language of the
current context. Expressions may contain data names or constants; however, they may
not contain names known only to the C preprocessor, such as in a #define directive
or a macro.
To evaluate expressions, you can use Expression View, which lets you evaluate
multiple expressions simultaneously, updating their values each time the process
stops.
Note: You can also evaluate expressions from the command line. See "Debugger
Command Line", page 317 for more information.

Expression View Window
The Expression View window is shown in Figure 7-3, page 102, with its major menus
displayed. The Expression View window has two pop-up menus, the Language
menu and the Format menu:
• The Language menu is invoked by holding down the right mouse button while
the cursor is in the Expression column.

007–2579–006

101

7: Viewing Program Data

• The Format menu is displayed by holding down the right mouse button in the
Result column.
To specify the expression to be evaluated, click in the Expression column and then
enter the expression in the selected field. It must be a valid expression in the current
or selected language: Ada, C, C++, or Fortran. To change languages, display the
Language menu and make your selection. When you press Enter, the result of the
expression is displayed in the Result column.

Editable Result
field

Figure 7-3 Expression View with Major Menus Displayed

To change the type of result information displayed in the right column, hold down
the right mouse button over the right column. This displays the Format menu. From
here you can select the following:

102

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

• Select the Default Value menu to see the value as decimal, unsigned, octal, hex,
float, char, or string characters.
• Select the Type Address Of menu to display the address in decimal, octal, or
hexadecimal.
• Select Bit Size to specify the size of the result, in bits.

Caution: The Debugger uses the symbol table of the target program to determine
variable type. Some variables in libraries, such as errno and _environ, are not fully
described in the symbol table. As a result, the Debugger may not know their types.
When the Debugger evaluates such a variable, it assumes that the variable is a
fullword integer. This gives the correct value for fullword integers or pointers, but the
wrong value for non-fullword integers and for floating-point values.
To see the value of a variable of unknown type, use C type cast syntax to cast the
address of the variable to a pointer that points to the correct type. For example, the
global variable _environ should be of type char**. You can see its value by
evaluating *(char***)&_environ.
After you display the current value of the expression, you may find it useful to leave
the window open so that you can trace the expression as it changes value from trap
to trap (or when you change the current context by double-clicking in the call stack).
Like other views involved with variables, Expression View has variable change
indicators for value fields that let you see previous values, as shown in the following
figure:

007–2579–006

103

7: Viewing Program Data

Change
indicators

Figure 7-4 Change Indicator in Expression View

Another useful technique is to save your expressions to a file for later reuse. To save
expressions, select the following from the Main View menu bar:
Config
Save Expressions
To load expressions, select the following from the Main View menu bar:
Config
Load Expressions

104

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Assigning Values to Variables
To assign a value to a variable, click the left column of the Expression View window
and enter the variable name. The current value appears in the right column. If this
Result field is editable (highlighted), you can click it and enter a new value or legal
expression. Press Enter to assign the new value. You can perform an assignment to
any expression that evaluates to a legal lvalue (in C). The C operator “=” is not
valid in Expression View. Valid expression operations are shown in the following
paragraphs.

Evaluating Expressions in C
The valid C expressions are shown in Table 7-1.

Table 7-1 Valid C Operations

Operation
Arithmetic1
Arithmetic (binary)
Logical
Relational
Bit
Dereference
Address
Array indexing
Conditional

Symbol
+ - ++ -+- */ %
&& || !
< > <= >= == !=
& | ^ << >> ~
*
&
[]
? :

Unary - increment and decrement do not have side-effects

007–2579–006

105

7: Viewing Program Data

Operation
Member extraction2
Assignment3

Symbol
. ->
= += -= /= %= >>= <<= &= ^= |=

Sizeof
Type-cast
Function call
C Function Calls

Function calls can be evaluated in expressions, as long as enough actual parameters
are supplied. Arguments are passed by value. Following the rules of C, each actual
parameter is converted to a value of the same type as the formal parameter, before
the call. If the types of the formal parameters are unknown, integral arguments are
widened to full words, and floating-point arguments are converted to doubles.
Functions may return pointers, scalar values, unions, or structs. Note that if the
function returns a pointer into its stack frame (rarely a good programming practice),
the value pointed to will be meaningless, since the temporary stack frame is
destroyed immediately after the call is completed.
Function calls may be nested. For example, if your program contains a successor
function succ, the Debugger will evaluate the expression succ(succ(succ(3))) to
6.

Evaluating Expressions in C++
C++ expressions may contain any of the C operations. You can use the word this to
explicitly reference data members of an object in a member function. When stopped
in a member function, the scope for this is searched automatically for data
members. Names may be used in either mangled or de-mangled form. Names
qualified by class name are supported (for example, Symbol::a).

2
3

106

These operations are interchangeable.
A new assignment is made at each stepping point. Use Assignments with caution to avoid inadvertently modifying
variables.
007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

If you wish to look at a static member variable for a C++ class, you need not specify
the variable with the class qualifier if you are within the context of the class. For
example, you would specify myclass::myvariable for the static variable
myvariable outside of class myclass and myvariable inside myclass.
Limitations

Constructors may be called from Expression View, just like other member functions.
To call a constructor, you must pass in a first argument that points to the object to be
created. C++ function calls have the same possibility of side effects as C functions.

Evaluating Expressions in Fortran
You can enter any Fortran expression under the Expression heading and its current
value will appear in the same row under the Results column. Fortran expressions
may contain any of the arithmetic, relational, or logical operators. Relational and
logical operator keywords may be spelled in upper case, lower case, or mixed case.
The usual forms of Fortran constants, including complex constants, may be used in
expressions. String constants and string operations, however, are not supported. The
operators in Table 7-2 are supported on data of integer, real, and complex types.

Table 7-2 Valid Fortran Operations

Operation
Arithmetic (unary)
Arithmetic (binary)
Logical
Relational
Array indexing

Symbol
-+
- + * / **
.NOT. .AND. .OR. .XOR. .EQV .NEQV.
.GT. .GE. .LT. .LE. .EQ. .NE.
()

Intrinsic function calls (except
string intrinsics)

007–2579–006

107

7: Viewing Program Data

Operation

Symbol

Function subroutine calls
Assignment4

Fortran Variables

Names of Fortran variables, functions, parameters, arrays, pointers, and arguments
are all supported in expressions, as are names in common blocks and equivalence
statements. Names may be spelled in upper case, lower case, or mixed case.
Fortran Function Calls

The Debugger evaluates function calls the same way that compiled code does. If it
can be, an argument is passed by reference; otherwise, a temporary expression is
allocated and passed by reference. Following the rules of Fortran, actual arguments
are not converted to match the types of formal arguments. Side effects can be caused
by Fortran function calls. A useful technique to protect the value of a parameter from
being modified by a function subroutine is to pass an expression such as
(parameter + 0)instead of just the parameter name. This causes a reference to a
temporary expression to be passed to the function rather than a reference to the
parameter itself. The value is the same.

108

A new assignment is made at each stepping point. Use assignments with caution to avoid inadvertently modifying
variables.
007–2579–006

Chapter 8

Debugging with Fix+Continue

Fix+Continue allows you to make changes to a C/C++ program you are debugging
without having to recompile and link the entire program. With Fix+Continue you can
edit a function, parse the new function, and continue execution of the program being
debugged.
Fix+Continue is an integral part of the Debugger. You issue Fix+Continue commands
graphically from the Fix+Continue submenu of the Main View window, or from the
cvd command line prompt in the Command/Message pane of the Main View
window.
This chapter provides an introduction to the Fix+Continue functionality as well as a
tutorial to demonstrate many of the Fix+Continue functions.

Introduction to Fix + Continue
The following sections give you an overview to Fix+Continue functionality.

Fix+Continue Functionality
Fix+Continue lets you perform the following activities:
• Redefine existing function definitions.
• Disable, re-enable, save, and delete redefinitions.
• Set breakpoints in redefined code.
• Single-step within redefined code.
• View the status of changes.
• Examine differences between original and redefined functions.
A typical Fix+Continue cycle proceeds as follows:
1. You redefine a function with Fix+Continue. When you continue executing the
program, the Debugger attempts to call the redefined function. If it cannot, an
information pop-up window appears and the redefined function will be executed
the next time the program calls that function.
007–2579–006

109

8: Debugging with Fix+Continue

2. You redefine other functions, alternating between debugging, disabling,
re-enabling, and deleting redefinitions. You might save function redefinitions to
their own files, or save files to a different name, to be used later with the present
or with other programs.
During debugging you can review the status of changes by listing them, showing
specific changes, or looking at the Fix+Continue Status View. You can compare
changes to an individual function or to an entire file with the compiled versions.
When you are satisfied with the behavior of your application, save the changed file as
a replacement for the compiled source.

Fix+Continue Integration with Debugger Views
Fix+Continue interacts with the following Views:
• The Views main view, the Source View, and Fix+Continue Status windows
distinguish between compiled and redefined code, and allow editing in redefined
code.
• The following status windows elements work with redefined code:
– Call Stack window
– Trap Manager
– Debugger command line

How Redefined Code Is Distinguished from Compiled Code
Redefined functions have an identification number and special line numbers. They are
color-coded according to their state (that is, edited, parsed, and so on).
Line numbers in the compiled file stay the same, no matter how redefined functions
change. However, when you begin editing a function, the line numbers of the
function body are represented in decimal notation (n.1, n.2, ..., n.m), where n is the
compiled line number where the function body begins, and m is the line number
relative to the beginning of the function body, starting with the number 1.
The Call Stack window and the Trap Manager functions both use function-relative
decimal notation when referring to a line number within the body of a redefined
function.

110

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

The Debugger command line reports ongoing status. In addition to providing the
same commands available from the menu, edit commands allow you to add, replace,
or delete lines from files. Therefore, you can operate on several files at once.

The Fix+Continue Interface
You can access Fix+Continue through the Fix+Continue menu. It includes three
supporting windows: Status, Message, and Build Environment. These windows are
part of Fix+Continue, and do not operate unless it is installed.

Debugger with Fix+Continue Support
Without Fix+Continue, the Debugger source views are Read-Only by default. That is
so you can examine your files with no risk of changing them. When you select Edit
from the Fix+Continue menu, the Debugger source code status indicator (in the
lower-right corner of the Debugger window) remains Read-Only. This is because
edits made using Fix+Continue are saved in an intermediate state. Instead, you must
choose Save File > Fixes As to save your edits.
When you edit a function, it is highlighted in color; and if you switch to the compiled
version of your code, the color changes to show that the function has been redefined.
If you try to edit the compiled version of your code, the Debugger beeps indicating
Read-Only status.
When you have completed your edits and want to see the results, select Parse and
Load. When the parse and load has executed successfully, the color changes again. If
the color does not change, there may be errors: check the Message Window.

Change ID, Build Path, and Other Concepts
The Fix+Continue features finding files and accessing functions through ID numbers
as follows:
• Each redefined function is numbered with a change ID. Its status may be shown as
redefined, enabled, disabled, deleted, or detached.
• Fix+Continue needs to know the location of include files and other parameters
specified by compiler build flags. You can set the build environment for all files or
for a specific file. You can display the current build environment from the

007–2579–006

111

8: Debugging with Fix+Continue

Fix+Continue menu, the command line, or the Fix+Continue Status Window.
When you finish a Fix+Continue session, you can unset the build environment.
• Output from a successful run is displayed in the Execution View. This
functionality is the same as it is in the Debugger without Fix+Continue.

Restrictions on Fix+Continue
Fix+Continue has the following restrictions:
• When you work with C code, you must use the -o32 compiler option.
• Fix+Continue does not support C++ templates.
• You may not add, delete, or reorder local variables in a function.
• You may not change the type of a local variable.
• You may not change a local variable to be a register variable and vice- versa.
• You may not add any function calls that increase the size of the parameter area.
• You may not add an alloca function to a frame that did not previously use an
alloca function.
• Both the old and new functions must be compiled with the -g option.
In other words, the layout of the stack frames of both the old and new functions
must be identical for you to continue execution in the function that is being
modified. If not, execution of the old function continues and the new function is
executed the next time the function is called.
• If you redefine functions that are in but not on top of the call stack, the modified
code will not be executed when they combine. Modified functions will be
executed only on their next call or on a rerun.
For example, consider the following call stack:
foo()
bar()
foobar()
main()

112

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

– If you redefine foo(), you can continue execution, provided that the layout of
the stack frames are the same.
– If you redefine main() after you have begun execution, the redefined main()
will be executed only when you rerun.
– If you redefine bar() or foobar(), the new code will not be executed when
foo() returns. It will be executed only on the next call of bar() or foobar().

Fix+Continue Tutorial
This tutorial illustrates several features of Fix+Continue. The demo files included in
/usr/demos/WorkShop/time1 contain the complete C++ source code for the
program time1. Use this program for your tutorial. Here you will see how
Fix+Continue can modify functions without recompiling and linking the entire
program.
This section contains the following subsections:
• "Setting up the Sample Session", page 113.
• "Redefining a Function: time1 Program", page 114.
• "Setting Breakpoints in Redefined Code", page 121.
• "Viewing Status", page 123.
• "Comparing Original and Redefined Code", page 123.
• "Ending the Session", page 126.

Setting up the Sample Session
For this tutorial, use the demo files in the /usr/demos/WorkShop/time1 directory
that contains the complete source code for the C++ application time1. To prepare for
the session, you must create the fileset and launch Fix+Continue from the Debugger
as shown below:
1. Enter the following commands:
% mkdir demos/time1
% cd demos/time1
% cp /usr/demos/WorkShop/time1/* .
007–2579–006

113

8: Debugging with Fix+Continue

% make time1
% cvd time1 &

The cvd command brings up the Debugger, from which you can use the
Fix+Continue utility. The Execution View icon and the Main View window
appear. Note that the Debugger shows a source code status indicator of (Read
Only).
2. Open the Execution View window and position it next to the Main View window.
3. Click Run to run time1.
The Execution View shows the program output (see Figure 8-1).

Figure 8-1 Program Results in Execution View

Redefining a Function: time1 Program
In this section, you will do the following in the time1 program:
• Edit a C/C++ function.
• Change the code of an existing C/C++ function and then parse and load the
function, rebuilding your program to see the effect of your changes on program
output (without recompiling).

114

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

• Save the changed function to its own separate file.
Editing a Function

Perform the following in the Debugger Main View window (the time1 program
should be displayed) to edit a function:
1. Selecting the following from the Main View window menu bar to show line
numbers:
Display
Show Line Numbers
2. Click on the source annotation column to the left of line 17 to set a breakpoint at
that point.
3. Set a breakpoint at line 20 from the cvd command line as follows:
cvd> stop at 20

4. Click on the Run button to execute the program.
The following output appears in the Execution View window:
First printing of time:
08:20:50
***************
Second printing of time:

5. Enter the following at the cvd command line to choose a class member function
to edit (in this case, printTime, a C++ member function of class Time):
cvd> func Time::printTime

This command opens the time1/time1.c file, which contains the
implementation of class Time. The cursor is placed at the beginning of the
printTime function. (See Figure 8-2, page 116.)

007–2579–006

115

8: Debugging with Fix+Continue

Note: The syntax of the func command is as follows:
• For C++ class member functions:
cvd> func className::classMemberFunction

• For all other C/C++ functions:
cvd> func functionName

Figure 8-2 Selecting a Function for Redefinition

6. Select the following option from the menu bar to highlight the function to be
edited:
Fix+Continue
Edit
Note: You can also use Alt-Ctrl-e to perform this task.
Note the results as shown in Figure 8-3, page 117. Line numbers changed to a
decimal notation based on the first line number of the function body. The
function body highlights to show that it is being edited. The line numbers of the
rest of the file are not affected.

116

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Line number
notation

Highlight

Figure 8-3 Redefined Function

Changing Code

1. To change the time output as shown in Step 5 in "Editing a Function", page 115,
delete the 0 from "0" in line 23.2.
2. Select the following option from the menu bar to parse the modified function and
load it for execution:
Fix+Continue
Parse And Load
An icon for the Fix+Continue Error Messages window displays; and the
following message appears in the cvd window:
Change id: 1 modified

Note: You can also use Alt-Ctrl-x to perform this task.
If there are errors:
a.

Go to the error location(s) by double-clicking the related message line in the
Fix+Continue Error Messages window.

Correct the errors.

Repeat steps 1 and 2.

Continue to step 3 when you see the change ID and the following messages:
Change id: 1 redefined
Change id: 1 saved func
Change id: 1 file not saved

007–2579–006

117

8: Debugging with Fix+Continue

Change id: 1 modified

Note: The new function value is not active until the function is called.
3. Click on the Continue button to continue program execution.
The following output appears in the Execution View window:
Second printing of time:
8:20:50
***************

Notice how the time printout has changed from 08:20:50 to 8:20:50.
Deleting Changed Code

To cancel any of your changes, you must bring up the source file in which the change
was made and perform the following steps:
1. Enter the following at the cvd command line:
cvd> func Time::printTime

2. Select the following option from the menu bar to delete your changes:
Fix+Continue
Delete Edits
The Verify before deleting dialog displays.
3. Click OK in the Verify before deleting dialog.
Your deletion is complete.
Changing Code from the Debugger Command Line

You can redefine a C++ class member function from the Debugger command line as
follows:
1. Click on the Kill button in the Main View window.

118

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

2. Click on the Run button to re-run the program.
3. Choose a class member function (in this case, printTime) to edit by entering the
following at the cvd command line:
cvd> func Time::printTime

4. Use the redefine command to edit the function:
cvd> redefine Time::printTime

Note the results as shown in Figure 8-3, page 117. Here, line numbers have
changed to decimal notation based on the first line number of the function body.
Note also that the command line prompt has changed.
5. Enter the following at the prompt:
"/path/name/time1.C":23.1> .

6. Change the function source by entering the following at the command line:
cvd> replace_source "time1.C":23.2
"time1.C:23.2> cout << (hour < 10 ? "" : "") << hour << ":"
"time1.C:23.3> .

Parse and Load is executed at this point. You exit out of the function edit mode
are return to the main source code. The following messages appear in the
command/message pane:
Change
Change
Change
Change
Change

id:
id:
id:
id:
id:
2

2
2
2
2
2

redefined
save func
file not saved
modified
, build results:
enabled .../time1.C Time::printTime(void)

Note: 2 in these messages is the redefined function ID. You will use this ID in the
procedure in "Switching between Compiled and Redefined Code", page 123. The
new function value is not active until the function is called.
7. Continue execution by entering the following command at the cvd command line:
cvd> continue

007–2579–006

119

8: Debugging with Fix+Continue

The following displays in the Execution View window:
Second printing of time:
8:20:50
***************

If you prefer to use the command line, experiment with add_source and other
commands that give you the same functionality described for the menu commands.
For details on each command, see "Debugger Command Line", page 317.
Saving Changes

Your original source files are not updated until the changed source file is saved. You
could save redefined function changes to the time1.C file. However, if you did, the
file would not match the tutorial. So perform the following steps:
1. Enter the following command:
cvd> func Time::printTime

2. Select the following from the menu bar:
Fix+Continue
Save As
A file_name dialog box opens.
3. The dialog box enables you to save your file changes back to the original source
files or save them to a different file. However, since you do not want to save your
changes, press the Cancel button on the bottom of the dialog box.
Note: You usually want to wait until you are finished with Fix+Continue before you
save your changes. In addition to the method described above, you can also save
your changes by selecting the following:
Fix+Continue
Save All Files

120

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Setting Breakpoints in Redefined Code
To see how the Debugger works with traps in redefined code, this section shows you
how to set breakpoints, run the Debugger, and view the results (Figure 8-4, page 122).
1. Reset to the beginning of program execution by entering the following at the cvd
command line:
cvd> kill
cvd> run

2. Bring up the time1.C source file by entering the following at the cvd command
line:
cvd> func Time::printTime

3. Select the following from the menu bar:
Fix+Continue
Edit
Note: You can also use the Alt-Ctrl-e accelerator to perform this task.
4. Enter the following after line 23.4 in the source pane of the Main View window:
cout << " AM"<< endl;

5. Select the following from the menu bar:
Fix+Continue
Parse And Load
6. Bring up the time1.C source file again by entering the following command at
the cvd command line:
cvd> func Time::printTime

7. Set a breakpoint at line 23.6 by entering the following message at the cvd
command line:
cvd> stop at 23.6

The following message appears in the Command/Message pane:
[2] Stop at file /path/name/time1.C line 23.6
007–2579–006

121

8: Debugging with Fix+Continue

8. Click on the Cont button in the Main View window.
The following figure shows how the breakpoint has been reached in the redefined
code:

Figure 8-4 Stopping after Breakpoints in Redefined Code

9. Select the following from the menu bar to see the results of continuing to the
breakpoint:

122

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Views
Call Stack
10. Select the following from the menu bar to view the locations of the breakpoints:
Views
Trap Manager
11. Remove the breakpoint by clicking on the source annotation column to the right
of line 23.6.

Viewing Status
To view status, select the following from the menu bar:
Fix+Continue
View
Status Window
The Fix+Continue Status window opens.

Comparing Original and Redefined Code
You can use Fix+Continue to compare original code with and modified code. This
section shows you several ways to view your changes.
Switching between Compiled and Redefined Code

Follow these steps to see how the redefined code affects your executable:
1. Click the Run button to view your redefined code. If you are following
procedures in order in this section, you should see the following display:
8:20:50 AM

2. Enter the following at the cvd command line:
cvd> func Time::printTime

3. Select the following from the menu bar:

007–2579–006

123

8: Debugging with Fix+Continue

Fix+Continue
Parse and Load
4. Select the following from the menu bar to disable your changes:
Fix+Continue
Edited<–>Compiled
5. Click the Continue button to see the printing of Time as in the original
executable. The following displays:
08:20:50

6. Re-enter the following at the cvd command line:
cvd> func Time::printTime

7. Select the following from the menu bar to re-enable your changes:
Fix+Continue
Edited<–>Compiled
8. Click on the Run button to see the changed printout of Time. The following
displays:
08:20:50 AM

Comparing Function Definitions

1. Place the cursor in the time1.C function.
2. Select the following from the menu bar:
Fix+Continue
Show Difference
For Function
A window opens to display an xdiff comparison of the files as follows:

124

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 8-5 Comparing Compiled and Redefined Function Code

You can get the same result by entering the show_diff # command from the
Debugger command line, where # is the redefined function ID.
If you do not like xdiff, you can change the comparison tool by selecting the
following from the menu bar:
Fix+Continue
Show Difference
Set Diff Tool
Comparing Source Code Files

If you have made several redefinitions to a file, you may need a side-by-side
comparison of the entire file. To see how changes to the entire file look, select the
following from the menu bar:

007–2579–006

125

8: Debugging with Fix+Continue

Fix+Continue
Show Difference
For File
This opens an xdiff window that displays the entire file rather than just the function.
You can get the same comparison results from the Debugger command line if you
enter the following command:
show_diff -file time1.C

Ending the Session
Exit the Debugger by selecting the following from the menu bar:
Admin
Exit

126

007–2579–006

Chapter 9

Detecting Heap Corruption

The heap is a portion of memory used to support dynamic memory
allocation/deallocation via the malloc and free function. This chapter describes
heap corruption detection and covers the following topics:
• "Typical Heap Corruption Problems", page 127
• "Finding Heap Corruption Errors", page 128
• "Heap Corruption Detection Tutorial", page 131

Typical Heap Corruption Problems
Due to the dynamic nature of allocating and deallocating memory, the heap is
vulnerable to the following typical corruption problems:

007–2579–006

boundary overrun

A program writes beyond the malloc region.

boundary underrun

A program writes in front of the malloc region.

access to uninitialized
memory

A program attempts to read memory that has not yet
been initialized.

access to freed memory

A program attempts to read or write to memory that
has been freed.

double frees

A program frees some structure that it had already
freed. In such a case, a subsequent reference can pick up
a meaningless pointer, causing a segmentation violation.

erroneous frees

A program calls free() on addresses that were not
returned by malloc, such as static, global, or automatic
variables, or other invalid expressions.

127

9: Detecting Heap Corruption

See the malloc(3f) man page for more information.

Finding Heap Corruption Errors
To find heap corruption problems, you must relink your executable with the
-lmalloc_ss library instead of the standard -lmalloc library. By default, the
-lmalloc_ss library catches the following errors:
• malloc call failing (returning NULL)
• realloc call failing (returning NULL)
• realloc call with an address outside the range of heap addresses returned by
malloc or memalign
• memalign call with an improper alignment
• free call with an address that is improperly aligned
• free call with an address outside the range of heap addresses returned by
malloc or memalign
If you also set the MALLOC_FASTCHK environment variable, you can catch these errors:
• free or realloc calls where the words prior to the user block have been
corrupted
• free or realloc calls where the words following the user block have been
corrupted
• free or realloc calls where the address is that of a block that has already been
freed. This error may not always be detected if the area around the block is
reallocated after it was first freed.

Compiling with the Malloc Library
You can compile your executable from scratch as follows:
% cc -g -o targetprogram targetprogram.c -lmalloc_ss

You can also relink it by using:
% ld -o targetprogram targetprogram.o -lmalloc_ss ...

128

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

An alternative to rebuilding your executable is to use the _RLD_LIST environment
variable to link the -lmalloc_ss library. See the rld(1) man page.

Setting Environment Variables
After compiling, invoke the Debugger with your executable as the target. In
Execution View, you can set environment variables to enable different levels of heap
corruption detection from within the malloc library, as follows:
MALLOC_CLEAR_FREE
Clears data in any memory allocation freed by free. It requires that
MALLOC_FASTCHK be set.
MALLOC_CLEAR_FREE_PATTERN pattern
Specifies a pattern to clear the data if MALLOC_CLEAR_FREE is
enabled. The default pattern is 0xcafebeef for the 32-bit version,
and 0xcafebeefcafebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
MALLOC_CLEAR_MALLOC
Clears data in any memory allocation returned by malloc. It
requires that MALLOC_FASTCHK be set.
MALLOC_CLEAR_MALLOC_PATTERN pattern
Specifies a pattern to clear the data if MALLOC_CLEAR_MALLOC is
enabled. The default pattern is 0xfacebeef for the 32-bit version,
and 0xfacebeeffacebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
MALLOC_FASTCHK
Enables additional corruption checks when you call the routines in
this library. Error detection is done by allocating a space larger than
the requested area, and putting specific patterns in front of and
behind the area returned to the caller. When free or realloc is
called on a block, the patterns are checked, and if the area was
overwritten, an error message is printed to stderr using an internal
call to the routine ssmalloc_error. Under the Debugger, a trap
may be set at exit from this routine to catch the program at the error.

007–2579–006

129

9: Detecting Heap Corruption

MALLOC_MAXMALLOC n
Where n is an integer in any base, sets a maximum size for any
malloc or realloc allocation. Any request exceeding that size is
flagged as an error, and returns a NULL pointer.
MALLOC_NO_REUSE
Specifies that no area that has been freed can be reused. With this
option enabled, no actual free calls are made and process space and
swap requirements can grow quite large.
MALLOC_TRACING
Prints out all malloc events including address and size of the
malloc or free. When running a trace in the course of a
performance experiment, you need not set this variable because
running the experiment automatically enables it. If the option is
enabled when the program is run independently, and the
MALLOC_VERBOSE environment variable is set to 2 or greater, trace
events and program call stacks are written to stderr.
MALLOC_VERBOSE
Controls message output. If set to 1, minimal output displays; if set to
2, full output displays.
For further information, see the malloc_ss(3) man page.

Trapping Heap Errors Using the Malloc Library
If you are using the -lmalloc_ss library, you can use the Trap Manager to set a
stop trap at the exit from the function ssmalloc_error that is called when an error
is detected. Errors are detected only during calls to heap management routines, such
as malloc() and free(). Some kinds of errors, such as overruns, are not detected
until the block is freed or realloced.
When you run the program, the program halts at the stop trap if a heap corruption
error is detected. The error and the address are displayed in Execution View. You
can also examine the Call Stack at this point to get stack information. To find the
next error, click the Continue button.
If you need more information to isolate the error, set a watchpoint trap to detect a
write at the displayed address. Then rerun your program. Use
130

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

MALLOC_CLEAR_FREE and MALLOC_CLEAR_MALLOC to catch problems from
attempts to access uninitialized or freed memory.
Note: You can run programs linked with the -lmalloc_ss library outside of the
Debugger. The trade-off is that you have to browse through the stderr messages
and catch any errors through visual inspection.

Heap Corruption Detection Tutorial
This tutorial demonstrates how to detect corruption errors by using the corrupt
program. The corrupt program has already been linked with the SpeedShop
malloc library (libmalloc_ss). The corrupt program listing is as follows:
#include
void main (int argc, char **argv)
{
char *str;
int **array, *bogus, value;
/* Let us malloc 3 bytes */
str = (char *) malloc(strlen(‘‘bad’’));
/* The following statement writes 0 to the 4th byte */
strcpy(str, ‘‘bad’’);
free (str);
/* Let us malloc 100 bytes */
str = (char *) malloc(100);
array = (int **) str;
/* Get an uninitialized value */
bogus = array[0];
free (str);
/* The following is a double free */
free (str);
/* The following statement uses the uninitialized value as a pointer */
value = *bogus;

007–2579–006

131

9: Detecting Heap Corruption

}

To start the tutorial:
1. Enter the following:
%
%
%
%

mkdir demos
mkdir demos/mallocbug
cd demos/mallocbug
cp /usr/demos/WorkShop/mallocbug/* .

2. Invoke the Debugger by typing:
% cvd corrupt &

The Main View window displays with corrupt as the target executable.
3. Open the Execution View window (if it is minimized) and set the
_SSMALLOC_FASTCHK and _SSMALLOC_CLEAR_MALLOC environment variables.
If you are using the C shell, type:
% setenv _SSMALLOC_FASTCHK
% setenv _SSMALLOC_CLEAR_MALLOC

If you are using the Korn or Bourne shell, type:
$ _SSMALLOC_FASTCHK=
$ _SSMALLOC_CLEAR_MALLOC=
$ export _SSMALLOC_FASTCHK _SSMALLOC_CLEAR_MALLOC

4. To trap any malloc corruption problems, you must enter the following at the
cvd command line:
cvd> set $pendingtraps=true
cvd> stop exit ssmalloc_error

A stop trap is set at the exit from the malloc library ssmalloc_error.
5. Enter the following at the cvd command line:
cvd> run

The program executes. Observe Execution View as the program executes.

132

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

A heap corruption is detected and the process stops at one of the traps. The type
of error and its address display in Execution View (see example in Figure 9-1,
page 133.)

Figure 9-1 Heap Corruption Warning Shown in Execution View

6. Select the following from the Main View window menu bar:
Views
Call Stack
Call Stack opens displaying the call stack frame at the time of the error (see
Figure 9-2).

007–2579–006

133

9: Detecting Heap Corruption

Figure 9-2 Call Stack at Boundary Overrun Warning

7. Click the Continue button in the Main View window’s control panel. Watch the
Execution View and Call Stack windows.
The process continues from the stop at the boundary overrun warning until it hits
the next trap where an erroneous free error occurs.
8. Click the Continue button again and watch the Execution View and Call Stack
windows.
This time the process stops at a bus error or segmentation violation. The PC stops
at the following statement because bogus was set to an uninitialized value:
value=*bogus

9. Enter p &bogus on the Debugger command line at the bottom of the Main View
window.
This gives us the address for the bogus variable and has been done in Figure 9-3,
page 135. We need the bad address so that we can set a watchpoint to find out
when it is written to. (This example has an address of 0x7fffaef4; your address
will be different.)

134

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Bus error data

PC at error line

Entry to get bad
address
Problem address
to be watched

Figure 9-3 Main View at Bus Error

10. Deactivate the stop trap by clicking the toggle button next to the trap description
in the Trap Manager window, and click the Kill button in the Main View window
to kill the process.
11. Click on the Clear button in the Trap Manager window.
12. Type the following command in the Trap field. This includes the address you
obtained from the Debugger command line (see Figure 9-3, page 135). This sets a
watchpoint that is triggered if a write is attempted at that address.
Note: Use the address from your system, not the one shown here.
stop watch address 0x7fffaef4 for write

007–2579–006

135

9: Detecting Heap Corruption

13. Click the Add button.
14. Click the Run button and observe the Main View window.
The process stops at the point where the bogus variable receives a bad value.
Details of the error display in the Main View window’s Status field.

136

007–2579–006

Chapter 10

Multiple Process Debugging

The WorkShop Debugger lets you debug threaded applications as well as programs
that use multiple processes spawned by fork or sproc. You can also control a single
process or all members of a process group, attach child processes, and specify that
spawned processes inherit traps from the parent process. The Trap Manager provides
special commands to facilitate debugging multiple processes by setting traps that
apply to the entire process group.
Note: The Multiprocess View window is for use by C, C++, and Fortran users. If
you are debugging Ada code, you should use the Task View window available
through the View menu of the Main View window (see "Task View", page 220).
Currently, Multiprocess View handles the following multiple process situations:
• True multiprocess program, which refers to a tightly integrated system of sproc’d
processes, generated by the MIPSpro Automatic Parallelization Option. For more
information on parallel processing, see the auto_p(5) man page, or the MIPSpro
Automatic Parallelizer Programmer’s Guide.
• Auto-fork application, which is a process that spawns a child process and then runs
in the background.
• Fork application, which is a process that spawns child processes and can interact
with them.
• Locally distributed application, which is an application that involves two different
executables running in different processes on the same host coordinated by a
rendezvous mechanism.
• MPI single system image application, which is an MPI application that runs on the
same host.
This chapter discusses the details of multiprocess debugging in WorkShop and
includes the following topics:
• "Using the Multiprocess View Window", page 138
• "Debugging a Multiprocess C Program", page 142
• "Debugging a Multiprocess Fortran Program", page 148
007–2579–006

137

10: Multiple Process Debugging

• "Debugging a Pthreaded Program", page 154
• "Debugging an MPI Single System Image Application", page 159

Using the

Multiprocess View

Window

The Multiprocess View window is brought up by selecting the following from the
menu bar of the Main View window:
Admin
Multiprocess View
This window can display individual processes or operate on a process group. By
default, a process group includes the parent process and all descendants spawned by
sproc. Processes spawned with fork during the session can be added to the process
group automatically when they are created. For a program compiled with the
MIPSpro Automatic Parallelization Option, a process group includes all threads
generated by the option. Any process to which you have read/write access can also
be added to the process group. All sproc’d processes must be in the same process
group, since they share information.
Note: Any child process that performs an exec with setuid (set user ID) enabled
will not become part of the process group.
Each process in the session can have a standard main view window session
associated with it. However, all processes in a process group appear on a single
Multiprocess View window.
When debugging multiprocess applications, you should disable the SIGTERM signal
by selecting the following from the Main View window menu bar:
Views
Signal Panel
Note: Although multiprocessing debugging is possible with SIGTERM enabled, the
multiprocess application may not terminate gracefully after execution is complete.

138

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Starting a Multiprocess Session
The first step in debugging multiple processes is to invoke the Debugger with the
parent process. Then select the following from the menu bar:
Admin
Multiprocess View
The following figure shows a typical Multiprocess View window.

Multiprocess
control area

Process
display area

Figure 10-1 Multiprocess View

Viewing Process Status
The process display area of the Multiprocess View lists the status of all processes and
threads in the process group. For definitions of the various status and states, see
"Status of Processes".
To get more information about a process or thread displayed in the process display
area, right-click on the process or thread entry. A Process menu pops up which is
applicable to the selected entry. From this menu you can do the following:
• change entry focus
• create a new window

007–2579–006

139

10: Multiple Process Debugging

• focus attention to a user–entered thread
• show thread-specific details
• add or remove an entry
For complete details about the Process menu, see "Controlling Multiple Processes",
page 219.

Using Multiprocess View Control Buttons
The Multiprocess View window uses the same control buttons as the Main View
window with the following exceptions:
• Buttons are applied to all processes as a group.
• There are no Return, Print, or Run buttons.
Control buttons in the Multiprocess View window have the same effect as clicking
the corresponding button in the Main View window of each individual process. For
definitions of the buttons, see "Multiprocess View Control Buttons", page 211.

Multiprocess Traps
As discussed in Chapter 5, "Setting Traps", page 71, the trap qualifiers [all] and
[pgrp] are used in multiprocess analysis. The [all] entry stops or samples all
processes when a trap fires. The [pgrp] entry sets the trap in all processes within
the process group that contains the trap location. The qualifiers can be entered by
default by using the Stop All Default and Group Trap Default selections,
respectively, in the Traps menu of Trap Manager. The Trap Manager is brought up
from the Views menu of the Main View window.

Viewing Pthreaded Applications
The Multiprocess View supports a hierarchical view of your pthreaded applications.
Select the folder icons of your choosing to get more information about a process or
thread.
Perform the following from within the Multiprocess View window to get additional
information about a process or thread:
1. Double-click on a folder icon.
140

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

The process display expands to show its pthreads.
2. Double-click to select the pthread of your choosing.
The call stack for that thread displays.

Adding and Removing Processes
To add a process, select Add from the Process menu. In the Switch Dialog dialog
window, select one of the listed processes or enter a process ID in the Process ID field
and click the OK button.
To remove a process, click on the process name in the Multiprocess View window
and select Remove from the Process menu. Be aware that a process in a sproc
process group cannot be removed. Likewise, you cannot remove a pthread from a
pthread group.

Multiprocess Preferences
The Preferences option in the Config menu brings up the Multiprocess View
Preferences dialog. The preferences on this dialog lets you determine when a process
is added to the group, specify process behavior, specify the number of call stack levels
to display, and so forth.
For details about Multiprocess View Preference options, see "Controlling
Preferences", page 212.

Bringing up Additional Main View Windows
To create a Main View window for a process, highlight that process in the
Multiprocess View window. Then, select the following in the Multiprocess View
window:
Process
Create new window

007–2579–006

141

10: Multiple Process Debugging

Debugging a Multiprocess C Program
This section uses a C program that generates numbers in the Fibonacci sequence to
demonstrate the following tasks when using the debugger to debug multiprocess code:
• Stopping a child process on a sproc
• Using the buttons in the Multiprocess View window
• Setting traps in the parent process only
• Setting group traps
The fibo program uses sproc to split off a child process, which in turn uses sproc
to split off a grandchild process. All three processes generate Fibonacci numbers until
stopped. You can find the source for fibo.c in the /usr/demos/WorkShop/mp
directory. A listing of the fibo.c source code follows:
#include
#include
#include
int NumberToCompute = 100;
int fibonacci();
void run(),run1();
int fibonacci(int n)
{
int f, f_minus_1, f_plus_1;
int i;
f = 1;
f_minus_1 = 0;
i = 0;
for (; ;) {
if (i++ == n) return f;
f_plus_1 = f + f_minus_1;
f_minus_1 = f;
f = f_plus_1;
}
}

142

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

void run()
{
int fibon;
for (; ;) {
NumberToCompute = (NumberToCompute + 1) % 10;
fibon = fibonacci(NumberToCompute);
printf("%d’th fibonacci number is %d\n",
NumberToCompute, fibon);
}
}
void run1()
{
int grandChild;
errno = 0;
grandChild = sproc(run,PR_SADDR);
if (grandChild == -1) {
perror("SPROC GRANDCHILD");
}
else
printf("grandchild is %d\n", grandChild);
run();
}
void main ()
{
int second;
second = sproc(run1,PR_SADDR);
if (second == -1)
perror("SPROC CHILD");
else
printf("child is %d\n", second);
run();
exit(0);
}

007–2579–006

143

10: Multiple Process Debugging

Launch the Debugger in Multiprocess View
Perform the following to start, compile the program, and run the Debugger:
1. Copy the program source from the demo directory as follows:
% cp /usr/demos/WorkShop/mp .

2. Compile fibo.c by entering the following command:
% cc -g fibo.c -o fibo

3. Invoke the Debugger on fibo as follows:
% cvd fibo &

4. Call up the Multiprocess View by selecting the following from the Main View
menu bar:
Admin
Multiprocess View
The next section uses the fibo program to illustrate some of the functionality of the
Multiprocess window.

Using Multiprocess View to Control Execution
To examine each process as it is created, you must set preferences so that each child
process created stops immediately after being created. The following steps show how
this can be done:
1. Select the following from the menu bar in the Multiprocess View window:
Config
Preferences
2. Toggle off Resume child after attach on sproc in the Multiprocess View
Preferences window.
3. Toggle off Copy traps to sproc’d processes so you can experiment with setting
traps later.
4. Click on the OK button to accept the changes.
5. Click on the Run button in the Main View window to execute the fibo program.
144

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Watch the Multiprocess View window, you will see the main process appear and
spawn a child process, which stops as soon as it appears. This is because you
turned off the Resume child after attach on sproc option. Notice also that the
Main View window switched to the stopped child process.
6. Click on the Stop button in the Multiprocess View window.
The control buttons on the Multiprocess View window may be used to control all
processes simultaneously, or the control buttons on any Main View window may
be used to control that individual process separately.
7. Click on the first line (that is, the main process) in the process pane of the
Multiprocess View window to highlight this line.
8. Select the following from the menu bar of the Multiprocess View window:
Process
Create new window
A new Main View window displays with a debug session for the main process.
Note: You may get a warning that .../write.s is missing. This refers to assembly
code and can be ignored. The new Main View window will not have source in its
source pane.
9. Select the following from the menu bar of the Main View window you just
created to create a Call Stack window:
Views
Call Stack
10. Double-click on the line in the Call Stack window that contains run (). This
brings up the fibo.c source for the main process in the Main View window.
11. Select the following from within the Call Stack window to close it:
Admin
Close
12. Click on Cont in the Multiprocess View window. The first child, created in Step
5, now spawns a grandchild process that stops in _nsproc, as shown here:

007–2579–006

145

10: Multiple Process Debugging

Note: A Main View window switches to the new stopped process.

Figure 10-2 Examining Process State Using Multiprocess View

13. Click on Stop in the Multiprocess View window.
14. Repeat steps 7 through 11 to bring up a Main View window for the parent process.

Using the Trap Manager to Control Trap Inheritance
Note: The instructions in this section assume that you have just run the tutorial in
"Using Multiprocess View to Control Execution", page 144.
This section shows you how to use the Trap Manager to set traps that affect one or all
processes in the fibo process group. For complete information on using the Trap
Manager, refer to Chapter 5, "Setting Traps", page 71.
1. Select the following from the Main View window for the parent process:

146

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Views
Trap Manager
Note: Traps are specific to the processes in the Main View window in which they
are set.
2. Select the following (from the same Main View window) to turn on line
numbering in the source pane, if not already showing:
Display
Show Line Numbers
3. Click to the left of line 32, to set a breakpoint/stop trap for the parent process.
Line 32 reads as follows:
32 Number to Compute = (NumberToCompute + 1) % 10

Line 32 highlights in red to indicate that a breakpoint has been set. A
corresponding trap command appears in the Trap text box in the Trap Manager
window; and the trap is added to the list on the Active Traps list of the same
window. Remember, this trap will affect only the parent process.
4. Click on the Cont button in the Multiprocess View window.
Note: The parent process has stopped, but the other processes are probably still
running.
5. Insert the word pgrp (that is, “process group”) after the word stop in the Trap
field of the Trap Manager window.
The trap should now read Stop pgrp at .... As the command suggests,
pgrp affects the whole process group.
6. Click on the Modify button.
The trap now affects two child processes. Watch the Multiprocess View window
to see the running processes in the process group stop at the trap on line 32.
7. Select the following from the Trap Manager window:

007–2579–006

147

10: Multiple Process Debugging

Traps
Group Trap Default
Note: Now, any additional traps that you set using the Trap Manager will affect
the entire process group. Any previously set traps will not be affected.
8. Select the text of line 23, found in the source pane of the Main View window
associated with the parent process. This line reads as follows:
23 f_minus_1 = f;

9. Select the following from the menu bar of the Trap Manager window:
Traps
At Source Line
The trap you have just set includes the modifier pgrp.
10. Select the following from any Main View window to close your session and end
this tutorial:
Admin
Exit

Debugging a Multiprocess Fortran Program
The section of this chapter presents a few standard techniques to assist you in
debugging a parallel program. This section shows you how to debug the sample
program.
See also Chapter 2, "Basic Debugger Usage", page 11 for important related information.

General Fortran Debugging Hints
Debugging a multiprocessed program is more involved than debugging a
single-processor program. Therefore, you should debug a single-processor version of
your program first and try to isolate the problem to a single parallel DO loop.
Once you have isolated the problem to a specific DO loop, change the order of
iterations in a single-processor version. If the loop can be multiprocessed, then the
148

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

iterations can execute in any order and produce the same answer. If it cannot be
multiprocessed, you will see that changing the order in which the loops execute will
cause the single-processor version to produce wrong answers. If wrong answers are
produced, you can use standard single-process debugging techniques to find the
problem. (See Chapter 2, "Basic Debugger Usage", page 11 for important related
information.)
If this technique fails, you must debug the multiprocessed version. To do this,
compile your code with the -g and -FLIST:=ON flags. The -FLIST:=ON flags save
the file containing the multiprocessed DO loop Fortran code in a file called
total.w2f.f and a file tital.rii and an rii_files directory.

Fortran Multiprocess Debugging Session
This section shows you how to debug a small segment of multiprocessed code.
The source code for this tutorial, total.f, can be found in the directory
/usr/demos/WorkShop/mp.
A listing of this code is as follows:
program driver
implicit none
integer iold(100,10), inew(100,10),i,j
double precision aggregate(100, 10),result
common /work/ aggregate
result=0.
call total(100, 10, iold, inew)
do 20 j=1,10
do 10 i=1,100
result=result+aggregate(i,j)
10
continue
20 continue
write(6,*)’ result=’,result
stop
end
subroutine total(n, m, iold, inew)
implicit none
integer n, m
integer iold(n,m), inew(n,m)
double precision aggregate(100, 100)
007–2579–006

149

10: Multiple Process Debugging

common /work/ aggregate
integer i, j, num, ii, jj
double precision tmp

C$DOACROSS LOCAL(i,ii,j,jj,num)
do j = 2, m-1
do i = 2, n-1
num = 1
if (iold(i,j) .eq. 0) then
inew(i,j) = 1
else
num = iold(i-1,j) +iold(i,j-1) + iold(i-1,j-1) +
iold(i+1,j) + iold(i,j+1) + iold(i+1,j+1)
if (num .ge. 2) then
inew(i,j) = iold(i,j) + 1
else
inew(i,j) = max(iold(i,j)-1, 0)
end if
end if
ii = i/10 + 1
jj = j/10 + 1
aggregate(ii,jj) = aggregate(ii,jj) + inew(i,j)
end do
end do
end

In the program, the local variables are properly declared. The inew always appears
with j as its second index, so it can be a share variable when multiprocessing the j
loop. The iold, m, and n are only read (not written), so they are safe. The problem is
with aggregate. The person analyzing this code deduces that, because j is always
different in each iteration, j/10 will also be different. Unfortunately, since j/10 uses
integer division, it often gives the same results for different values of j.
While this is a fairly simple error, it is not easy to see. When run on a single processor,
the program always gets the right answer. Sometimes it gets the right answer when
multiprocessing. The error occurs only when different processes attempt to load from
and/or store into the same location in the aggregate array at exactly the same time.
Debugging Procedure

Perform the following to debug this code:

150

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

1. Create a new directory for this exercise:
% mkdir demos/mp

2. cd to the new directory and copy the following program source into it:
% cp /usr/demos/WorkShop/mp .

3. Edit the total.f file in a shell editor, such as vi:
% vi total.f

4. Reverse the order of the iterations for demonstration purposes.
Replace
do j = 2, m-1

with
do j = m-1, 2, -1

This still produces the right answer with one process running, but the wrong
answer when running with multiple processes. The local variables look right,
there are no equivalence statements, and inew uses only simple indexing. The
likely item to check is aggregate. Your next step is to look at aggregate with
the Debugger.
5. Compile the program with -g option as follows:
% f77 -g -mp total.f -o total

6. If your debugging session is not running on a multiprocessor machine, you can
force the creation of two threads, for example purposes, by setting an
environment variable. If you use the C shell, type:
% setenv MP_SET_NUMTHREADS 2

Is you use the Korn or Bourne shell, type:
$ MP_SET_NUMTHREADS=2
$ export MP_SET_NUMTHREADS

7. Enter the following to start the Debugger:
% cvd total &

The Main View window displays.
007–2579–006

151

10: Multiple Process Debugging

8. Select the following from the Main View menu bar to show the line numbers:
Display
Show Line Numbers
9. Select the following from the Main View menu bar:
Source
Go To Line
And enter 44.
Line 44 is as follows:
aggregate(ii,jj) = aggregate(ii,jj) + inew(i,j)

10. You will now set a stop trap at this line, so you can see what each thread is doing
with aggregate, ii, and jj. You want this trap to affect all threads of the
process group. One way to do this is to turn on trap inheritance in the
Multiprocess View Preferences dialog. To open this dialog, select the following
from the Main View menu bar to open the Multiprocess View window:
Admin
Multiprocess View
Then, select the following from within the Multiprocess View window:
Config
Preferences
Another way is to use the Trap Manager to specify group traps, as follows.
a.

Select the following from the Main View window menu bar to open the Trap
Manager:
Views
Trap Manager

Select the following from the Trap Manager window:
Traps
Group Trap Default

11. Click-drag to select line 44 in the Main View window.

152

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

12. Open the Trap Manager window from the Main View window menu bar as
follows:
Views
Trap Manager
Then select the following from the the Trap Manager window:
Traps
At Source Line
This sets a stop trap that reads as follows in the cvd pane of the Main View
window:
Stop pgrp at file /usr/demos/WorkShop/mp/total.f line 44

13. Select the following from the menu bar in the Main View window to monitor
status of the two processes:
Admin
Multiprocess View
You are now ready to run the program.
14. Click the Run button in the Main View window.
As you watch the Multiprocess View, you see the two processes appear, run, and
stop in the function _mpdo_total_1. It is unclear, however, if the Main View
window is now relative to the master process, or that it has switched to the slave
process.
15. Right-click on the name of the slave process in the Multiprocess View window
and select the following:
Process
Create a new window
A new window is displayed that launches a debug session for the process. Now,
both master and slave processes should display in respective Main View windows.
16. Invoke the Variable Browser as follows from the Menu Bar of each process:

007–2579–006

153

10: Multiple Process Debugging

Views
Variable Browser
17. Look at ii and jj in the following figure.

Figure 10-3 Comparing Variable Values from Two Processes

They have the same values in each process; therefore, both processes may attempt
to write to the same member of the array aggregate at the same time. So
aggregate should not be declared as a share variable. You have found the bug
in your parallel Fortran program.

Debugging a Pthreaded Program
cvd supports the debugging of IRIX 6.4 and 6.5 pthreads. You can view pthread
creation and execution through the Multiprocess View window. Through this
window you can:
• View a hierarchal display of a threaded application
• View a process/pthread relationship
• Expand individual call stacks
C, C++, and Fortran users should use the Multiprocess View window when
debugging pthreads. Ada users should use the Task View window.

154

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

The next sections give hints on debugging pthreaded programs, list differences
between 6.4 and 6.5 threads, and illustrate how to debug a program that uses IRIX 6.5
pthreads.

User-Level Continue of Single 6.5 POSIX Pthread
The ability to “continue” or “free run” a single POSIX pthread under IRIX 6.5 is
available at the user level with WorkShop release 2.8. However, use of this new
debugging feature can, in certain specific circumstances, lead to anomalous and
possibly confusing behavior. Such behavior occurs when the single thread that is
continued or free run encounters either a “blocking” or “scheduling” situation in the
operating system or the pthreads library. When such situations arise, the operating
system (or, in some cases, the pthreads library) must take action to dispose of the
single continued or free run thread and, possibly, newly created threads. In the course
of this action the debugging user will see things occur, with both the single continued
or free run thread as well as all other threads, that will be perplexing because
complex thread scheduling algorithms are invoked by both the operating system and
the pthreads library to recover from the original blocking or scheduling incident. This
note attempts to provide information which might lessen frustration on the part of
the debugging user in the face of blocking or scheduling incidents. Debugging true
POSIX pthreads is tricky business, and users of this new feature, allowing a continue
or free run of a single 6.5 POSIX pthread, will gain even more appreciation of this fact.
This feature has been used internally for some time by the WorkShop debugger. The
continue or free run of a single 6.5 pthread is used each time a user requests a single
thread step-over of a function. The single thread is allowed to free run through the
function which is being stepped over. Thus, if any blocking or scheduling situations
occur in the course of this stepping over and associated free run of a single thread,
then anomalous behavior can, and does, occur. For example, when attempting to step
over a function call which eventually calls the routine pthread_create, the user
will see the step over succeed or not succeed in non-deterministic fashion due to
complex scheduling algorithms in the pthreads library. This is explained in greater
detail below in "Scheduling Anomalies", page 156.
As another example, when a single thread step over is requested of a routine which
does a printf somewhere down the call tree, the blocking operating system call
writev is eventually invoked and this can, and does, lead to anomalous behavior in
the eyes of the debugging user. This is explained in detail in"Blocking Anomalies",
page 157.

007–2579–006

155

10: Multiple Process Debugging

Scheduling Anomalies

Scheduling anomalies may occur when the single 6.5 POSIX pthread which is being
continued or free run creates a new pthread via call to routine pthread_create. At
the time of the call to pthread_create the OS kernel and the pthreads library get
into a complex algorithm in deciding how to give life to the new child pthread. An
actual OS kernel thread (OS kernel threads are not available at the user level — they
differ from the user level pthread) must be either created anew or found elsewhere to
support the user’s new child pthread.
First, let’s assume the OS kernel thread is to be found elsewhere, depending on a vast
number of things (for example, number of cpu’s, environment variables, and so on).
The OS kernel may (this is very non-deterministic) decide to just put the child pthread
on a ready queue, in need of an OS kernel thread. Thus the child does nothing right
away. Meanwhile if the parent pthread, via a call to routine pthread_cond_wait,
monitors the child pthread’s struggle for life, it (the parent) gets parked on a mutex
because the child obviously has not been born yet (remember, it’s on the ready
queue). The parent pthread’s OS kernel thread becomes available, which causes the
OS scheduler to check for work for this newly freed OS kernel thread. Behold, it finds
the child sitting in the ready queue and assigns the parent’s OS kernel thread to the
new child pthread. The child then runs to completion and releases its (parent’s old)
OS kernel thread. The parent, checking for the child’s new life via
pthread_cond_wait, now recaptures its OS kernel thread and things work fine in
the eyes of the debugging user.
Now, let’s assume the OS kernel thread required by the new child pthread must be
created anew. The child is not placed on the ’ready queue’. Again, this is a
non-deterministic decision which depends on a large number of variables (that is
number or cpu’s, and so on). The OS kernel creates a new OS kernel thread for the
child pthread and “engages” it (the child) to that new OS kernel thread. However,
“marriage” of the OS kernel thread and the new child pthread cannot occur until the
new OS kernel thread actually runs. This never occurs because, in allowing the single
parent 6.5 pthread to continue or run free, it was requested that only one user
pthread be run - the parent. If the parent, however, is using pthread_cond_wait to
monitor the new life of its child, then it (the parent) is parked on a mutex waiting for
the child to run. This is a Catch-22. The parent awaits the child but the child cannot
run because only one pthread, the parent, has been requested to run. The debugger
user, meanwhile, is not amused. The debugger displays “running” as the overall
status and this is because no events of interest are occurring. Everybody is waiting on
everybody else. Things are not working.

156

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Blocking Anomalies

Blocking anomalies occur when the single 6.5 POSIX thread which is being continued
or free run encounters a blocking condition in the course of its running. The notion of
blocking has three distinct flavors:
• Blocking syscalls in the OS kernel (see "Blocking Kernel System Calls", page 331
for a list). When one of these kernel syscalls is blocked by another thread’s usage,
the OS kernel decides what the next move is regarding the OS kernel thread
attached to the user pthread making the call. Control could just transfer to another
application, to disk I/O, or whatever. These syscalls are all I/O-related. The OS
kernel thread says, in effect, "I’m waiting for something to do -> I’m blocked", and
it is immediately available for reassignment. The best example of a blocking
kernel syscall is writev, which is used by the common library routine printf.
Thus, if a single 6.5 POSIX thread is continued or free run and it eventually calls
printf, the debugging user may see the anomalous behavior of another pthread
started running because the continued or free run 6.5 pthread was blocked in
writev. The printf pthread’s OS kernel thread is reassigned and another
pthread suddenly takes off.
• Various lock blocking in the pthread library, such as Mutex (mutual exchange
lock). This occurs in user space (libc, user code, and so on). The pthread library
sense that a pthread is going to block due to another pthread’s usage. Control
transfers to the routine usync_control which eventually calls a blocking kernel
syscall (see preceding item). Again, the OS kernel decides the fate of the
associated OS kernel thread. Unexpected things could start running.
• Other lock blocking in the pthread library, whereby the pthread library senses that
a user pthread is going to block but does not go off to usync_control. Instead it
goes to the pthread_scheduler in the pthread library for the disposition of the
associated OS kernel thread. The pthread_scheduler then reassigns the
associated OS kernel thread to another user pthread and unexpected things could
start running.
How to Continue a Single POSIX 6.5 Pthread

To continue (or free run) a single POSIX 6.5 pthread, simply click on the Continue
button in the Main View window. Note that this is different from the function of the
Continue button in the Multiprocess View window, which continues all threads.

007–2579–006

157

10: Multiple Process Debugging

Other Pthread Debugging Hints
Observe the following guidelines when debugging pthreaded programs:
• C++ exception handling works per process not per thread.
• Using the step over function on a pthread_exit may produce unexpected
results.
• Use Multiprocess View not Task View.
• Use WorkShop versus dbx for 6.5 pthread debugging whenever possible.
• Do not do a Next of printf.

Differences between 6.4 and 6.5 Pthreads
The following differences exist between the IRIX 6.4 and the IRIX 6.5 implementation
of pthreads:
• In the IRIX 6.5 implementation, many user threads are serviced by a few kernel
micro-threads. This can result in the following problems:
– After stopping at a breakpoint, a pthreaded program may abort with a
Trace/BPT trap error when you try to use the continue function.
– Data race problems may occur as kernel micro-threads switch from one user
pthread to another.
You can alleviate these problems with the following command:
ccall pthread_setconcurrency n

Where n is the number of kernel micro-threads made available to service user
threads. In this manner, you can increase the number of kernel micro-threads
available. However, you must not specify a value for n that is greater than the
number of physical CPUs on your system.
• The Multiprocess View window shows different sets of threads / processes
depending on which version of IRIX you are running. (This is because in IRIX
releases before IRIX 6.5, threads are handled as sprocs, not as threads.)

158

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Pthread Debugging Session
Pthread debugging is highly variable not only from environment to environment from
from IRIX release to IRIX release. Because of this, it is not possible to provide a
representative pthread debugging tutorial that can be used by all users.
See "User-Level Continue of Single 6.5 POSIX Pthread", page 155, Theory of 6.5
Pthreads, for an in depth description of current pthread implementation in IRIX.

Debugging an MPI Single System Image Application
cvd supports the debugging of a single system image MPI application. The
debugging session is set up so that initially mpirun is being debugged. The
following is the typical command line used to invoke cvd on an MPI application:
% cvd mpirun -args -np 2 MPI_app_name

This example command line indicates that the arguments -np 2 MPI_app_name will
be passed to mpirun and that cvd will initially be focused on the mpirun process.

007–2579–006

159

10: Multiple Process Debugging

Figure 10-4 Initial MPI start up screen display

An entry point into the MPI application can be used to set a pending trap (breakpoint)
in the MPI application. This breakpoint will be resolved when the Run button is
activated and the actual MPI application is running. If the breakpoint target is valid,
the MPI application will stop at the breakpoint and further debugging can be done.

160

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Figure 10-5 Reaching the MPI application breakpoint screen display

The use of the Multiprocess View for debugging MPI applications is very similar to
what has been presented in the previous sections of this chapter.
The current implementation does not filter out other processes created by login shells
so some extra processes may be shown in the Multiprocess View.

007–2579–006

161

Chapter 11

X/Motif Analyzer

This chapter provides an introduction to the X/Motif Analyzer as well as a tutorial to
demonstrate most of the Analyzer functions. The chapter contains the following
sections:
Motif is a library of routines that enable you to create user interfaces in an
X-environment. The Motif libraries handle most of the low-level event handling tasks
common to any GUI system. This way, you can create sophisticated interfaces
without having to contend with all of the complexity of X.
The X/Motif Analyzer helps you debug code that calls Motif library routines. The
X/Motif Analyzer is integrated with the Debugger so you can issue X/Motif
Analyzer commands graphically. To access X/Motif analyzer subwindow select the
following from the Main View window menu bar:
Views
X/Motif Analyzer

Introduction to the X/Motif Analyzer
The Analyzer contains X/Motif objects (for example, widgets and X graphics
contexts) that can be difficult or impossible to inspect through ordinary debugging
procedures. It also allows you to set widget-level breakpoints and collect X–event
history information in the same manner as using xscope(blank). See the xscope(1)
man page for more information.

Examiners Overview
When the X/Motif Analyzer first displays, it is set to examine widgets. At this point,
the window may be blank, or it may display a widget found in the call stack of a
stopped process.
At the bottom of the X/Motif Analyzer window is a tab panel that shows the current
set of examiners. In addition to this tab, the Widget Examiner, Breakpoints, Trace,
and Tree Examiners tabs are at the bottom of the window. These four tabs are always
present. Other examiners are available from the Examine menu of the X/Motif
Analyzer window.
007–2579–006

163

11: X/Motif Analyzer

Some examiners cannot be manually selected. They appear only when appropriate to
the call stack context. For example, the Callback Examiner appears only when a
process is stopped somewhere in a widget callback.

Examiners and Selections
If you select text in one examiner and then choose another examiner by using the
Examine menu, the new examiner is brought up and the text is used as an expression
for it. If you selected text that is an inappropriate object for the new examiner, an
error is generated.
Alternatively, you can select text, pull down the Examine menu, and choose
Selection. Here, the X/Motif Analyzer attempts to select an appropriate examiner for
the text. If the type of text is unknown, the following message displays:
Couldn’t examine selection in more detail

Otherwise, the appropriate examiner is chosen and the text is evaluated.
You can also accomplish this by triple-clicking on a line of text. If the type of text is
unknown, nothing happens. Otherwise, the appropriate examiner is chosen and the
text is evaluated.

Inspecting Data
X/Motif applications consist of collections of objects (that is, Motif widgets) and make
extensive use of X resources such as windows, graphics context, and so on. The
construction model of an X window system hinders you from inspecting the internal
structures of widgets and X resources because you are presented with ID values. The
X/Motif Analyzer lets you to see the data structures behind the ID values.

Inspecting the Control Flow
Traditional debuggers enable you to set breakpoints only in source lines or functions.
With the X/Motif Analyzer, you can set breakpoints for specific widgets or widget
classes, for specific control flow constructs like callbacks or event handlers, and for
specific X events or requests.

164

007–2579–006

ProDevTM WorkShop: Debugger User’s Guide

Tracing the Execution
The X/Motif Analyzer can trace Xlib-level server events and client requests, Xt-level
event dispatching information, widget life cycle, and widget status information.

Restrictions and Limitations
The X/Motif Analyzer has the following restrictions and limitations:
• The Breakpoints Examiner is active only after you have stopped a process and if
you have changed $LD_LIBRARY_PATH. See "Launching the X/Motif Analyzer",
page 167 for more information regarding the correct $LD_LIBRARY_PATH.
• Sometimes, gadget names may be unavailable and are displayed as

007 2579 006

Navigation menu

Versions of this User Manual:

Views

Navigation