TotalView Reference Guide November 2003 Version 6.3.1

TotalView
Reference Guide
November 2003
Version 6.3.1
Copyright © 1998–2003 by Etnus LLC. All rights reserved.
Copyright © 1996–1998 by Dolphin Interconnect Solutions, Inc.
Copyright © 1993–1996 by BBN Systems and Technologies, a division of BBN Corporation.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means,
electronic, mechanical, photocopying, recording, or otherwise without the prior written permission of Etnus LLC. (Etnus).
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the
Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.
Etnus has prepared this manual for the exclusive use of its customers, personnel, and licensees. The information in this
manual is subject to change without notice, and should not be construed as a commitment by Etnus. Etnus assumes no
responsibility for any errors that appear in this document.
TotalView and Etnus are registered trademarks of Etnus LLC.
All other brand names are the trademarks of their respective holders.
Book Contents
part I - CLI Commands
1
2
3
4
5
CLI Command Summary ..............................................................................3
CLI Commands ............................................................................................13
CLI Namespace Commands.....................................................................125
TotalView Variables ..................................................................................155
Default Arena Widths...............................................................................187
part II - Running TotalView
6
7
TotalView Command Syntax ...................................................................191
TotalView Debugger Server (tvdsvr) Command Syntax.......................199
part III - Platforms and Operating Systems
8
9
10
Compilers and Platforms .........................................................................207
Operating Systems ...................................................................................215
Architectures .............................................................................................225
TotalView Reference Guide: version 6.3.1
iii
Book Contents
iv
Contents
About This Book
How To Use This Book ............................................................................................. xi
Conventions ............................................................................................................ xi
TotalView Documentation .......................................................................................xii
part I - CLI Commands
1
CLI Command Summary
2
CLI Commands
Command Overview ............................................................................................... 13
alias ........................................................................................................................ 16
capture ................................................................................................................... 18
dactions.................................................................................................................. 19
dassign.................................................................................................................... 21
dattach ................................................................................................................... 23
dbarrier ................................................................................................................... 25
dbreak..................................................................................................................... 29
dcache .................................................................................................................... 32
dcheckpoint............................................................................................................ 33
dcont ...................................................................................................................... 36
ddelete.................................................................................................................... 37
ddetach................................................................................................................... 38
ddisable .................................................................................................................. 39
ddlopen .................................................................................................................. 40
ddown..................................................................................................................... 42
denable................................................................................................................... 43
dflush...................................................................................................................... 44
dfocus..................................................................................................................... 47
dga .......................................................................................................................... 49
dgo.......................................................................................................................... 51
dgroups................................................................................................................... 52
TotalView Reference Guide: version 6.3.1
v
Contents
dhalt ....................................................................................................................... 57
dheap...................................................................................................................... 58
dhold ...................................................................................................................... 67
dkill ......................................................................................................................... 68
dlappend ................................................................................................................ 69
dlist......................................................................................................................... 70
dload....................................................................................................................... 73
dmstat .................................................................................................................... 74
dnext....................................................................................................................... 76
dnexti ..................................................................................................................... 78
dout ........................................................................................................................ 80
dprint ...................................................................................................................... 82
dptsets.................................................................................................................... 86
drerun ..................................................................................................................... 88
drestart ................................................................................................................... 90
drun ........................................................................................................................ 92
dset......................................................................................................................... 95
dstatus.................................................................................................................... 97
dstep....................................................................................................................... 99
dstepi.................................................................................................................... 102
dunhold ................................................................................................................ 104
dunset................................................................................................................... 105
duntil .................................................................................................................... 106
dup ....................................................................................................................... 108
dwait ..................................................................................................................... 109
dwatch .................................................................................................................. 110
dwhat.................................................................................................................... 113
dwhere .................................................................................................................. 116
dworker ................................................................................................................. 118
exit ........................................................................................................................ 119
help....................................................................................................................... 120
quit ....................................................................................................................... 121
stty........................................................................................................................ 122
unalias .................................................................................................................. 123
3
CLI Namespace Commands
Command Overview ............................................................................................. 125
actionpoint ........................................................................................................... 127
dll.......................................................................................................................... 129
dec2hex ................................................................................................................ 130
errorCodes............................................................................................................ 131
expr....................................................................................................................... 132
focus_groups ........................................................................................................ 134
focus_processes................................................................................................... 135
focus_threads....................................................................................................... 136
group .................................................................................................................... 137
hex2dec ................................................................................................................ 138
image .................................................................................................................... 139
process ................................................................................................................. 141
read_symbols ....................................................................................................... 144
respond ................................................................................................................ 145
vi
Contents
scope ....................................................................................................................
source_process_startup.......................................................................................
symbol ..................................................................................................................
thread ...................................................................................................................
type.......................................................................................................................
type_transformation.............................................................................................
4
146
147
148
149
151
153
TotalView Variables
Top-Level (::) Namespace ..................................................................................... 155
TV:: Namespace .................................................................................................... 160
TV::GUI:: Namespace ............................................................................................ 180
5
Default Arena Widths
part II - Running TotalView
6
TotalView Command Syntax
Syntax ................................................................................................................... 191
Options ................................................................................................................. 191
7
TotalView Debugger Server (tvdsvr) Command Syntax
The tvdsvr Command and Its Options ................................................................. 199
Replacement Characters ...................................................................................... 202
part III - Platforms and Operating Systems
8
Compilers and Platforms
Compiling with Debugging Symbols..................................................................... 207
HP Alpha Running Linux ................................................................................... 207
HP Tru64 UNIX .................................................................................................. 208
HP-UX ............................................................................................................... 208
IBM AIX on RS/6000 Systems ........................................................................... 208
Linux Running on an x86 Platform .................................................................... 209
SGI IRIX-MIPS Systems ..................................................................................... 210
SunOS 5 on SPARC ........................................................................................... 210
Using Exception Data on Tru64 UNIX .................................................................. 211
Linking with the dbfork Library ............................................................................. 211
Linking with dbfork and HP Tru64 UNIX ............................................................... 211
Linking with HP-UX ........................................................................................... 212
dbfork on IBM AIX on RS/6000 Systems ........................................................... 212
Linking C++ Programs with dbfork .............................................................. 213
Linux ................................................................................................................. 213
SGI IRIX6-MIPS ................................................................................................. 214
SunOS 5 SPARC ................................................................................................ 214
9
Operating Systems
Supported Operating Systems ............................................................................. 215
TotalView Reference Guide: version 6.3.1
vii
Contents
Mounting the /proc File System ........................................................................... 216
Mounting /proc HP Tru64 UNIX and SunOS 5 .................................................. 216
Mounting proc SGI IRIX .................................................................................... 216
Swap Space .......................................................................................................... 216
Swap Space on HP Tru64 UNIX ........................................................................ 217
Swap Space on HP HP-UX ................................................................................ 217
Maximum Data Size ...................................................................................... 217
Swap Space on IBM AIX ................................................................................ 218
Swap Space on Linux ........................................................................................ 218
Swap Space on SGI IRIX ................................................................................... 218
Swap Space on SunOS 5 .................................................................................. 219
Shared Libraries .................................................................................................... 219
Changing Linkage Table Entries and LD_BIND_NOW ....................................... 220
Using Shared Libraries on HP-UX ..................................................................... 220
Debugging Dynamically Loaded Libraries ............................................................ 221
Known Limitations ............................................................................................ 223
Remapping Keys ................................................................................................... 223
Expression System ............................................................................................... 223
Expression System on HP Alpha Tru64 UNIX ................................................... 223
Expression System on IBM AIX ......................................................................... 223
Expression System on SGI IRIX ........................................................................ 224
10
Architectures
HP Alpha............................................................................................................... 225
Alpha General Registers ....................................................................................... 225
Alpha Floating-Point Registers ......................................................................... 226
Alpha FPCR Register ......................................................................................... 226
HP PA-RISC ........................................................................................................... 227
PA-RISC General Registers ................................................................................ 227
PA-RISC Process Status Word ........................................................................... 228
PA-RISC Floating-Point Registers ..................................................................... 228
PA-RISC Floating-Point Format ........................................................................ 229
IBM Power ............................................................................................................. 229
Power General Registers ................................................................................... 229
Power MSR Register .......................................................................................... 230
Power Floating-Point Registers ......................................................................... 231
Power FPSCR Register ....................................................................................... 231
Using the Power FPSCR Register ................................................................... 232
Intel IA-64 ............................................................................................................. 233
Intel IA-64 General Registers ............................................................................ 233
IA-64 Processor Status Register Fields (PSR) .................................................... 234
Current Frame Marker Register Fields (CFM) .................................................... 235
Register Stack Configuration Register Fields (RSC) .......................................... 235
Previous Function State Register Fields (PFS) .................................................. 235
Floating Point Registers .................................................................................... 235
Floating Point Status Register Fields ................................................................ 236
Intel x86 ................................................................................................................ 236
Intel x86 General Registers ............................................................................... 236
Intel x86 Floating-Point Registers ..................................................................... 237
Intel x86 FPCR Register ..................................................................................... 238
Using the Intel x86 FPCR Register ................................................................. 238
viii
Contents
Intel x86 FPSR Register ..................................................................................... 239
Intel x86 MXSCR Register ................................................................................. 239
SGI MIPS ............................................................................................................... 240
MIPS General Registers ..................................................................................... 240
MIPS SR Register ............................................................................................... 241
MIPS Floating-Point Registers .......................................................................... 241
MIPS FCSR Register .......................................................................................... 242
Using the MIPS FCSR Register ...................................................................... 243
MIPS Delay Slot Instructions ............................................................................ 243
Sun SPARC ............................................................................................................ 244
SPARC General Registers .................................................................................. 244
SPARC PSR Register .......................................................................................... 244
SPARC Floating-Point Registers ........................................................................ 245
SPARC FPSR Register ........................................................................................ 245
Using the SPARC FPSR Register .................................................................... 246
Index ..................................................................................................................247
TotalView Reference Guide: version 6.3.1
ix
Contents
x
About This Book
This document is the reference guide for the Etnus TotalView®
debugger. Unlike the TotalView Users Guide which presented GUI and CLI
information together, the chapters in this book are either devoted to
one interface or contain information that pertains to both.
How To Use This Book __________________
The information in this book is in three parts.
■
■
■
CLI Commands
Here you will find a description of all of the CLI’s commands, the variables
that you can set using the CLI, and other CLI-related information.
Running TotalView
TotalView and the TotalView Debugger Server can accept a great many
command-line options. These options are described here.
Platforms and Operating Systems
While the way in which you use TotalView is the same from system to system and from environment to environment, these systems and environments place some constraints on what you must do and require that you
compile programs differently on the various UNIX platforms. These differences are described here.
Conventions __________________________
The following table describes the conventions used in this book:
Convention
Meaning
[]
Brackets are used when describing parts of a command that are
optional.
In a command description, text in italic represent information
you type. Elsewhere, italic is used for emphasis. You won’t have
any problems distinguishing between the uses.
arguments
TotalView Reference Guide: version 6.3.1
xi
TotalView Documentation
Convention
Meaning
Dark text
In a command description, dark text represent keywords or
options that you must type exactly as displayed. Elsewhere, it
represents words that are used in a programmatic way rather
than their normal way.
In program listings, this indicates that you are seeing a program
or something you’d type in response to a shell or CLI prompt. If
this text is in bold, it’s indicating that what you’re seeing is what
you’ll be typing. Bolding this kind of text is done only when it’s
important. You’ll usually be able to differentiate what you type
from what the system prints.
This graphic symbol indicates that the information that follows—it is printed in italics—is a note. This information is an
important qualifier to what was just said.
This graphic symbol indicates that a feature is only available in
the GUI. If you see it on the first line of a section, all the information in the section is just for GUI users. When it is next to a
paragraph, it tells you that just the sentence or two being discussed applies to the GUI.
The primary emphasis of this book is on the GUI. It shows the
windows and dialog boxes that you use. This symbol tells you
how to do the same thing using the CLI.
Example text
CLI:
TotalView Documentation ______________
The following table describes other TotalView documentation:
Title
TotalView User Guide
Contents
Describes how to use the TotalView GUI and
the CLI; this is the most used of all the TotalView
Online
Help HTML PDF
✔
✔
✔
books
TotalView Reference Guide Contains descriptions of CLI commands, how you
✔
run TotalView, and platform-specific information
TotalView QuickView
Presents what you need to know to get started
using TotalView
TotalView Commands
Defines all TotalView GUI commands
✔
Creating Type Transforma- Tells how to create Tcl CLI macros that change the
tions
way structures and STL containers appear
TotalView Installation
Contains the procedures to install TotalView and the
Guide
FLEXlm license manager
TotalView New Features
Tells you about new features added to TotalView
✔
TotalView Release Notes
Lists known bugs and other information related to
the current release
Platforms and System
Lists the platforms upon which TotalView runs and
Requirements
the compilers it supports
xii
✔
✔
Print
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
✔
About This Book
TotalView Documentation
Contacting Us _________________________
Please contact us if you have problems installing TotalView, questions that
are not answered in the product documentation or on our Web site, or suggestions for new features or improvements.
Our Internet E-Mail address for support issues is:
support@etnus.com
For documentation issues, the address is:
documentation@etnus.com
Here are our phone numbers:
1-800-856-3766 in the United States
(+1) 508-652-7700 worldwide
If you are reporting a problem, please include the following information:
■
■
■
The version of TotalView and the platform on which you are running
TotalView.
An example that illustrates the problem.
A record of the sequence of events that led to the problem.
TotalView Reference Guide: version 6.3.1
xiii
TotalView Documentation
xiv
About This Book
Part I: CLI Commands
This part of the TotalView Reference Guide contains five chapters describing the CLI. While Chapter 4 describes all CLI variables, these variables
include those used to set GUI behaviors.
Chapter 1: CLI Command Summary
There are a great number of CLI commands. This chapter
summarizes them for you.
Chapter 2: CLI Commands
Here you will find a detailed treatment of all CLI commands
that are found in the CLI’s unqualified (top-level)
namespace. These are the commands that you will use dayin and day-out and those that are most often used interactively.
Chapter 3: CLI Namespace Commands
This chapter contains descriptions of commands found in
the TV:: namespace. These commands are seldom used interactively as they are most often used in scripts.
Chapter 4: TotalView Variables
TotalView places variables in three namespaces: unqualified
(top-level), TV:: and TV::GUI. For the most part, you set
these variables to alter TotalView behaviors.
Chapter 5: Default Arena Widths
Many of the commands described in Chapter 2 have a default arena. That is, the scope of their action is across a set
of groups, processes, and threads unless you tell the command otherwise. Here you’ll find a listing of all these default
arenas.
TotalView Reference Guide: version 6.3.1
1
2
CLI Command
Summary
1
This chapter contains a summary of all TotalView® CLI commands.
Type Transformation macros and convenience routines are not
listed here.
actionpoint
Gets and sets action point properties
TV::actionpoint action [ object-id ] [ other-args ]
alias
Creates a new user-defined pseudonym for a command
alias alias-name defn-body
Views previously defined aliases
alias [ alias-name ]
capture
Returns a command’s output as a string
capture [ –out | –err | –both ] [ –f filename ] command
dactions
Displays information about action points
dactions [ ap-id-list ] [ –at source-loc ]
[ –enabled | –disabled ]
Saves action points to a file
dactions –save [ filename ]
Loads previously saved action points
dactions –load [ filename ]
dassign
Changes the value of a scalar variable
dassign target value
TotalView Reference Guide: version 6.3.1
3
dattach - ddisable
dattach
Brings currently executing processes under CLI control
dattach [ –g gid ] [ –r hname ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –c corefile-name ]
[ –e ] fname pid-list
dbarrier
Creates a barrier breakpoint at a source location
dbarrier source-loc [ –stop_when hit { group | process | none } ]
[ –stop_when_done { group | process | none } ]
Creates a barrier breakpoint at an address
dbarrier –address addr
[ –stop_when_hit { group | process | none } ]
[ –stop_when_done { group | process | none } ]
dbreak
Creates a breakpoint at a source location
dbreak source-loc [ –p | –g | –t ] [ [ –l lang ] –e expr ]
Creates a breakpoint at an address
dbreak –address addr [ –p | –g | –t] [ [ –l lang ] –e expr ]
dcache
Clears the remote library cache
dcache
dcheckpoint
Create a checkpoint on SGI IRIX
dcheckpoint [ after_checkpointing ] [ –by process_set ] [ –no_park ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –no_preserve_ids ] [ –force ] checkpoint-name
Create a checkpoint on IBM AIX
dcheckpoint [ –delete | –halt ]
dcont
Continues execution and waits for execution to stop
dcont
ddelete
Deletes some action points
ddelete action-point-list
Deletes all action points
ddelete –a
ddetach
Detaches from the processes
ddetach
ddisable
Disables some action points
ddisable action-point-list
4
Chapter 1: CLI Command Summary
dll - dgo
Disables all action points
1. Command Summary
ddisable –a
dll
Manages shared libraries
TV::dll action [ dll-id-list ] [ other-args ]
ddlopen
Loads a shared object library
ddlopen [ –now | –lazy ] [ –local | –global ] [ –mode int ] filespec
Displays information about shared object libraries
ddlopen [ –list dll-ids... ]
ddown
Moves down the call stack
ddown [ num-levels ]
dec2hex
Converts a decimal number into hexadecimal
TV::dec2hex number
denable
Enables some action points
denable action-point-list
Enables all disabled action points in the current focus
denable –a
dflush
Removes the top-most suspended dprint
dflush
Removes all suspended dprint computations
dflush –all
Removes dprint computations preceding and including a suspended
evaluation ID
dflush susp-eval-id
dfocus
Changes the target of future CLI commands to this P/T set
dfocus p/t-set
Executes a command in this P/T set
dfocus p/t-set command
dga
Displays global array variables
dga [–lang lang_type] [handle_or_name] [slice]
dgo
Resumes execution of target processes
dgo
TotalView Reference Guide: version 6.3.1
5
dgroups - dheap
dgroups
Adds members to thread and process groups
dgroups –add [ –g gid ] [ id-list ]
Deletes groups
dgroups –delete [ –g gid ]
Intersects a group with a list of processes and threads
dgroups –intersect [ –g gid ] [ id-list ]
Prints process and thread group information
dgroups [ –list ] [ pattern ]
Creates a new thread or process group
dgroups –new [ thread_or_process ] [ –g gid ] [ id-list ]
Removes members for thread or process groups
dgroups –remove [ –g gid ] [ id-list ]
dhalt
Suspends execution of processes
dhalt
dheap
Shows heap tracker state
dheap [ –status ]
Enables or disables heap tracking
dheap { –enable | –disable }
Enables or disables Memory Tracker event notification
dheap { –notify | –nonotify }
Displays Memory Tracker information
dheap –info [ –backtrace ] [ start_address [ end_address ] ]
Indicates if an address refers to a deallocated block
dheap –is_dangling address
Locates memory leaks
dheap –leaks [ –check_interior ]
Paints memory with a distinct pattern
dheap –paint [ subcommands ]
Enables and disables block allocation and reallocation notification
dheap –tag_alloc subcommand start_address [ end_address]
Enables and disables the saving and freeing of deallocated memory
blocks
dheap –tag_alloc –[no]dont_free_on_dealloc
Enables and disables the retaining (hoarding) of freed memory blocks
dheap –hoard [ subcommands ]
6
Chapter 1: CLI Command Summary
dhold - dptsets
1. Command Summary
dhold
Holds processes
dhold –process
Holds threads
dhold –thread
dkill
Terminates execution of target processes
dkill
dlappend
Appends list elements to a TotalView variable
dlappend variable-name value [ ... ]
dlist
Displays code relative to the current list location
dlist [ –n num-lines ]
Displays code relative to a named location
dlist source-loc [ –n num-lines ]
Displays code relative to the current execution location
dlist –e [ –n num-lines ]
dload
Loads debugging information
dload [ –g gid ] [ –r hname] [ –e ] executable
dmstat
Displays memory use information
dmstat
dnext
Steps source lines, stepping over subroutines
dnext [ num-steps ]
dnexti
Steps machine instructions, stepping over subroutines
dnexti [ num-steps ]
dout
Runs out from current subroutine
dout [ frame-count ]
dprint
Prints the value of a variable or expression
dprint variable_or_expression
dptsets
Shows status of processes and threads in an array of P/T expressions
dptsets [ ptset_array ] ...
TotalView Reference Guide: version 6.3.1
7
drerun - dunset
drerun
Restarts processes
drerun [ cmd_arguments ] [ < infile ]
[ > [ > ][ & ] outfile ]
[ 2> [ > ] errfile ]
drestart
Restarts a checkpoint on SGI
drestart [ process-state ] [ –no_unpark ] [ –g gid ] [ –r host ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –no_preserve_ids ] checkpoint-name
Restarts a checkpoint on AIX
drestart [ –halt ] [ –g gid ] [ –r host ] [ –no_same_hosts ] checkpoint-name
drun
Starts or restarts processes
drun [ cmd_arguments ] [ < infile ]
[ > [ > ][ & ] outfile ]
[ 2> [ > ] errfile ]
dset
Creates or changes a CLI state variable
dset [ –new ] debugger-var value
Views current CLI state variables
dset [ debugger-var ]
Sets the default for a CLI state variable
dset -set_as_default debugger-var value
dstatus
Shows current status of processes and threads
dstatus
dstep
Steps lines, stepping into subfunctions
dstep [ num-steps ]
dstepi
Steps machine instructions, stepping into subfunctions
dstepi [ num-steps ]
dunhold
Releases a process
dunhold –process
Releases a thread
dunhold –thread
dunset
Restores a CLI variable to its default value
dunset debugger-var
Restores all CLI variables to their default values
dunset –all
8
Chapter 1: CLI Command Summary
duntil - exit
1. Command Summary
duntil
Runs to a line
duntil line-number
Runs to an address
duntil –address addr
Runs into a function
duntil proc-name
dup
Moves up the call stack
dup [ num-levels ]
dwait
Blocks command input until the target processes stop
dwait
dwatch
Defines a watchpoint for a variable
dwatch variable [ –length byte-count ] [ –p | –g | –t ]
[ [ –l lang ] –e expr ] [ –t type ]
Defines a watchpoint for an address
dwatch –address addr –length byte-count [ –p | –g | –t ]
[ [ –l lang ] –e expr ] [ –t type ]
dwhat
Determines what a name refers to
dwhat symbol-name
dwhere
Displays locations in the call stack
dwhere [ num-levels ] [ –a ]
dworker
Adds or removes a thread from a workers group
dworker { number | boolean }
errorCodes
Returns a list of all error code tags
TV::errorCodes
Returns or raises error information
TV::errorCodes number_or_tag [ –raise [ message ] ]
expr
Manipulates values created by dprint –nowait
TV::expr action [ susp-eval-id ] [ other-args ]
exit
Terminates the debugging session
exit [ –force ]
TotalView Reference Guide: version 6.3.1
9
focus_groups - scope
focus_groups
Returns a list of groups in the current focus
TV::focus_groups
focus_processes
Returns a list of processes in the current focus
TV::focus_processes [ –all | –group | –process | –thread ]
focus_threads
Returns a list of threads in the current focus
TV::focus_threads [ –all | –group | –process | –thread ]
group
Gets and sets group properties
TV::group action [ object-id ] [ other-args ]
help
Displays help information
help [ topic ]
hex2dec
Converts to decimal
TV::hex2dec number
image
Gets and sets image properties
TV::image action [ object-id ] [ other-args ]
process
Gets and sets process properties
TV::process action [ object-id ] [ other-args ]
quit
Terminates the debugging session
quit [ –force ]
read_symbols
Read symbols from libraries
TV::read_symbols –lib lib-name-list
Read symbols from libraries associated with a stack frame
TV::read_symbols –frame [number]
Read symbols for all stacks in the backtrace
TV::read_symbols –stack
respond
Provides responses to commands
TV::respond response command
scope
Returns information about a a symbol’s scope.
TV::scope action [ object-id ] [ other-args ]
10
Chapter 1: CLI Command Summary
source_process_startup - unalias
1. Command Summary
source_process_startup
“Sources” a .tvd file when a process is loaded
TV::source_proccess_startup process_id
stty
Sets terminal properties
stty [ stty-args ]
symbol
Returns or sets internal TotalView symbol information
TV::symbol action [ object-id ] [ other-args ]
thread
Gets and sets thread properties
TV::thread action [ object-id ] [ other-args ]
type
Gets and sets type properties
TV::type action [ object-id ] [ other-args ]
type_transformation
Creates type transformations and examine properties
TV::type_transformation action [ object-id ] [ other-args ]
unalias
Removes an alias
unalias alias-name
Removes all aliases
unalias –all
TotalView Reference Guide: version 6.3.1
11
unalias - unalias
12
Chapter 1: CLI Command Summary
CLI Commands
2
This chapter contains detailed descriptions of CLI commands.
Command Overview ___________________
This section lists all of the CLI commands. It also contains a short explanation of what each command does.
General CLI Commands
The CLI commands in this group provide information on the general CLI
operating environment:
■
■
■
■
■
■
■
■
alias: Creates or views pseudonym for commands and arguments.
capture: Allows commands that print information to instead send their
output to a variable.
dlappend: Appends list elements to a TotalView variable.
dset: Changes or views values of TotalView variables.
dunset: Restores default settings of TotalView variables.
help: Displays help information.
stty: Sets terminal properties.
unalias: Removes a previously defined alias.
CLI Initialization and Termination
These commands initialize and terminate the CLI session, and add processes to CLI control:
■
■
■
■
■
dattach: Brings one or more processes currently executing in the normal
runtime environment (that is, outside TotalView) under TotalView control.
ddetach: Detaches TotalView from a process.
ddlopen: Dynamically loads shared object libraries.
dgroups: Manipulates and manages groups.
dkill: Kills existing user processes, leaving debugging information in
place.
TotalView Reference Guide
13
Command Overview
■
■
■
■
dload: Loads debugging information about the program into TotalView
and prepares it for execution.
drerun: Restarts a process.
drun: Starts or restarts the execution of user processes under control of
the CLI.
exit, quit: Exits from TotalView, ending the debugging session.
Program Information
The following commands provide information about a program's current
execution location and allow you to browse the program's source files:
■
■
■
■
■
■
■
■
■
■
■
ddown: Navigates through the call stack by manipulating the current
frame.
dflush: Unwinds stack from dprint computations.
dga: Displays global array variables.
dlist: Browses source code relative to a particular file, procedure, or line.
dmstat: Displays memory usage information.
dprint: Evaluates an expression or program variable and displays the resulting value.
dptsets: Shows status of processes and threads in a P/T set.
dstatus: Shows status of processes and threads.
dup: Navigates through the call stack by manipulating the current frame.
dwhat: Determines what a name refers to.
dwhere: Prints information about the thread’s stack.
Execution Control
The following commands control execution:
■
■
■
■
■
■
■
■
■
■
■
■
■
■
dcont: Continues execution of processes and waits for them.
dfocus: Changes the set of processes, threads, or groups upon which a
CLI command acts.
dgo: Resumes execution of processes (without blocking).
dhalt: Suspends execution of processes.
dhold: Holds threads or processes.
dnext: Executes statements, stepping over subfunctions.
dnexti: Executes machine instructions, stepping over subfunctions.
dout: Runs out of current procedure.
dstep: Executes statements, moving into subfunctions if required.
dstepi: Executes machine instructions, moving into subfunctions if required.
dunhold: Releases held threads.
duntil: Executes statements until a statement is reached.
dwait: Blocks command input until processes stop.
dworker: Adds or removes threads from a workers group.
Action Points
The following action point commands are responsible for defining and
manipulating the points at which the flow of program execution should
stop so that you can examine debugger or program state:
14
Chapter 2: CLI Commands
Command Overview
■
■
■
■
■
■
■
dactions: Views information on action point definitions and their current
status; it also saves and restores action points.
dbarrier: Defines a process barrier breakpoint.
dbreak: Defines a breakpoint.
ddelete: Deletes an action point.
ddisable: Temporarily disables an action point.
denable: Reenables an action point that has been disabled.
dwatch: Defines a watchpoint.
Other Commands
The commands in the category do not fit into any of the other categories.
■
■
■
■
dassign: Changes the value of a scalar variable.
dcache: Clears the remote library cache.
dcheckpoint: Creates a file that can later be used to restart a program.
dheap: Displays information about the heap.
drestart: Restarts a checkpoint.
TotalView Reference Guide: version 6.3.1
2. CLI Commands
■
15
alias
alias
Creates or views pseudonyms for commands
Format:
Creates a new user-defined pseudonym for a command
alias alias-name defn-body
Views previously defined aliases
alias [ alias-name ]
Arguments:
alias-name
defn-body
Description:
The alias command associates a name you specify with text that you
define. This text can contain one or more commands. After you create an
alias, you can use it in the same way as a native TotalView or Tcl command.
In addition, you can include an alias as part of a definition of another alias.
The name of the command pseudonym being defined.
The text that Tcl will substitute when it encounters
alias-name.
If you just do not enter an alias-name argument, the CLI displays the names
and definitions of all aliases. If you just specify an alias-name argument, the
CLI displays the definition of the alias.
Because the alias command can contain Tcl commands, you must ensure
that defn-body complies with all Tcl expansion, substitution, and quoting
rules.
TotalView’s global startup file, tvdinit.tvd, defines a set of default aliases.
All the common commands have one- or two-letter aliases. (You can obtain
a list of these commands by typing alias—being sure not to use an argument—in the CLI window.)
You cannot use an alias to redefine the name of a CLI-defined command.
You can, however, redefine a built-in CLI command by creating your own Tcl
procedure. For example, here is a procedure that disables the built-in
dwatch command. When a user types dwatch, the CLI executes this code
instead of the built-in CLI code:
proc dwatch {} {
puts “The dwatch command is disabled”
}
The CLI does not parse defn-body (the command’s definition) until it is used.
Thus, you can create aliases that are nonsensical or incorrect. The CLI only
detects errors when it tries to execute your alias.
When you obtain help for a command, the help text includes information
for TotalView’s predefined aliases.
Examples:
alias nt dnext
alias nt
alias
16
Defines a command called nt that executes the dnext
command.
Displays the definition of the nt alias.
Displays the definitions of all aliases.
Chapter 2: CLI Commands
alias
alias m {dlist main}
Defines an alias called m that lists the source code of
function main().
alias step2 {dstep; dstep}
Defines an alias called step2 that does two dstep commands. This new command will apply to the focus that
exists when someone uses this alias.
alias step2 {s ; s}
Creates an alias that performs the same operations as
the one in the previous example. It differs in that it
uses the alias for dstep. Note that you could also create an alias that does the same thing as follows: alias
step2 {s 2}.
Defines an alias called step1 that steps the first user
thread in process 1. Note that all other threads in the
process run freely while TotalView steps the current line
in your program.
TotalView Reference Guide: version 6.3.1
17
2. CLI Commands
alias step1 {f p1. dstep}
capture
capture
Returns a command’s output as a string
Format:
Arguments:
capture [ –out | –err | –both ] [ –f filename ] command
–out
–err
–both
–f filename
command
Description:
Examples:
Tells the CLI that it should only capture output that is
sent to stdout. This option is the default.
Tells the CLI to send the output it captures to stderr.
Tells the CLI to send the output it captures to stdout
and stderr.
Tells the CLI to send the output it captures to filename.
The CLI command (or commands) whose output is
being captured. If you are specifying more than one
command, you must enclose them within braces ({ }).
The capture command executes command, capturing all output that would
normally go to the console into a string. After command completes, it
returns the string. This command is analogous to the UNIX shell’s back-tick
feature; that is, `command`. The capture command lets you obtain the
printed output of any CLI command so that you can assign it to a variable
or otherwise manipulate it.
set save_stat [ capture st ]
Saves the current process status into a Tcl variable.
set vbl [ capture {foreach i {1 2 3 4} \
{p int2_array($i )}} ]
Saves the printed output of four array elements into a
Tcl variable. Here is some sample output:
int2_array(1)
int2_array(2)
int2_array(3)
int2_array(4)
=
=
=
=
-8
-6
-4
-2
(0xfff8)
(0xfffa)
(0xfffc)
(0xfffe)
Because capture records all of the information sent to
it by the commands in the foreach, you do not have to
use a dlist command.
exec cat << [ capture help commands ] > cli_help.txt
Writes the help text for all TotalView commands to the
cli_help.txt file.
set ofile [open cli_help.txt w]
capture –f $ofile help commandsq
Also writes the help text for all TotalView commands to
close $ofile
the cli_help.txt file. This set of commands is more efficient than the previous command because the captured data is not buffered.
18
Chapter 2: CLI Commands
dactions
dactions
Displays information, saves, and reloads action points
Format:
Displays information about action points
dactions [ ap-id-list ] [ –at source-loc ] [ –enabled | –disabled ]
Saves action points to a file
dactions –save [ filename ]
Loads previously saved action points
dactions –load [ filename ]
Arguments:
ap-id-list
–enabled
–disabled
–save
–load
filename
Description:
The dactions command displays information about action points in the
processes in the current focus. The information is printed; it is not
returned.
This command also lets you obtain the action point identifier. You will need
to use this identifier when you delete, enable, and disable action points.
The identifier is returned when the action point is created. It is also displayed when the
target stops at an action point.
You can include action point identifiers as arguments to the command
when more detailed information is needed. The –enabled and –disabled
options restrict output to action points in one of these states.
You cannot use the dactions command when you are debugging a core file
or before TotalView loads executables.
The –save option tells TotalView that it should write action point information to a file so that either you or TotalView can restore your action points
at a later time. The –load option tells TotalView that it should immediately
TotalView Reference Guide: version 6.3.1
19
2. CLI Commands
–at source-loc
A list of action point identifiers. If you specify individual
action points, the information displayed is limited to
these points.
If you omit this argument, TotalView displays summary
information about all action points in the processes in
the focus set. If one ID is entered, TotalView displays
full information for it. If more than one ID is entered,
TotalView just displays summary information for each.
Displays the action points at source-loc.
Only shows enabled action points.
Only shows disabled action points.
Writes information about action points to a file.
Restores action point information previously saved in a
file.
The name of the file into which TotalView will read and
write action point information. If you omit this file
name, TotalView writes them to a file named
program_name.TVD.v3breakpoints, where program_name is
the name of your program.
dactions
read in the saved file. If you use the filename argument with either of these
options, TotalView either writes to or reads from this file. If you do not use
this argument, it uses a file named programname.TVD.v3breakpoints where
programname is the name of your program. This file is written to the same
directory as your program.
The information saved includes expression information associated with the
action point and whether the action point is enabled or disabled. For
example, if your program’s name is foo, it writes this information to
foo.TVD.v3breakpoints.
TotalView does not save information about watchpoints.
If a file with the default name exists, TotalView can read this information
when it starts your program. When TotalView exits, it can create the default.
For more information, see File > Preferences in TotalView’s Help system.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
ac
{dactions}
Displays all action points
ac –at 81
Displays information about the action points on line
81. (Notice that this example uses the alias instead of
the full command name.) Here is the output from this
command:
ac –at 81
1 shared action point for group 3:
1 addr=0x10001544 [arrays.F#81] Enabled
Share in group: true
Stop when hit: group
dactions 1 3
Displays information about action points 1 and 3, as
follows:
2 shared action points for process 1:
1 addr=0x100012a8 [arrays.F#56] Enabled
3 addr=0x100012c0 [arrays.F#57] Enabled
dfocus p1 dactions
Displays information on all action points defined within
process 1.
dfocus p1 dactions –enabled
Displays information on all enabled action points
within process 1.
20
Chapter 2: CLI Commands
dassign
dassign
Changes the value of a scalar variable
Format:
dassign target value
Arguments:
target
value
Description:
The dassign command evaluates an expression and replaces the value of a
variable with the evaluated result. The location may be a scalar variable, a
dereferenced pointer variable, or an element in an array or structure.
The name of a scalar variable within your program.
A source-language expression that evaluates to a scalar
value. This expression can use the name of another
variable.
The CLI interprets each symbol name in the expression according to the
current context. Because the value of a source variable may not have the
same value across threads and processes, the value assigned can differ in
your threads and processes. If the data type of the resulting value is incompatible with that of the target location, you must cast the value into the
target’s type. (Casting is described in Chapter 12 of the TotalView Users Guide.)
Here are some things you should know about assigning characters and
strings:
■
■
■
If you are assigning a character to a target, place the character value
within single quotation marks; for example, ‘c’.
You can use the standard C language escape character sequences; for
example, \n, \t, and the like. These escape sequences can also be in a
character or string assignment.
If you are assigning a string to a target, place the string within quotation
marks. However, you must “escape” the quotation marks so they are not
interpreted by Tcl; for example, \”The quick brown fox\”.
If value contains an expression, the expression is evaluated by TotalView’s
expression system. This system is discussed in Chapter 12 of the TotalView
Users Guide.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
as
{dassign}
Changes a scalar variable’s value
dassign scalar_y 102
Stores the value 102 in each occurrence of variable
scalar_y for all processes and threads in the current set.
TotalView Reference Guide: version 6.3.1
21
2. CLI Commands
The default focus for dassign is thread. So, if you do not change the focus,
this command acts upon the thread of interest. If the current focus specifies a
width that is wider than t (thread) and is not d (default), dassign iterates
over the threads in the focus set and performs the assignment in each. In
addition, if you use a list with the dfocus command, dassign iterates over
each list member.
dassign
dassign i 10*10
dassign i i*i
Stores the value 100 in variable i.
Does not work and the CLI displays an error message. If
i is a simple scalar variable, you could use the following
statements:
set x [lindex [capture dprint i] 2]
dassign i [expr $x * $x]
f {p1 p2 p3} as scalar_y 102
Stores the value 102 in each occurrence of variable
scalar_y contained in processes 1, 2, and 3.
22
Chapter 2: CLI Commands
dattach
dattach
Brings currently executing processes under CLI control
Format:
Arguments:
dattach [ –g gid ] [ –r hname ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –c corefile-name ]
[ –e ] filename pid-list
–g gid
–r hname
–ask_attach_parallel
Asks if TotalView should attach to parallel processes of
a parallel job. The default is to automatically attach to
processes. For additional information, see File >
Preferences in TotalView’s Help.
–no_attach_parallel
-c corefile-name
–e
filename
pid-list
TotalView Reference Guide: version 6.3.1
Do not attach to any additional parallel processes in a
parallel job. For additional information, see File >
Preferences in TotalView’s Help.
Tells the CLI that it should load the core file named in
the argument that follows. If you use this option, you
must also special a file name (filename).
Tells the CLI that the next argument is a file name. You
need to use this argument if the file name begins with a
dash (–) or only uses numeric characters.
The name of the executable. Setting an executable
here, sets it for all PIDs being attached to in this command. If you do not include this argument, the CLI tries
to determine the executable file from the process.
Some architectures do not allow this to occur.
A list of system-level process identifiers (such as a
UNIX PID) naming the processes that TotalView will
control. All PIDs must reside on the same system, and
they will all be placed into the same control group.
If you need to place the processes in different groups
or attach to processes on more than one system, you
must use multiple dattach commands.
23
2. CLI Commands
Sets the control group for the processes being added
to be group gid. This group must already exist. (The CLI
GROUPS variable contains a list of all groups. See
GROUPS on page 157 for more information.)
The host on which the process is running. The CLI will
launch a TotalView Debugger Server on the host
machine if one is not already running there. Consult
the Setting Up Parallel Debugging Sessions chapter of the
Totalview Users Guide for information on the launch command used to start this server.
Setting a host sets it for all PIDs attached to in this
command. If you do not name a host machine, the CLI
uses the local host.
dattach
Description:
The dattach command tells TotalView to attach to one or more processes,
making it possible to continue process execution under CLI control.
This command returns the TotalView process ID (DPID) as a string. If you
specify more than one process in a command, dattach returns a list of
DPIDs instead of a single value.
TotalView places all processes to which it attaches in one dattach command in the same control group. This allows you to place all processes in a
multiprocess program executing on the same system in the same control
group.
If a program has more than one executable, you must use a separate
dattach for each.
If you have not already loaded filename, the CLI searches for it. The search
will include all directories in the EXECUTABLE_PATH CLI variable.
The process identifiers specified in the pid-list must refer to existing processes in the run-time environment. TotalView attaches to the processes,
regardless of their execution states.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
at
{dattach}
Brings the process under CLI control
dattach mysys 10020
Loads debugging information for mysys and brings the
process known to the run-time system by PID 10020
under CLI control.
dattach –e 123 10020
Loads file 123 and brings the process known to the
run-time system by PID 10020 under CLI control.
dattach –g 4 –r Enterprise myfile 10020
Loads myfile that is executing on the host named
Enterprise into group 4 and brings the process known
to the run-time system by PID 10020 under CLI control.
If a TotalView Debugger Server (tvdsvr) is not running on
Enterprise, the CLI will start it.
dattach my_file 51172 52006
Loads debugging information for my_file and brings the
processes corresponding to PIDs 51172 and 52006
under CLI control.
set new_pid [dattach –e mainprog 123]
dattach –r otherhost –g $CGROUP($new_pid) –e slave 456
Begins by attaching to mainprog running on the local
host. It then attaches to slave running on otherhost and
inserts them both in the same control group.
24
Chapter 2: CLI Commands
dbarrier
dbarrier
Defines a process or thread barrier breakpoint
Format:
Creates a barrier breakpoint at a source location
dbarrier source-loc [ –stop_when_hit width ]
[ –stop_when_done width ]
Creates a barrier breakpoint at an address
dbarrier –address addr [ –stop_when_hit width ]
[ –stop_when_done width ]
Arguments:
source-loc
–stop_when_done width
After all processes or threads reach the barrier, the CLI
releases all processes and threads held at the barrier.
(Released means that these threads and processes can
run.) Setting this option tells the CLI that it should stop
additional threads contained in the same group or
process.
If you do not use this option, the value of the
BARRIER_STOP_WHEN_DONE variable indicates what
else TotalView stops.
The width argument indicates what else is stopped. You
can enter one of the following three values:
TotalView Reference Guide: version 6.3.1
25
2. CLI Commands
The barrier breakpoint location as a line number or as a
string containing a file name, function name, and line
number, each separated by # characters; for example,
#file#line. If you omit parts of this specification, the
CLI will create them for you. For more information, see
“Qualifying Symbol Names” in Chapter 12 of the TotalView
Users Guide.
–address addr
The barrier breakpoint location as an absolute address
in the address space of the program.
–stop_when_hit width
Tells the CLI what else it should stop when it stops the
thread arriving at a barrier.
If you do not use this option, the value of the
BARRIER_STOP_ALL variable indicates what TotalView
will stop.
This command’s width argument indicates what else
TotalView stops. You can enter one of the following
three values:
Stops all processes in the control group when the bargroup
rier is hit.
Stops the process that hit the barrier.
process
Stops the thread that hit the barrier; that is, the thread
none
will be held and all other threads continue running. If
you apply this width to a process barrier, TotalView will
stop the process that hit the breakpoint.
dbarrier
group
process
none
Description:
Stops the entire control group when the barrier is satisfied.
Stops the processes containing threads in the satisfaction set when the barrier is satisfied.
You will find information on the “satisfaction set” in this
topic’s Description section.
Stops the satisfaction set. For process barriers, process
and none have the same effect. This is the default if
BARRIER_STOP_WHEN_DONE is none.
The dbarrier command sets a process or thread barrier breakpoint that is
triggered when execution arrives at a location. This command returns the
ID of the newly created breakpoint.
The dbarrier command is most often used to synchronize a set of threads.
The P/T set defines which threads are affected by the barrier. When a thread
reaches a barrier, it stops, just as it does for a breakpoint. The difference is
that TotalView prevents—that is, holds—each thread reaching the barrier
from responding to resume commands (for example, dstep, dnext, and
dgo) until all threads in the affected set arrive at the barrier. When all
threads reach the barrier, TotalView considers the barrier to be satisfied and
releases these threads. They are just released; they are not continued. That
is, TotalView leaves them stopped at the barrier. If you now continue the
process, those threads stopped at the barrier also run along with any other
threads that were not participating with the barrier. After they are released,
they can respond to resume commands.
If the process is stopped and then continued, the held threads, including
the ones waiting on an unsatisifed barrier, do not run. Only unheld threads
run.
The satisfaction set for the barrier is determined by the current focus. If the
focus group is a thread group, TotalView creates a thread barrier.
■
■
When a thread hits a process barrier, TotalView holds the thread’s process.
When a thread hits a thread barrier, TotalView holds the thread; TotalView
may also stop the thread’s process or control group. Neither are held.
TotalView determines the default focus width based on the setting of the
SHARE_ACTION_POINT variable. If it is set to true, the default is group. Otherwise, it is process.
TotalView determines what processes and threads are part of the satisfaction set by taking the intersection of the share group with the focus set.
(Barriers cannot extend beyond a share group.)
The CLI displays an error message if you use an inconsistent focus list.
26
Chapter 2: CLI Commands
dbarrier
Barriers can create deadlocks. For example, if two threads participate in two different
barriers, each could be left waiting at different barriers, barriers that can never be satisfied. A deadlock can also occur if a barrier is set in a procedure that will never be invoked
by a thread in the affected set. If a deadlock occurs, use the ddelete command to remove
the barrier since deleting the barrier also releases any threads held at the barrier.
The –stop_when_hit option tells TotalView what other threads it should
stop when a thread arrives at a barrier.
The –stop_when_done option controls the set of additional threads that
TotalView will stop when the barrier is finally satisfied. That is, you can also
stop an additional collection of threads after the last expected thread
arrives and all the threads held at the barrier are released. Normally, you
will want to stop the threads contained in the control group.
The none argument for these options indicate that the CLI should not stop
additional threads.
■
■
If –stop_when_hit is none when a thread hits a thread barrier, TotalView
just stops that thread; it does not stop other threads.
If –stop_when_done to none, TotalView does not stop additional threads,
aside from the ones that are already stopped at the barrier.
TotalView plants the barrier point in the processes or groups specified in
the current focus. If the current focus:
■
■
■
Does not indicate an explicit group, the CLI creates a process barrier
across the share group.
Indicates a process group, the CLI creates a process barrier that is satisfied when all members of that group reach the barrier.
Indicates a thread group, TotalView creates a thread barrier that is satisfied when all members of the group arrive at the barrier.
The following example illustrates these differences. If you set a barrier with
the focus set to a control group (which is the default), TotalView creates a
process barrier. This means that the –stop_when_hit value is set to process
even though you specified thread.
d1.<> dbarrier 580 –stop_when_hit thread
2
d1.<> ac 2
1 shared action point for group 3:
2 addr=0x120005598 [../regress/fork_loop.cxx#580] Enabled
(barrier)
Share in group: true
Stop when hit: process
Stop when done: process
process barrier; satisfaction set = group 1
TotalView Reference Guide: version 6.3.1
27
2. CLI Commands
If you omit a stop option, TotalView sets the default behavior by using the
BARRIER_STOP_ALL and BARRIER_STOP_WHEN_DONE variables. For more
information, see dset.
dbarrier
However, if you create the barrier with a specific workers focus,
stop_when_hit remains set to thread:
1.<> baw 580 –stop_when_hit thread
1
d1.<> ac 1
1 unshared action point for process 1:
1 addr=0x120005598 [../regress/fork_loop.cxx#580]
Enabled (barrier)
Share in group: false
Stop when hit: thread
Stop when done: process
thread barrier; satisfaction set = group 2
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
ba
{dbarrier}
Defines a barrier.
baw
{dfocus pW dbarrier
–stop_when_done process}
Creates a thread barrier across
the worker threads in the
process of interest. TotalView
sets the set of threads stopped
when the barrier is satisfied to
the process containing the
satisfaction set.
BAW
{dfocus gW dbarrier
–stop_when_done group}
Creates a thread barrier across
the worker threads in the share
group of interest. The set of
threads stopped when the
barrier is satisfied will be the
entire control group.
dbarrier 123
Stops each process in the control group when it arrives
at line 123. After all arrive, the barrier is satisfied and
TotalView releases all processes.
dfocus {p1 p2 p3} dbarrier my_proc
Holds each thread in processes 1, 2, and 3 as it arrives
at the first executable line in procedure my_proc. After
all arrive, the barrier is satisfied and TotalView releases
all processes.
dfocus gW dbarrier 642 –stop_when_hit none
Sets a thread barrier at line 642 on the workers group.
The process is continued automatically as each thread
arrives at the barrier. That is, threads that are not at
this line continue running.
28
Chapter 2: CLI Commands
dbreak
dbreak
Defines a breakpoint
Format:
Creates a breakpoint at a source location
dbreak source-loc [ –p | –g | –t ] [ [ –l lang ] –e expr ]
Creates a breakpoint at an address
dbreak –address addr [ –p | –g | –t] [ [ –l lang ] –e expr ]
Arguments:
source-loc
–p
–g
–t
–l lang
–e expr
Description:
The dbreak command defines a breakpoint or evaluation point that
TotalView triggers when execution arrives at the specified location. The ID
of the new breakpoint is returned.
Each thread stops when it arrives at a breakpoint.
TotalView Reference Guide: version 6.3.1
29
2. CLI Commands
–address addr
The breakpoint location specified as a line number or
as a string containing a file name, function name, and
line number, each separated by # characters; for example, #file#line. Defaults are constructed if you omit
parts of this specification. For more information, see
“Qualifying Symbol Names” in Chapter 12 of the TotalView
Users Guide.
The breakpoint location specified as an absolute
address in the address space of the program.
Tells TotalView to stop the process that hit this breakpoint. You can set this option as the default by setting
the STOP_ALL variable to process. See dset on page 95
for more information.
Tells TotalView to stop all processes in the process’s
control group when the breakpoint is hit. You can set
this option as the default by setting the STOP_ALL variable to group. See dset on page 95 for more information.
Tells TotalView to stop the thread that hit this breakpoint. You can set this option as the default by setting
the STOP_ALL variable to thread. See dset on page 95
for more information.
Sets the programming language used when you are
entering expression expr. The languages you can enter
are c, c++, f7, f9, and asm (for C, C++, FORTRAN 77,
Fortran 9x, and assembler). If you do not specify a language, TotalView assumes that you wrote the expression in the same language as the routine at the
breakpoint.
When the breakpoint is hit, TotalView will evaluate
expression expr in the context of the thread that hit the
breakpoint. The language statements and operators
you can use are described in Chapter 14 of the TotalView
Users Guide.
dbreak
Specifying a procedure name without a line number tells the CLI to set an
action point at the beginning of the procedure. If you do not name a file,
the default is the file associated with the current source location.
The CLI may not be able to set a breakpoint at the line you specify. This
occurs when a line does not contain an executable statement.
If you try to set a breakpoint on a line at which the CLI cannot stop execution, it sets one at the nearest following line where it can halt execution.
When the CLI displays information on a breakpoint’s status, it displays the
location where execution will actually stop.
If the CLI encounters a stop group breakpoint, it suspends each process in
the group as well as the process containing the triggering thread. The CLI
then shows the identifier of the triggering thread, the breakpoint location,
and the action point identifier.
TotalView determines the default focus width based on the setting of the
SHARE_ACTION_POINT variable. If it is set to true, the default is group. Otherwise, it is process.
One possibly confusing aspect of using expressions is that their syntax differs from that of Tcl. This is because you will need to embed code written in
Fortran, C, or assembler within Tcl commands. In addition, your expressions will often include TotalView built-in functions. For example, if you
want to use the TotalView $tid built-in function, you will need to type it as
\$tid.
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
b
{break}
Sets a breakpoint
bt
{dbreak t}
Sets a breakpoint just on the thread of
interest
For all examples, assume the current process set is d2.< when the breakpoint is defined.
dbreak 12
Suspends process 2 when it reaches line 12. However,
if the STOP_ALL variable is set to group, all other processes in the group are stopped. In addition, if you
have set the SHARE_ACTION_POINT variable to true, the
breakpoint is placed in every process in the group.
dbreak –address 0x1000764
b 12 –g
Suspends process 2 when address 0x1000764 is
reached.
Suspends all processes in the current control group
when line 12 is reached.
dbreak 57 –l f9 –e {goto $63}
Causes the thread that struck the breakpoint to transfer to line 63. The host language for this statement is
Fortran 90 or Fortran 95.
30
Chapter 2: CLI Commands
dbreak
dfocus p3 b 57 –e {goto $63}
In process 3, sets the same evaluation point as the previous example.
2. CLI Commands
TotalView Reference Guide: version 6.3.1
31
dcache
dcache
Clears the remote library cache
Format:
Arguments:
dcache –flush
Description:
The dcache –flush command tells TotalView to remove the library files that
it places in your cache. This cache is located in the .totalview/lib_cache
subdirectory contained in your home directory.
–flush
Delete all files from the library cache that are not currently being used.
When you are debugging programs on remote systems that use libraries
that either do not exist on the host or whose version differ, TotalView copies the library files into your cache. This cache can become large.
TotalView automatically deletes cached library files that it hasn't used in
the last week. If you need to reclaim additional space, this command will
remove files not currently being used and that are not quite old enough for
TotalView to automatically delete.
32
Chapter 2: CLI Commands
dcheckpoint
dcheckpoint
Format:
Creates a checkpoint image of processes (IBM and SGI)
Create a checkpoint on SGI IRIX
dcheckpoint [ after_checkpointing ] [ –by process_set ] [ –no_park ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –no_preserve_ids ] [ –force ] checkpoint-name
Create a checkpoint on IBM AIX
dcheckpoint [ –delete | –halt ]
Arguments:
after_checkpointing
–delete
–go
–halt
–by process_set
ash
pgid
sid
–no_park
(SGI only) Indicates the set of processes that will be
checkpointed. If you do not use a process_set option,
TotalView only checkpoints the focus process. (On AIX,
the checkpoint is the scope of the Parallel Environment
job.) Your options are:
Checkpoint the array session.
Checkpoint the entire UNIX process group.
Checkpoint the entire process session.
(SGI only) Tells TotalView that it should not park all processes before TotalView begins checkpointing them. If
you use this option, you will also need to use the
drestart command’s –no_unpark option. Checkpoints
that will be restarted from a shell must use this option.
–ask_attach_parallel
(SGI only) Asks if TotalView should reattach to parallel
processes of a parallel job. (Some systems automatically detach you from processes being checkpointed.)
–no_attach_parallel
(SGI only) Tells TotalView that it should not reattach to
processes from which the checkpointing processes
detached. (Some systems automatically detach you
from processes being checkpointed.)
–no_preserve_ids
–force
TotalView Reference Guide: version 6.3.1
(SGI only) Lets TotalView assign new IDs when it
restarts a checkpoint. If you do not use this option, the
same IDs are used.
(SGI only) Tells TotalView to overwrite an existing
checkpoint.
33
2. CLI Commands
–detach
Defines the state of the process both before and after
the checkpoint. Use one of the following options:
Processes exit after being checkpointed.
(SGI only) Processes continue running after being
checkpointed. In addition, TotalView detaches from
them.
(SGI only) Processes continue running after being
checkpointed.
Processes halt after they are checkpointed.
dcheckpoint
checkpoint-name
Description:
(SGI only) The name being assigned to the checkpoint.
TotalView ignores this name if you are creating a checkpoint on an IBM/RS6000 machine.
The dcheckpoint command saves program and process information into
the checkpoint-name file. This information includes process and group IDs.
Some time later, you will use the drestart command to restart the program.
This command does not save TotalView breakpoint information. If you need to save
them, use the dactions command.
The following restrictions exist when you are trying to checkpoint IRIX processes.
■
■
IRIX will not checkpoint a process that is running remotely and which
communicates using sockets. As the TotalView Debugger Server (tvdsvr)
uses sockets to redirect stdin, stdout, and stderr, you will need to used
the drun command to modify the way your processes send information
to a tty before creating a checkpoint.
If you are using SGI MPI, you need to use the -cpr command-line option,
which, if conditions are correct, you’ll be able to create a checkpoint.
Use the ASH option with MPI checkpoints
The after_checkpointing options let you specify what happens after the checkpoint operation concludes. If you do not specify an option, the CLI tells the
checkpointed processes that they should stop. This lets you investigate a
program’s state at the checkpoint position. In contrast, –go tells the CLI
that it should let the processes continue to run. The –detach and –halt
options are used less frequently. The –detach option shuts down the CLI
and leaves the processes running. This command’s –halt option is similar
to –detach, differing only in that processes started by the CLI and TotalView
are also terminated.
The process_set options tell TotalView which processes it should checkpoint.
While the focus set can only contain one process, processes in the same
process group, process session, process hierarchy, or array session can
also be included in the same checkpoint. If you do not use one of the –by
options, TotalView only checkpoints the focus process.
If the focus group contains more than one process, the CLI displays an
error message.
Just before TotalView begins checkpointing your program, it temporarily
stops (that is, parks) the processes that are being checkpointed. Parking
ensures that the processes do not run freely after a dcheckpoint or drestart
operation. (If they did, your code would begin running before you get control of it.) If you will be restarting the checkpoint file outside of TotalView,
you must use the –no_park option.
When creating the checkpoint, the CLI detaches from processes before
they are checkpointed. By default, the CLI automatically reattaches to
them. If you do not want this to occur, use the –no_attach_parallel option
34
Chapter 2: CLI Commands
dcheckpoint
to tell the CLI that it shouldn’t reattach, or use the –ask_attach_parallel
option to indicate that it should ask you if it should reattach.
Examples:
dcheckpoint check1
Checkpoints the current process. TotalView writes the
checkpoint information into the check1 file. These processes stop.
f3 dcheckpoint check1
Checkpoints process 3. Process 3 stops. TotalView
writes the checkpoint information into the check1 file.
f3 dcheckpoint –go check1
f3 dcheckpoint –by pgid –detach check1
Checkpoints process 3 and all other processes in the
same UNIX process group. All of the checkpointed processes continuing running but they run detached from
the CLI. TotalView writes the checkpoint information
into the check1 file.
TotalView Reference Guide: version 6.3.1
35
2. CLI Commands
Checkpoints process 3. Process 3 continues to run.
TotalView writes the checkpoint information into the
check1 file.
dcont
dcont
Continues execution and waits for execution to stop
Format:
Description:
dcont
The dcont command continues all processes and threads in the current
focus and then waits for all of them to stop.
This command is a Tcl macro whose definition is as follows:
proc dcont {args} {uplevel dgo; "dwait $args" }
This behavior is often what you want to do in scripts. It is seldom what you
want to do interactively.
You can interrupt this action by typing Ctrl+C. This tells TotalView to stop executing
these processes.
This command has no arguments.
A dcont command completes when all threads in the focus set of processes stop executing.
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
co
{dcont}
Resume
CO
{dfocus g dcont}
Group-level resume
dcont
Resumes execution of all stopped/runnable threads
belonging to processes in the current focus. (Threads
held at barriers are not affected.) The command blocks
further input until all threads in all target processes
stop. After the CLI displays its prompt, you can enter
additional commands.
dfocus p1 dcont
Resumes execution of all stopped/runnable threads
belonging to process 1. The CLI does not accept additional commands until the process stops.
dfocus {p1 p2 p3} co
CO
36
Resumes execution of all stopped/runnable threads
belonging to processes 1, 2, and 3.
Resumes execution of all stopped/runnable threads
belonging to the current group.
Chapter 2: CLI Commands
ddelete
ddelete
Deletes action points
Format:
Deletes some action points
ddelete action-point-list
Deletes all action points
ddelete –a
Arguments:
action-point-list
–a
Description:
A list of the action points being deleted.
Tells TotalView to delete all action points in the current
focus.
If you delete a barrier point, the CLI releases the processes and threads
held at it.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
de
{ddelete}
Deletes action points
ddelete 1 2 3
ddelete –a
Deletes breakpoints 1, 2, and 3.
Deletes all action points associated with processes in
the current focus.
dfocus {p1 p2 p3 p4} ddelete –a
Deletes all the breakpoints associated with processes 1
through 4. Breakpoints associated with other threads
are not affected.
dfocus a de –a
Deletes all action points known to the CLI.
TotalView Reference Guide: version 6.3.1
37
2. CLI Commands
The ddelete command permanently removes one or more action points.
The argument to this command lets you specify which action points the CLI
should delete. The –a option indicates that the CLI should delete all action
points.
ddetach
ddetach
Detaches from processes
Format:
Description:
ddetach
The ddetach command detaches the CLI from all processes in the current
focus. This undoes the effects of attaching the CLI to a running process; that
is, the CLI releases all control over the process, eliminates all debugger
state information related to it (including action points), and allows the process to continue executing in the normal run-time environment.
This command has no arguments.
You can detach any process controlled by the CLI; the process being
detached does not have to be originally loaded with a dattach command.
After this command executes, you are no longer able to access program
variables, source location, action point settings, or other information
related to the detached process.
If a single thread serves as the set, the CLI detaches the process containing
the thread.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
det
{ddetach}
Detaches from processes
ddetach
Detaches the process or processes that are in the current focus.
dfocus {p4 p5 p6} det
dfocus g2 det
38
Detaches processes 4, 5, and 6.
Detaches all processes in the control group associated
with process 2.
Chapter 2: CLI Commands
ddisable
ddisable
Temporarily disables action points
Format:
Disables some action points
ddisable action-point-list [ –block number-list]
Disables all action points
ddisable –a
Arguments:
action-point-list
–block number-list
Description:
The ddisable command temporarily deactivates action points. This command does not, however, delete them.
The first form of this command lets you explicitly name the IDs of the
action points being disabled. The second form lets you disable all action
points.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
di
{ddisable}
Temporarily disables action points
ddisable 3 7
di –a
Disables the action points whose IDs are 3 and 7.
Disables all action points in the current focus.
dfocus {p1 p2 p3 p4} ddisable –a
Disables action points associated with processes 1
through 4. Action points associated with other processes are not affected.
di 1 -block 3 4 Disables the action points associated with blocks three
and four. That is, one logical action point can map to
more than one actual action point if you’ve set the
action point at an ambiguous location.
ddisable 1 2 -block 3 4
Disables the action points associated with blocks three
and four in both action points.
TotalView Reference Guide: version 6.3.1
39
2. CLI Commands
–a
A list of the action points being disabled.
If you’ve set a breakpoint on a line that is ambiguous,
use this option to say which instances should be disabled. You can obtain a list of these numbers if you use
the dactions command.
Tells TotalView to disable all action points.
ddlopen
ddlopen
Dynamically loads shared object libraries
Format:
Loads a shared object library
ddlopen [ –now | –lazy ] [ –local | –global ] [ –mode int ] filespec
Displays information about shared object libraries
ddlopen [ –list dll-ids... ]
Arguments:
–now
–lazy
–local
–global
–mode int
filespec
–list
Description:
Include RTLD_NOW in dlopen’s mode argument. (now
means immediately resolve all undefined symbols.)
Include RTLD_LAZY in dlopen’s mode argument. (lazy
means that dlopen() does not try to resolve unresolved
symbols. Instead, symbols are resolved as code is executed.)
Include RTLD_GLOBAL in dlopen’s mode argument.
(local means that library symbols are not available to
libraries that the program subsequently loads.)
Include RTLD_LOCAL in dlopen’s mode argument. (global means that library symbol are available to libraries
that the program subsequently loads.)
The integer arguments are ORed into the other mode
flags passed to dlopen(). See your operating system’s
documentation for information on these flags.
The shared library being loaded.
Displays information about the listed dll-ids. If you omit
this option or use -list without a list dll-ids, TotalView
displays information about all dll-ids.
The ddlopen command Dynamically load shared object libraries, or list the
shared object libraries that were loaded by this command or the Tools >
Dynamic Libraries command.
If use a filespec argument, TotalView performs a dlopen(3) operation upon
this file in each process of the current P/T set. On AIX, you can add a
parenthesized library module name to the end of the filespec.
dlopen(3), dlerror(3), and other related routines are not part of the default runtime
libraries on AIX, Solaris, and Red Hat Linux. Instead, they are within the libdl system
library. Consequently, you must link your program using the –ldl option if you want to
use the ddlopen command.
The –now and –lazy options indicate if dlopen will immediately resolve
unresolved symbol references, or if it should defer resolving them until the
target program references them. If you don’t use either switch, TotalView
uses your operating system's default. (Not all platforms support both alternatives. For example, AIX treats RTLD_LAZY the same as RTLD_NOW).
The –local and –global options determine if symbols from the newly loaded
library are available to resolve references. If you don’t use either option,
TotalView uses the target operating system's default. (HP Tru 64 UNIX
40
Chapter 2: CLI Commands
ddlopen
doesn't support either alternative; its operation is equivalent to –global.
IRIX, Solaris, and Linux only support –global; if you don’t specify an option,
the default is –local.)q
After you enter this command, the CLI waits until all dlopen calls complete
across the current focus. The CLI will then return a unique dll-id and then
display its prompt, which means you can enter additional CLI commands.
However, if an event occurs (for example, a $stop, a breakpoint in user
function called by static object constructors, a SEGV, etc.), ddlopen will
throw an exception that describes the event. The first exception subcode
in the errorCode variable is the dll-id for the suspended dlopen calls.
If an error occurs while executing dlopen(), TotalView calls the dlerror()
function in the target process, and then prints the returned string.
Every dll-id is also a valid breakpoint ID, representing the expressions used
to load and unload DLLs; you can manipulate these breakpoints using the
TV::expr command.
If you do not use a filespec or if you use the –list option without naming an
dll-ids, TotalView prints information about objects loaded using ddlopen. If
you do name any dll-ids, TotalView prints information is printed about DLLs
loaded into all processes in the focus set; otherwise, TotalView prints information about just those DLLs. ddlopen prints its output directly to the
console.
The ddlopen command calls the dlopen() function and it can change the
string returned by dlerror(). It can also change the values returned to the
application by any subsequent dlerror() call.
Examples:
ddlopen "mpistat.so"
Load mpistat.so. The returned argument lists the process into which TotalView loaded the library.
dfocus g ddlopen "mpistat.so(mpistat.o)"
Load the module mpistat.o in the AIX DLL library
mpistat.so into all members of the current process’s
control group:
ddlopen -lazy -global "mpistat.so"
ddlopen
TotalView Reference Guide: version 6.3.1
Load mpistat.so into process 1, don't resolve outstanding application symbol requests to point to mpistat.
However, the symbols in this library will be used if they
need to be.
Print list of shared objects dynamically loaded by
ddlopen.
41
2. CLI Commands
A dll-id describes a shareable object that was dynamically loaded by
ddlopen. You can use the TV:dll command to obtain information about and
delete these objects. If all dlopen() calls return immediately, the ddlopen
command returns a unique dll-id that you can also use with the TV::dll command.
ddown
ddown
Moves down the call stack
Format:
ddown [ num-levels ]
Arguments:
num-levels
Description:
The ddown command moves the selected stack frame down one or more
levels. It also prints the new frame’s number and function name.
Number of levels to move down. The default is 1.
Call stack movements are all relative, so ddown effectively “moves down”
in the call stack. (If “up” is in the direction of main(), then “down” is back to
where you were before moving through stack frames.)
Frame 0 is the most recent—that is, the currently executing—frame in the
call stack, frame 1 corresponds to the procedure that invoked the currently
executing one, and so on. The call stack’s depth is increased by one each
time a procedure is entered, and decreased by one when it is exited.
The command affects each thread in the focus. You can specify any collection of processes and threads as the target set.
In addition, the ddown command modifies the current list location to be
the current execution location for the new frame; this means that a dlist
command displays the code surrounding this new location.
The context and scope changes made by this command remain in effect
until the CLI executes a command that modifies the current execution
location (for example, dstep), or until you enter a dup or ddown command.
If you tell the CLI to move down more levels than exist, the CLI simply
moves down to the lowest level in the stack (which was the place where
you began moving through the stack frames).
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
d
{ddown}
Moves down the call stack
ddown
Moves down one level in the call stack. As a result, for
example, dlist commands that follow will refer to the
procedure that invoked this one. Here is an example of
what is printed after you enter this command:
0 check_fortran_arrays_ PC=0x10001254,
FP=0x7fff2ed0 [arrays.F#48]
d 5
42
Moves the current frame down five levels in the call
stack.
Chapter 2: CLI Commands
denable
denable
Enables action points
Format:
Enables some action points
denable action-point-list [ –block number-list]
Enables all disabled action points in the current focus
denable –a
Arguments:
action-point-list
–a
–block number-list
The denable command reactivates action points that you had previously
disabled with the ddisable command. The –a option tells the CLI to enable
all action points in the current focus.
If you have not saved the ID values of disabled action points, you can use
the dactions command to obtain a list of this information.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
en
{denable}
Reenables action points
denable 3 4
Enables two previously identified action points. These
action points were previously disabled with the
ddisable command.
dfocus {p1 p2} denable –a
Enables all action points associated with processes 1
and 2. Settings associated with other processes are not
affected.
Enables all action points associated with the current
en –a
focus.
Enables all actions points in all processes.
f a en –a
en 1 -block 3 4 Enables the action points associated with blocks three
and four. That is, one logical action point can map to
more than one actual action point if you’ve set the
action point at an ambiguous location.
denable 1 2 -block 3 4
Enables the action points associated with blocks three
and four in both action points.
TotalView Reference Guide: version 6.3.1
43
2. CLI Commands
Description:
The identifiers of the action points being enabled.
Tells TotalView to enable all action points.
If you’ve set a breakpoint on a line that is ambiguous,
use this option to say which instances should be
enabled. You can obtain a list of these numbers if you
use the dactions command.
dflush
dflush
Unwinds stack from suspended computations
Format:
Removes the top-most suspended expressions evaluations
dflush
Removes the computation indicated by a suspended evaluation ID and all
those that precede it
dflush susp-eval-id
Removes all suspended computations
dflush –all
Arguments:
susp-eval-id
–all
Description:
The ID returned or thrown by the dprint command or
which is printed by the dwhere command.
Flushes all suspended evaluations within the current
focus.
The dflush command unwinds the stack to eliminate frames generated by
suspended computations. Typically, these can occur if you had used the
dprint –nowait command. However, this situation can occur, for example, if
an error occurred in a function call in an eval point or in an expression
within a Tools > Evaluate window or if you use a $stop function.
You can use this command in three ways:
■
■
■
If you don’t use an argument, the CLI unwinds the top-most suspended
evaluation in all threads in the current focus.
If you use a susp-eval-id, the CLI unwinds each stack of all threads in the
current focus, flushing all pending computations up to and including the
frame associated with the ID.
If you use the –all option, the CLI flushes all suspended evaluations in all
threads in the current focus.
If no evaluations are suspended. the CLI ignores this command. If you do
not indicate a focus width, the default focus is thread level.
Examples:
The following example uses dprint to place five suspended routines on the
stack. It then uses dflush to remove them. As you follow the example,
you’ll see the three different ways you can use the dflush command.
#
# Create 5 suspended functions
#
d1.<> dprint -nowait nothing2(7)
7
Thread 1.1 hit breakpoint 4 at line
d1.<> dprint -nowait nothing2(8)
8
Thread 1.1 hit breakpoint 4 at line
d1.<> dprint -nowait nothing2(9)
9
Thread 1.1 hit breakpoint 4 at line
d1.<> dprint -nowait nothing2(10)
10
Thread 1.1 hit breakpoint 4 at line
d1.<> dprint -nowait nothing2(11)
44
310 in "nothing2(int)"
310 in "nothing2(int)"
310 in "nothing2(int)"
310 in "nothing2(int)"
Chapter 2: CLI Commands
dflush
11
Thread 1.1 hit breakpoint 4 at line 310 in "nothing2(int)"
...
#
# Here’s what the top of the call stack looks like:
#
PC=0x00012520, FP=0xffbef130 [fork.cxx#310]
Function Call (11) ****************
PC=0x00012520, FP=0xffbef220 [fork.cxx#310]
Function Call (10) ****************
PC=0x00012520, FP=0xffbef310 [fork.cxx#310]
Function Call (9) ****************
PC=0x00012520, FP=0xffbef400 [fork.cxx#310]
Function Call (8) ****************
PC=0x00012520, FP=0xffbef4f0 [fork.cxx#310]
Function Call (7) ****************
PC=0x00013fd8, FP=0xffbef648 [fork.cxx#1120]
PC=0x00014780, FP=0xffbef6c8 [fork.cxx#1278]
#
# Use dflush to remove the last item pushed onto
# the stack. Notice the frame associated with “11”
# is no longer there
#
d1.<> dflush
d1.<> dwhere
0 nothing2
1 ***** Eval
2 nothing2
3 ***** Eval
4 nothing2
5 ***** Eval
6 nothing2
7 ***** Eval
8 forker
9 fork_wrap
PC=0x00012520, FP=0xffbef220 [fork.cxx#310]
Function Call (10) ****************
PC=0x00012520, FP=0xffbef310 [fork.cxx#310]
Function Call (9) ****************
PC=0x00012520, FP=0xffbef400 [fork.cxx#310]
Function Call (8) ****************
PC=0x00012520, FP=0xffbef4f0 [fork.cxx#310]
Function Call (7) ****************
PC=0x00013fd8, FP=0xffbef648 [fork.cxx#1120]
PC=0x00014780, FP=0xffbef6c8 [fork.cxx#1278]
#
# Use dflush with a suspened ID argument to remove all
# frames up to and including the one associated with
# suspended ID 9. This means that 7 and 8 remain.
#
d1.<> dflush 9
# Top of call stack after dflush 9
d1.<> dwhere
0 nothing2
PC=0x00012520, FP=0xffbef400 [fork.cxx#310]
1 ***** Eval Function Call (8) ****************
2 nothing2
PC=0x00012520, FP=0xffbef4f0 [fork.cxx#310]
3 ***** Eval Function Call (7) ****************
4 forker
PC=0x00013fd8, FP=0xffbef648 [fork.cxx#1120]
5 fork_wrap
PC=0x00014780, FP=0xffbef6c8 [fork.cxx#1278]
#
# Use dflush -all to remove all frames. Only the frames
TotalView Reference Guide: version 6.3.1
45
2. CLI Commands
d1.<> dwhere
0 nothing2
1 ***** Eval
2 nothing2
3 ***** Eval
4 nothing2
5 ***** Eval
6 nothing2
7 ***** Eval
8 nothing2
9 ***** Eval
10 forker
11 fork_wrap
...
dflush
# associated with the program remain.
#
d1.<> dflush -all
# Top of call stack after dflush -all
d1.<> dwhere
0 forker
PC=0x00013fd8, FP=0xffbef648 [fork.cxx#1120]
1 fork_wrap
PC=0x00014780, FP=0xffbef6c8 [fork.cxx#1278]
46
Chapter 2: CLI Commands
dfocus
dfocus
Changes the current (Process/Thread P/T) set
Format:
Changes the target of future CLI commands to this P/T set
dfocus p/t-set
Executes a command in this P/T set
dfocus p/t-set command
Arguments:
p/t-set
command
Description:
The dfocus command changes the set of processes, threads, and groups
upon which a command will act. This command can change the focus for
all commands that follow or just the command that immediately follows.
The dfocus command always expects a P/T value as its first argument. This
value can either be a single arena specifier or a list of arena specifiers. The
default focus is d1.<, which selects the first user thread. The d (for default)
indicates that each CLI command is free to use its own default width.
If you enter an optional command, the focus is set temporarily, and the CLI
executes command in the new focus. After command executes, the CLI
restores focus to its original value. The command argument can be a single
command or a list.
If you use a command argument, dfocus returns the result of the command.
If you do not enter a command, dfocus returns the focus as a string value.
Instead of a P/T set, you can type a P/T set expression. These expressions are described
in “Using P/T Set Operators” in Chapter 11 of the TotalView Users Guide.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
f
{dfocus}
Changes the object upon which a
command acts
dfocus g dgo
Continues the TotalView group containing the focus
process.
dfocus p3 {dhalt; dwhere}
dfocus 2.3
TotalView Reference Guide: version 6.3.1
Stops process 3 and displays backtraces for each of its
threads.
Sets the focus to thread 3 of process 2, where the “2”
and the “3” are TotalView’s process and thread identifier values. The focus is set to d2.3.
47
2. CLI Commands
A set of processes and threads. This set defines the
target upon which the CLI commands that follow will
act. You can also use a P/T set filter as one or more of
the elements in this list.
A CLI command, which when it executes, operates
upon its own local focus.
dfocus
dfocus 3.2
dfocus .5
dfocus g dstep
Sets and then resets command focus. A focus command that includes a dot and omits the process value
tells the CLI to use the current process. Thus, this
sequence of commands changes the focus to process 3,
thread 5 (d3.5).
Steps the current group. Note that while the thread of
interest is determined by the current focus, the command acts on the entire group containing that thread.
dfocus {p2 p3} {dwhere ; dgo}
Performs a backtrace on all threads in processes 2 and
3 and then tells these processes to execute.
f 2.3 {f p w; f t s; g}
dfocus p1
dfocus a
Executes a backtrace (dwhere) on all the threads in
process 2, steps thread 3 in process 2 (without running
any other threads in the process), and continues the
process.
Changes the current focus to include just those threads
currently in process 1. The width is set to process. The
CLI sets the prompt to p1.<.
Changes the current set to include all threads in all
processes. When you execute this command, you will
notice that your prompt changes to a1.<. This command alters the CLI’s behavior so that actions that previously operated on a thread now apply to all threads
in all processes.
dfocus gW dstatus
Displays the status of all worker threads in the control
group. The width is group level and the target is the
workers group.
dfocus pW dstatus
Displays the status of all worker threads in the current
focus process. The width is process level and the target
is the workers group.
f {breakpoint(a) | watchpoint(a)} st
Shows all threads that are stopped at breakpoints or
watchpoints.
f {stopped(a) – breakpoint(a)} st
Shows all stopped threads that are not stopped at
breakpoints.
You will find many other dfocus examples in Chapter 11 of the TotalView
Users Guide.
48
Chapter 2: CLI Commands
dga
dga
Displays global array variables
Format:
Arguments:
dga [–lang lang_type] [handle_or_name] [slice]
–lang
lang_type
handle_or_name
Description:
The dga command tells TotalView to display information about Global
Arrays.
If the focus includes more than one process, TotalView prints a list for each
process in the focus. Because the arrays are global, each list will be identical. If there is more than one thread in the focus, TotalView prints the value
of the array as it is seen from that thread.
In almost all cases, you will want to change the focus to d2.< so that you
don’t involve a starter process such as prun.
Examples:
dga
TotalView displays a list of global arrays. For example:
lb_dist
Handle
Ghosts
C type
Forran Type
-1000
yes
<double>[129][129][27]
<double precision(27,129,129)
bc_mask
Handle
Ghosts
C type
Fortran Type
-999
yes
long[129][129]
<integer>(129,129)
dga bc_mask (:2,:2)
Displays a slice of the bc_mask variable. For example:
bc_mask(:2,:2) = {
(1,1) = 1 (0x00000001)
(2,1) = 1 (0x00000001)
(1,2) = 1 (0x00000001)
(2,2) = 0 (0x00000000)
}
TotalView Reference Guide: version 6.3.1
49
2. CLI Commands
slice
Tells TotalView which language conventions it should
use when displaying information. If you omit this
option, TotalView uses the language used by the thread
of interest.
Tells TotalView which language type it uses when displaying a global array. Your choices are either “c” or “f ”.
Tells TotalView to display an array. This can either be a
numeric handle or the name of the array. If you omit
this argument, TotalView displays a list of all Global
Arrays.
Tells TotalView that is should only display a slice (that
is, part of an array). If you are using C, you will have to
place the array designators within braces {} as “[” has
special meaning in Tcl.
dga
dga -lang c -998 {[:1]{:1]}
Displays the same bc_mask variable as was displayed in
the previous example in C format. In this case, the variable is referred to by its handle.
50
Chapter 2: CLI Commands
dgo
dgo
Resumes execution of processes
Format:
Description:
dgo
The dgo command tells all non-held processes and threads in the current
focus to resume execution. If the process does not exist, this command
creates it, passing it the default command arguments. These can be arguments passed into the CLI, or they can be the arguments set with the
drerun command. If you are also using the TotalView GUI, this value can be
set by using the Process > Startup command.
This command has no arguments.
If a process or thread is held, it ignores this command.
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
g
{dgo}
Resumes execution
G
{dfocus g dgo}
Group resume
dgo
G
f p g
f g g
f gL g
f pL g
f t g
TotalView Reference Guide: version 6.3.1
Resumes execution of all stopped/runnable threads
belonging to processes in the current focus. (Threads
held at barriers are not affected.)
Resumes execution of all threads in the current control
group.
Continues the current process. Only threads that are
not held are actually allowed to run.
Continues all processes in the control group. Only processes and threads that are not held are allowed to
run.
Continues all threads in the share group that are at the
same PC as the thread of interest.
Continues all threads in the current process that are at
the same PC as the thread of interest.
Continues a single thread.
51
2. CLI Commands
You cannot use a dgo command when you are debugging a core file, nor
can you use it before the CLI loads an executable and starts executing it.
dgroups
dgroups
Manipulates and manages groups
Format:
Adds members to thread and process groups
dgroups –add [ –g gid ] [ id-list ]
Deletes groups
dgroups –delete [ –g gid ]
Intersects a group with a list of processes and threads
dgroups –intersect [ –g gid ] [ id-list ]
Prints process and thread group information
dgroups [ –list ] [ pattern-list ]
Creates a new thread or process group
dgroups –new [ thread_or_process ] [ –g gid ] [ id-list ]
Removes members from thread or process groups
dgroups –remove [ –g gid ] [ id-list ]
Arguments:
–g gid
id-list
pattern-list
thread_or_process
Description:
The dgroups command lets you perform the following functions:
■
■
■
■
■
■
52
The group ID upon which the command operates. The
gid value can be an existing numeric group ID, an existing group name, or, if you are using the –new option, a
new group name.
A Tcl list containing process and thread IDs. Process
IDs are integers; for example, “2” indicates process 2.
Thread IDs define a pid.tid pair and look like decimal
numbers; for example, “2.3” indicates process 2, thread
3. If the first element of this list is a group tag such as
the word control, the CLI ignores it. This makes it easy
to insert all members of an existing group as the items
to be used in any of these operations. (See the dset
command’s discussion of the GROUP(gid) variable for
information on group designators.) These words appear
in some circumstances when TotalView returns lists of
elements in P/T sets.
A pattern to be matched against group names. The pattern is a Tcl regular expression.
Keywords indicating that TotalView will create a new
process or thread group. You can specify one of the following arguments: t, thread, p, or process.
Add members to process and thread groups.
Create a group.
Intersect a group with a set of processes and threads.
Delete groups.
Display the name and contents of groups.
Remove members from a group.
Chapter 2: CLI Commands
dgroups
dgroups –add
The dgroups –add command adds members to one or more thread or process groups. TotalView adds each of these threads and processes to the
group. If you add a:
■
■
Process to a thread group, TotalView adds all of its threads.
Thread to a process group, TotalView adds the thread’s parent process.
You can abbreviate –add to –a.
The CLI returns the ID of this group.
If id-list contains processes and the target is a thread group, the CLI adds
all threads from these processes. If it contains threads and the target is a
process group, TotalView adds the parent process for each thread.
If you specify an id-list and you also use the –g option, the CLI ignores the focus. You
can, of course, use two dgroups -add commands.
Even if you try to add the same object more than once to a group, the CLI
only adds it once.
TotalView does not let you use this command to add a process to a control
group. If you need to perform this operation, you can add it by using the
CGROUP(dpid) variable. For example:
dset CGROUP($mypid) $new_group_id
dgroups –delete
The dgroups –delete command deletes the target group. You can only
delete groups that you create; you cannot delete groups that TotalView creates.
dgroups –intersect
The dgroups –intersect command intersects a group with a set of processes
and threads. If you intersect a thread group with a process, the CLI uses all
of the process’s threads. If you intersect a process group with a thread, the
CLI uses the thread’s process.
After this command executes, the group no longer contains members that
were not in this intersection.
You can abbreviate –intersect to –i.
dgroups –list
The dgroups –list command prints the name and contents of process and
thread groups. If you specify a pattern-list as an argument, the CLI only
prints information about groups whose names match this pattern.
TotalView Reference Guide: version 6.3.1
53
2. CLI Commands
The items being added can be explicitly named using an id-list. If you do not
use an id-list, the CLI adds the threads and processes in the current focus.
Similarly, you can name the group to which the CLI adds members if you
use the –g option. If you omit this option, the CLI uses the groups in the
current focus.
dgroups
When entering a list, you can specify a pattern. The CLI matches this pattern
against TotalView’s list of group names by using the Tcl regex command.
If you do not enter a pattern, the CLI only displays groups that you have created which
have nonnumeric names.
The CLI returns information from this command; it is not returned.
You can abbreviate –list to –l.
dgroups –new
The dgroups –new command creates a new thread or process group and
adds threads and processes to it. If you use a name with –g, the CLI uses
that name for the group ID; otherwise, it assigns a new numeric ID. If the
group you name already exists, the CLI replaces it with the newly created
group.
The CLI returns the ID of the newly created group.
The items being added can be explicitly named using an id-list. If you do not
use an id-list, the CLI adds the threads and processes in the current focus.
If id-list contains processes and the target is a thread group, the CLI adds
all threads from these processes. If it contains threads and the target is a
process group, TotalView adds the parent process for each thread.
If you specify an id-list and use the –g option, the CLI ignores the focus.You can, of
course, use two dgroups -add commands.
If you are adding more than one object and one of these objects is a duplicate, TotalView will add the nonduplicate objects to the group.
You can abbreviate –new to –n.
dgroups –remove
The dgroups –remove command removes members from one or more
thread or process groups. If you ask to remove a process from a thread
group, TotalView removes all of its threads. If you ask to remove a thread
from a process group, TotalView removes its parent process.
You cannot remove processes from a control group. You can, however,
move a process from one control group to another by using the dset command to assign it to the CGROUP(dpid) variable group.
Also, you cannot use this command on read-only groups such as share
groups.
You can abbreviate –remove to –r.
Command alias:
54
You may find the following alias useful:
Alias
Definition
Meaning
gr
dgroups
Manipulates a group
Chapter 2: CLI Commands
dgroups
Examples:
dgroups –add
f tW gr –add
dgroups –add
Adds the focus thread to its workers group.
Adds the current focus thread to the current focus
group.
set gid [dgroups –new thread ($CGROUP(1))]
Creates a new thread group containing all threads from
all processes in the control group for process 1.
f $a_group/9 dgroups –add
Adds process 9 to a user-defined group.
dgroups –delete
gr –delete –g mygroup
Deletes mygroup.
dgroups –intersect –g 3 3.2
Intersects thread 3.2 with group 3. If group 3 is a thread
group, this command removes all threads except 3.2
from it; if it is a process group, this command removes
all processes except process 3 from it.
f tW gr –i
Intersects the focus thread with its workers group.
f gW gr –i –g mygroup
Removes all nonworker threads from mygroup.
dgroups –list
dgroups –list
Tells TotalView to display information about all named
groups. For example:
ODD_P: {process 1 3}
EVEN_P: {process 2 4}
gr –l *
Tells TotalView to display information about groups in
the current focus.
1: {control 1 2 3 4}
2: {workers 1.1 1.2 1.3 1.4 2.1 2.2 2.3 2.4 3.1
3.2 3.3 3.4 4.1 4.2 4.3 4.4}
3: {share 1 2 3 4}
ODD_P: {process 1 3}
EVEN_P: {process 2 4}
dgroups –new
gr –n t –g mygroup $GROUP($CGROUP(1))
Creates a new thread group named mygroup containing all threads from all processes in the control group
for process 1.
set mygroup [dgroups –new]
Creates a new process group that contains the current
focus process.
dgroups –remove
dgroups –remove –g 3 3.2
Removes thread 3.2 from group 3.
f W dgroups –add
Marks the current thread as being a worker thread.
TotalView Reference Guide: version 6.3.1
55
2. CLI Commands
dgroups –intersect
dgroups
f W dgroups –r
56
Indicates that the current thread is not a workers
thread.
Chapter 2: CLI Commands
dhalt
dhalt
Suspends execution of processes
Format:
Description:
Command alias:
The dhalt command stops all processes and threads in the current focus.
The command has no arguments.
You may find the following aliases useful:
Alias
Definition
Meaning
h
{dhalt}
Suspends execution
H
{dfocus g dhalt}
Group stop
dhalt
f t 1.1 h
TotalView Reference Guide: version 6.3.1
Suspends execution of all running threads belonging to
processes in the current focus. (Threads that are held
at barriers are not affected.)
Suspends execution of thread 1 in process 1. Note the
difference between this command and f 1.< dhalt. If
the focus is set as thread level, this command will halt
the first user thread, which is probably thread 1.
57
2. CLI Commands
Examples:
dhalt
dheap
dheap
Controls heap debugging
Format:
Shows Memory Tracker state
dheap [ –status ]
Enables or disables the Memory Tracker
dheap { –enable | –disable }
Enables or disables Memory Tracker event notification
dheap { –notify | –nonotify }
Displays Memory Tracker information
dheap –info [ –backtrace ] [ start_address [ end_address ] ]
Indicates if an address refers to a deallocated block
dheap –is_dangling address
Locates memory leaks
dheap –leaks [ –check_interior ]
Paints memory with a distinct pattern
dheap –paint [ subcommands ]
Enables and disables block allocation and reallocation notification
dheap –tag_alloc subcommand start_address [ end_address]
Enables and disables the saving and freeing of deallocated memory blocks
dheap –tag_alloc –[no]dont_free_on_dealloc
Enables and disables the retaining (hoarding) of freed memory blocks
dheap –hoard [ subcommands ]
Arguments:
–status
–enable/–disable
–notify/–nonotify
–info
Displays the current state of the Memory Tracker. This
lets you know if a process is capable of having its heap
operations traced and if TotalView will notify you if a
heap event occurs.
If TotalView has stopped a thread because a heap event
occurred, you will see information about this event.
Using the –enable option tells TotalView that it should
use the Memory Tracker the next time you start the
program. The –disable option tells TotalView that it
should not use the Memory Tracker the next time you
start the program.
Using the –notify option tells TotalView that it should
stop your program’s execution when a heap problem
occurs. The –nonotify options tells TotalView that it
shouldn’t stop execution. Even if you type –nonotify,
TotalView will continue tracking heap events.
Displays information about the heap, or regions of the
heap within a range of addresses. If you don’t use the
address arguments, the CLI displays information about
all heap allocations.
–backtrace
Tells the CLI to display backtrace information.
58
Chapter 2: CLI Commands
dheap
start_address
If you just enter a start_address, the CLI reports on all
allocations beginning at and following this address.
end_address
If you also specify an end_address, the CLI reports on all
allocations between start_address and end_address.
–is_dangling address
–leaks
By default, TotalView only checks to see if the starting
location of an allocated memory block is reachable.
–check_interior
When checking for leaks, a block will be considered
“reachable” if the interior portion of an allocated memory block is referenced even though no reference is
made to the start of the block.
–paint [ subcommands ]
Use the dheap –paint command to enable and disable
block painting and to show status information. For
more information on block painting, see “dheap –paint:
Block Painting” on page 63.
If you do not use an argument to –paint, TotalView
shows current block painting status.
–enable_alloc
–enable_dealloc
–enable_alloc_zeroed
These enabling subcommands enable block painting.
They tell TotalView to paint a block when your program’s heap manager allocates, deallocates, or uses a
memory function that returns zeroed memory.
–disable_alloc
–disable_dealloc
–disable_alloc_zeroed
These disabling subcommands disable block painting.
–set_alloc_pattern pattern
–set_dealloc_pattern pattern
Use these two subcommands to set the pattern that
TotalView uses when it paints a block of memory. This
takes effect the next time you restart your program.
The maximum width of pattern can differ from operating system to operating system. However, you can use
fewer numbers than this maximum.
TotalView Reference Guide: version 6.3.1
59
2. CLI Commands
Indicates if the address used as an argument was once
allocated but is now deallocated and has not yet been
recycled by the heap manager.
Locates all memory blocks that were allocated and
which are not reachable. That is, using this command
tells TotalView to locate all dangling memory. For more
information on using this subcommand, see “dheap –
leaks: Detecting Leaks” on page 62.
dheap
dheap –paint –unset_alloc_pattern
dheap –paint –unset_dealloc_pattern
Use these two subcommand to reset the patterns used
when TotalView paints memory to TotalView’s default
values. This takes effect the next time you restart your
program.
–tag_alloc subcommand [ start_address [ end_address] ]
Tells TotalView to notify you when your program deallocates or reallocates a memory block. (For more information, see “dheap –tag_alloc: Deallocation Notification” on
page 64.)
You can specify more than one subcommand in one
dheap –tag_alloc command.
–notify_dealloc
–notify_realloc
Use these two subcommands to enable notification
when your program deallocates or reallocates a memory block. If you do not specify address arguments,
TotalView tags all allocated blocks.
–nonotify_dealloc
–nonotify_realloc
Use these two subcommands to disable deallocation
and reallocation notification. If you do not specify
address arguments, TotalView removes the tag from all
tagged blocks.
start_address
If just a start_address is entered, TotalView either tags or
removes the tag from the block containing this
address. Which action depends upon the subcommand
you use.
end_address
If you also specify an end_address, TotalView either tags
all blocks beginning with the block containing the
start_address and ending with the block containing the
end_address or removes the tag. Which action depends
upon the subcommand you use. If end_address is 0
(zero), TotalView tags or removes the tag from all
addresses beginning with start_address to the end of the
heap.
–[no]dont_free_on_dealloc
If you do not wish deallocated memory to be reused—
this is used in conjunction with hoarding—use the
–dont_free_on_dealloc subcommand. To reenable
memory reuse, use the –nodont_free_on_dealloc subcommand.
–hoard [ subcommands ]
Tells TotalView that it should not surrender allocated
blocks back to your program’s heap manager. If you do
not enter a subcommand, TotalView displays informa-
60
Chapter 2: CLI Commands
dheap
tion about the hoarded blocks. For more information,
see “Memory Reuse: dheap –hoard” on page 64.
–enable_hoarding
–disable_hoarding
Enables and disables hoarding.
–set_max_kb num_kb
Sets the maximum size of the hoarded information.
–set_max_blocks num_blocks
Set the maximum number of hoarded blocks.
–unset_max_kb
–unset_max_blocks
experimental and may be removed.)
Description:
The dheap commands control TotalView’s Memory Tracker. The Memory
Tracker can:
■
■
■
■
■
Tell TotalView that it should use the Memory Tracker’s agent to track
memory errors, stop execution when an error occurs, and display information you’ll need to analyze the error. For more information, see “Notification When “free” Problems Occur” on page 62.
Detect leaked memory by analyzing if a memory block is reachable. For
more information, see “dheap –leaks: Detecting Leaks” on page 62.
Paints memory with a bit pattern when it is allocated and deallocated.
For more information, see “dheap –paint: Block Painting” on page 63.
Notify you when a memory block is deallocated or reallocate. For more
information, see “dheap –tag_alloc: Deallocation Notification” on page 64.
Hoard freed memory so that is not released to the heap manager. For
more information, see “Memory Reuse: dheap –hoard” on page 64.
The “Debugging Memory Problems” chapter of the TotalView Users Guide contains considerable information on using this command to uncover problems that occur when
memory is freed incorrectly. In some circumstances, you will need to link the agent into
your program, which is extensively discussed in that chapter.
In all cases, you need to enable the Memory Tracker by using the dheap
–enable command. Except for when you use commands that display information, you will also have to use the dheap –notify command, which tells
TotalView to tell you when Memory Tracker heap events occur.
If you enable notification, TotalView stops the process when it detects a
heap allocation event. TotalView is always monitoring heap events, even if
you turned notification off. That is, disabling notification means that the
process won’t be stopped when events occur and you aren’t told about
these events.
While you can separately enable and disable notification in any group, process, or thread, you probably only want to control notification on the control group’s master process. Because this is the only process that TotalView
creates, it is the only process where TotalView can control the Memory
TotalView Reference Guide: version 6.3.1
61
2. CLI Commands
–display
Resets a hoarding size value to its default.
Lists blocks currently in the hoard. (This subcommand is
dheap
Tracker’s environment variable. For example, slave processes are normally
created by an MPI starter process or are created as a result of fork/exec. In
these cases, TotalView simply attaches to them.
If you do not use any of dheap’s subcommands, the CLI displays dheap
status information. You would only use the –status option when you want
the CLI to display status information in addition to doing something else.
The information dheap displays may contain a value indicating additional
information:
Value
0x0001
0x0002
0x0004
0x0008
0x0010
0x0020
Meaning
Operation in progress
notify_dealloc
notify_realloc
paint_on_dealloc
dont_free_on_dealloc
hoarded
Notification When “free” Problems Occur
If you type dheap –enable –notify and then run your program, the Memory
Tracker will notify you if a problem occurs when your program tries to free
memory. (For more information, see Chapter 15 of the TotalView Users Guide.)
If you use other subcommands, additional actions can occur. For example, if you use the
–tag_alloc subcommand, TotalView will also notify you when a tagged block is freed,
even if no error occurred when it was freed.
When execution stops, you can type dheap (with no arguments), to show
information about what has happened. You can also use the dheap –info
and dheap –info –backtrace commands to display additional information.
The information displayed by these commands will allow you to locate the
statement in your program that caused the problem.
For each allocated region, the CLI displays the start and end address, and
the length of the region in decimal and hexadecimal.
dheap –leaks: Detecting Leaks
The dheap –leaks command locates memory blocks that were allocated but
which are no longer reachable. After entering this command, TotalView
determines if the beginning of an allocated memory block is reachable. It
then displays a report detailing these blocks. If you use the –check_interior
option, TotalView considers blocks reachable if a pointer exists to memory
inside of an allocated block even if no reference exists to the beginning of
the block.
For example:
d1.<> dheap -leaks
process
1
(5257): total count 12, total bytes 380
* leak
1 -- total count 4 (33.33%), total bytes 200 (52.63%)
-- smallest / largest / average leak: 20 / 80 / 50
62
Chapter 2: CLI Commands
dheap
:
:
:
:
malloc
PC=0x40020f9d [../malloc_wrappers_dlopen.c#149]
main
PC=0x08048862 [local_structure_leak.cxx#45]
__libc_start_main PC=0x400cf177 [/lib/i686/libc.so.6]
_start
PC=0x08048721 [../local_structure_leak]
* leak
2 -- total count 4 (33.33%), total bytes 100 (26.32%)
-- smallest / largest / average leak: 10 / 40 / 25
malloc
PC=0x40020f9d [../malloc_wrappers_dlopen.c#149]
main
PC=0x0804883f [local_structure_leak.cxx#42]
__libc_start_main PC=0x400cf177 [/lib/i686/libc.so.6]
_start
PC=0x08048721 [../local_structure_leak]
:
:
:
:
* leak
In addition to providing backtrace information, this information:
■
■
■
Consolidates leaks made by one program statement into one leak report. For example, leak 1 has four instances.
Reports the amount of memory consumed for a group of leaks. It also
tells you what percentage of leaked memory this one group of memory is
using.
Indicates the smallest and largest leaks size, as well as telling you what
the average leak size is for a group.
You can use the dheap –is_dangling command to determine if an address
refers to a deallocated block. If it does, the address is not being referenced, which means this memory block is dangling.
dheap –paint: Block Painting
When a block is allocated or deallocated, TotalView can paint the block
with a bit pattern. This makes it easy to identify uninitialized blocks, or
blocks pointed to by dangling pointers. In addition, by carefully selecting
the bit pattern, an error can be forced if the memory is used in, for example, a floating point operation, or if a pointer deference’s this memory.
Here are the commands that enable block painting:
dheap –paint –enable_alloc
dheap –paint –enable_dealloc
■ dheap –paint –enable_alloc_zeroed
■
■
Some heap allocation routines such as calloc() return zeroed memory.
Using the –enable_alloc_zeroed command allows you to separately enable
the painting of the memory blocks altered by these kinds of routines. You
would do this if your program relies upon this behavior. If you do enable
painting for routines that zero memory, TotalView uses the same pattern as
it used for a normal allocation.
Disable painting by using the following commands:
■
■
dheap –paint –disable_alloc
dheap –paint –disable_dealloc
TotalView Reference Guide: version 6.3.1
63
2. CLI Commands
:
:
:
:
3 -- total count 4 (33.33%), total bytes 80 (21.05%)
-- smallest / largest / average leak: 20 / 20 / 20
malloc
PC=0x40020f9d [../malloc_wrappers_dlopen.c#149]
main
PC=0x08048822 [local_structure_leak.cxx#39]
__libc_start_main PC=0x400cf177 [/lib/i686/libc.so.6]
_start
PC=0x08048721 [../local_structure_leak]
dheap
■
dheap –paint –disable_alloc_zeroed
By default, the default allocation bit pattern is 0xa110ca7f and the default
deallocation pattern is 0xdeall0cf. You can change these patterns with the
following two commands:
dheap –paint –set_alloc_pattern pattern
■ dheap –paint –set_dealloc_pattern pattern
■
Here are the commands that restore the painting pattern to TotalView’s
default:
■
■
dheap –paint –unset_alloc_pattern
dheap –paint –unset_dealloc_pattern
Finally, if you do not use an argument to the –paint subcommand, the CLI
displays the current settings relating to block painting. This information
includes whether painting is enabled or disabled for allocation, zeroed allocation, and deallocation in addition to the patterns being used.
dheap –tag_alloc: Deallocation Notification
The dheap –tag_alloc –notify_dealloc and dheap –tag_alloc –notify_realloc
subcommands tell TotalView to tag information within the Memory
Tracker’s tables and to notify you when your program either frees a block
or passes it to realloc().
You can tell TotalView which blocks it should tag using the start_address and
end_address arguments to –notify_dealloc and –notify_realloc. You can ell
TotalView that it should notify you when any currently allocated block is
free or reallocated if you do not enter an address argument.
Using the –notify_dealloc subcommand tells TotalView that it should let you
know when a memory block is freed or when realloc() is called with its
length set to zero. If you want notification when other values are passed to
realloc,() you should also use the –notify_realloc subcommand.
You can disable notification using the following two subcommands:
dheap –tag_alloc –nonotify_dealloc
■ dheap –tag_alloc –nonotify_realloc
■
Memory Reuse: dheap –hoard
In some cases, you may not want your system’s heap manager to reuse
memory. You would to this, for example, when you are trying to find problems that occur when more than one process or thread is allocating the
same memory block.
After you enable hoarding, the Memory Tracker adds the deallocated region
to a bounded fifo buffer. It is quite possible for this to use a considerable
amount of memory. You can control the size of the buffer so that TotalView
does not use too much of the heap for this hoarded memory by specifying
the number of regions in the buffer and their overall size.
64
Chapter 2: CLI Commands
dheap
Hoarding is a three-step process, where you must use:
■
■
dheap –enable to tell TotalView to use the Memory Tracker.
dheap –tag_alloc –dont_free_on_dealloc to tell TotalView to tag deallo-
cated memory blocks.
■
dheap –hoard –enable_hoarding to tell TotalView that a deallocated
block should not be released back to the heap manager.
Hoarding is disabled until you explicitly enable it.
The rest of this section is an overview of hoarding commands.
Use the following two commands to enable and disable hoarding:
dheap –hoard –enable_hoarding
■ dheap –hoard –disable_hoarding (this is the default)
■
dheap –hoard –set_max_kb num_kb
Sets the maximum size in kb to which the hoard is
allowed to grow. If the process has not run and the
maximum size is not known, a default value (TBD) is
shown when requesting hoarding information.
dheap –hoard –set_max_blocks num_blocks
Sets the maximum number of blocks the hoard may
contain.
dheap –hoard –unset_max_kb
dheap –hoard –unset_max_blocks
dheap –hoard
Use these commands to restore the hoards default size
and block values. These reset values will be used when
you restart the process.
Shows hoard status information. Five columns are
shown. The first contains “yes” or “no”, which indicates
whether hoarding is enabled. The second and third columns show the maximum size in kb and number of
blocks to which the hoard can grow. The last two columns show the current size of the hoard, again, in kb
and number of blocks.
dheap –hoard –display
This option, which may be removed in a future release,
lists the blocks within the hoard. The blocks are shown
in address order, rather than their fifo order.
Examples
The following example shows the kind of information the CLI will display
after the Memory Tracker locates an error due to memory being incorrectly
freed.
TotalView Reference Guide: version 6.3.1
65
2. CLI Commands
Use the following commands to control the amount of memory within the
heap that is used for the hoarding of freed blocks:
dheap
d1.<> dheap
d1.<> dheap
1
1.1
process:
Enable
Notify
Available
(21144):
yes
yes
yes
free: Address not the start of any allocated block.:
free: existing allocated block:
free: start=0x08049858 length=(17 [0x11])
free: flags: 0x0 (none)
free:
malloc
PC=0x40021f8d [malloc_wrapp.c#149]
free:
main
PC=0x08048533 [free_not_algned.c#31]
free:
__libc_start_main PC=0x40056647 [libc.so.6]
free:
_start
PC=0x08048421 [free_not_algned]
free:
66
address passed to heap manager: 0x08049860
Chapter 2: CLI Commands
dhold
dhold
Holds threads or processes
Format:
Holds processes
dhold –process
Holds threads
dhold –thread
Arguments:
–process
Indicates that processes in the current focus will be
held. You can abbreviate –process to –p.
Indicates that threads in the current focus will be held.
You can abbreviate –thread to –t.
–thread
Description:
The dhold command holds the threads and processes in the current focus.
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
hp
{dhold –process}
Holds the focus process
HP
{f g dhold –process}
Holds all processes in the focus group
ht
{f t dhold –thread}
Holds the focus thread
HT
{f g dhold –thread}
Holds all threads in the focus group
htp
{f p dhold –thread}
Holds all threads in the focus process
f W HT
f s HP
Holds all worker threads in the focus group.
Holds all processes in the share group.
f $mygroup/ HP
Holds all processes in the group identified by the contents of mygroup.
TotalView Reference Guide: version 6.3.1
67
2. CLI Commands
You cannot hold system manager threads. In all cases, holding threads that aren’t part
of your program always has some risk attached to it.
dkill
dkill
Terminates execution of processes
Format:
Description:
dkill
The dkill command terminates all processes in the current focus.
This command has no arguments.
Because the executables associated with the defined processes are still
“loaded,” typing the drun command restarts the processes.
The dkill command alters program state by terminating all processes in the
affected set. In addition, TotalView destroys any spawned processes when
the process that created them is killed. The drun command can only restart
the initial process.
Command alias:
Examples:
You may find the following aliases useful:
Alias
Definition
Meaning
k
{dkill}
Terminates a process’s execution
dkill
Terminates all threads belonging to processes in the
current focus.
dfocus {p1 p3} dkill
Terminates all threads belonging to processes 1 and 3.
68
Chapter 2: CLI Commands
dlappend
dlappend
Appends list elements to a TotalView variable
Format:
dlappend variable-name value [ ... ]
Arguments:
variable-name
value
Description:
The dlappend command appends list elements to a TotalView variable. The
dlappend command performs the same functions as the Tcl lappend command, differing in that dlappend will not create a new debugger variable.
That is, the following Tcl command creates a variable named foo:
The variable to which values are being appended.
The values being appended.
lappend foo 1 3 5
dlappend foo 1 3 5
Examples:
dlappend TV::process_load_callbacks my_load_callback
Adds the my_load_callback function to the list of functions in the process_load_callbacks variable.
TotalView Reference Guide: version 6.3.1
69
2. CLI Commands
In contrast, the following command displays an error message:
dlist
dlist
Displays source code lines
Format:
Displays code relative to the current list location
dlist [ –n num-lines ]
Displays code relative to a named place
dlist source-loc [ –n num-lines ]
Displays code relative to the current execution location
dlist –e [ –n num-lines ]
Arguments:
–n num-lines
source-loc
–e
Description:
Requests that this number of lines be displayed rather
than the default value. (The default is the value of the
MAX_LIST variable.) If num-lines is negative, lines before
the current location are shown, and additional dlist
commands will show preceding lines in the file rather
than succeeding lines.
This option also sets the value of the MAX_LIST variable to num-lines.
Sets the location at which the CLI begins displaying
information. This location is specified as a line number
or as a string containing a file name, function name,
and line number, each separated by # characters. For
example: file#func#line. For more information, see
“Qualifying Symbol Names” in Chapter 11 of the TotalView
Users Guide. Defaults are constructed if you omit parts
of this specification.
Sets the display location to include the current execution point of the thread of interest. If you used dup and
ddown commands to select a buried stack frame, this
location includes the PC (program counter) for that
stack frame.
The dlist command displays lines relative to a place in the source code.
(This position is called the list location.) The CLI prints this information; it is
not returned. If neither source-loc nor –e is specified, the command continues where the previous list command left off. To display the thread’s execution point, use dlist –e.
If you enter a file or procedure name, the listing begins at the file or procedure’s first line.
The default focus for this command is thread level. If your focus is at process level, TotalView acts on each thread in the process.
The first time you use the dlist command after you focus on a different
thread—or after the focus thread runs and stops again—the location
changes to include the current execution point of the new focus thread.
Tabs in the source file are expanded as blanks in the output. The tab stop
width is controlled by the TAB_WIDTH variable, which has a default value of
8. If TAB_WIDTH is set to –1, no tab processing is done, and tabs are displayed using their ASCII value.
70
Chapter 2: CLI Commands
dlist
All lines are shown with a line number and the source text for the line. The
following symbols are also used:
@
An action point is set at this line.
The PC fro the current stack frame is at the indicated line and this
>
is the leaf frame.
The PC for the current stack frame is at the indicated line and this
=
is a buried frame; this frame has called another function so that
this frame is not the active frame.
These correspond to the marks shown in the backtrace displayed by
dwhere that indicates the selected frame.
Here are some general rules:
■
The initial display location is main().
The display location is set to the current execution location when the focus is on a different thread.
If the source-loc argument is not fully qualified, the CLI looks for it in the
directories named in the CLI EXECUTABLE_PATH variable.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
l
{dlist}
Displays lines
These examples assume that MAX_LIST is at its initial value of 20.
dlist
dlist 10
dlist –n 10
dlist –n –50
dlist do_it
Displays 20 lines of source code, beginning at the current list location. The list location is incremented by 20
when the command completes.
Displays 20 lines, starting with line 10 of the file corresponding to the current list location. Because an
explicit value was used, the CLI ignores the previous
command. The list location is changed to line 30.
Displays 10 lines, starting with the current list location.
The value of the list location is incremented by 10.
Displays source code preceding the current list location; 50 lines are shown, ending with the current source
code location. The list location is decremented by 50.
Displays 20 lines in procedure do_it. The list location is
changed so that it is the 20th line of the procedure.
dfocus 2.< dlist do_it
dlist –e
f 1.2 l –e
TotalView Reference Guide: version 6.3.1
Displays 20 lines in the routine do_it associated with
process 2. If the current source file were named foo,
this could also be specified as dlist foo#do_it, naming
the executable for process 2.
Displays 20 lines starting 10 lines above the current
execution location.
Lists the lines around the current execution location of
thread 2 in process 1.
71
2. CLI Commands
■
dlist
dfocus 1.2 dlist –e –n 10
Produces essentially the same listing as the previous
example, differing in that 10 lines are displayed.
dlist do_it.f#80 –n 10
Displays 10 lines, starting with line 80 in file do_it.f. The
list location is updated to line 90.
72
Chapter 2: CLI Commands
dload
dload
Loads debugging information
Format:
Arguments:
dload [ –g gid ] [ –r hname ] [ –e ] executable
–g gid
–r hname
–e
executable
Description:
Command alias:
Examples:
The dload command creates a new TotalView process object for executable.
The dload command returns the TotalView ID for the new object.
You may find the following alias useful:
Alias
Definition
Meaning
lo
{dload}
Loads debugging information
dload do_this
Loads the debugging information for executable
do_this into the CLI. After this command completes,
the process does not yet exist and no address space or
memory is allocated to it.
lo –g 3 –r other_computer do_this
Loads the debugging information for executable
do_this executing on the other_computer machine into
the CLI. This process is placed into group 3.
f g3 lo –r other_computer do_this
Does not do what you would expect it to do because
the dload command ignores the focus command.
dload –g $CGROUP(2) –r slowhost foo
Loads another process based on image foo on
machine slowhost. TotalView places this process in the
same group as process 2.
TotalView Reference Guide: version 6.3.1
73
2. CLI Commands
Sets the control group for the process being added to
the group ID specified by gid. This group must already
exist. (The CLI GROUPS variable contains a list of all
groups.)
The host on which the process will run. The CLI will
launch a TotalView Debugger Server on the host
machine if one is not already running there. See Chapter 5, “Setting Up Parallel Debugging Sessions” of the
TotalView Users Guide for information on the server
launch commands.
Tells the CLI that the next argument is a file name. You
need to use this argument if the file name begins with a
dash or only uses numeric characters.
A fully or partially qualified file name for the file corresponding to the program.
dmstat
dmstat
Displays memory use information
Format:
Description:
dmstat
The dmstat command displays information about how your program is
using memory. After you enter this command, the CLI returns memory
information. This information is displayed in three parts, as follows:
■
memory usage summary: Indicates the minimum and maximum
■
amounts of memory used by the text and data segments, the heap and
the stack, as well as the virtual memory stack usage and the virtual memory size.
Individual process statistics: Shows the amount of memory that each
process is currently using.
image information: Lists the name of the image, the image’s text size,
the image’s data size, and the set of processes using the image.
■
The following table contains definitions of the columns that are displayed.
Table 1: dmstat columns
Column
text
data
heap
stack
74
Meaning
The amount of memory used to store your program’s
machine code instructions. The “text segment” is
sometimes called the “code segment.”
The amount of memory used to store initialized and
uninitialized data.
The amount of memory currently being used for data
created at runtime. For example, calls to malloc() allocate
space on the heap while free() releases it.
The amount of memory used by the currently executing
routine and all of the routines in its backtrace.
If this is a multi-threaded process, TotalView only shows
information for the main thread’s stack. Note that the
stacks of other threads may not change over time on
some architectures.
On some systems, the space allocated for a thread is
considered as being part of the heap.
For example, if your main routine invokes function foo(),
the stack contains two groups of information—these
groups are called “frames.” The first frame contains the
information required for the execution of your main
routine and the second, which is the current frame,
contains the information needed by foo(). If foo() invokes
bar(), the stack contains three frames. When foo() finishes
executing, the stack only contains one frame.
Chapter 2: CLI Commands
dmstat
Column
stack_vm
vm_size
dmstat is sensitive to the focus, as this example from a
four-process program shows:
dmstat
process: text
data
1
(9271): 1128.54K
heap
16.15M
stack
9976
[stack_vm]
vm_size
10432 [16384] 17.44M
image information:
image_name
....ry/forked_mem_exampleLINUX
/lib/i686/libpthread.so.0
/lib/i686/libc.so.6
/lib/ld-linux.so.2
dfocus a dmstat
1
5
6
7
process:
(9979):
(9982):
(9983):
(9984):
text
2524
32172
1050688
70240
data
16778479
27948
122338
10813
dpids
1
1
1
1
The CLI prints the following on a four-process program:
text
1128.54K
1128.54K
1128.54K
1128.54K
data heap stack [stack_vm] vm_size
16.15M 14072 273168 [ 278528] 17.69M
16.15M 9976 10944 [
16384] 17.44M
16.15M 9976 10944 [
16384] 17.44M
16.15M 9976 10944 [
16384] 17.44M
maximum:
1
(9979): 1128.54K 16.15M 14072 273168 [
minimum
5
(9982): 1128.54K 16.15M 9976 10944 [
278528]
17.69M
16384]
17.44M
image information:
image_name
....ry/forked_mem_exampleLINUX
/lib/i686/libpthread.so.0
/lib/i686/libc.so.6
/lib/ld-linux.so.2
TotalView Reference Guide: version 6.3.1
text
2524
32172
1050688
70240
data
16778479
27948
122338
10813
dpids
1 5 6
1 5 6
1 5 6
1 5 6
7
7
7
7
75
2. CLI Commands
Examples:
Meaning
The logical size of the stack is the difference between the
current value of the stack pointer and address from which
the stack originally grew. This value can differ from the size of
the virtual memory mapping in which the stack resides. For
example, the mapping can be larger than the logical size of
the stack if the process previously had a deeper nesting of
procedure calls or made memory allocations on the stack, or
it can be smaller if the stack pointer has advanced but the
intermediate memory has not been touched.
The value here is this size difference.
The sum of the sizes of the mappings in the process's
address space.
dnext
dnext
Steps source lines, stepping over subroutines
Format:
dnext [ num-steps ]
Arguments:
num-steps
Description:
The dnext command executes source lines; that is, it advances the program
by steps (source line statements). However, if a statement in a source line
invokes a routine, dnext executes the routine as if it were one statement;
that is, it steps over the call.
An integer greater than 0, indicating the number of
source lines to be executed.
The optional num-steps argument tells the CLI how many dnext operations it
should perform. If you do not specify num-steps, the default is 1.
The dnext command iterates over the arenas in its focus set, performing a
thread-level, process-level, or group-level step in each arena, depending
on the width of the arena. The default width is process (p).
For more information on stepping in processes and threads, see dstep on
page 99.
Command alias:
76
You may find the following aliases useful:
Alias
Definition
Meaning
n
{dnext}
Runs the thread of interest one statement
while allowing other threads in the process to
run.
N
{dfocus g dnext}
A group stepping command. This searches for
threads in the share group that are at the
same PC as the thread of interest, and steps
one such “aligned” thread in each member
one statement. The rest of the control group
runs freely.
nl
{dfocus L dnext}
Steps the process threads in “lockstep.” This
steps the thread of interest one statement
and runs all threads in the process that are at
the same PC as the thread of interest to the
same statement. Other threads in the process
run freely. The group of threads that are at the
same PC is called the lockstep group.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
NL
{dfocus gL dnext}
Steps “lockstep” threads in the group. This
steps all threads in the share group that are at
the same PC as the thread of interest one
statement. Other threads in the control group
run freely.
Chapter 2: CLI Commands
dnext
Definition
Meaning
nw
{dfocus W dnext}
Steps worker threads in the process. This
steps the thread of interest one statement,
and runs all worker threads in the process to
the same (goal) statement. The nonworker
threads in the process run freely.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
NW
{dfocus gW dnext}
Steps worker threads in the group. This steps
the thread of interest one statement, and
runs all worker threads in the same share
group to the same statement. All other
threads in the control group run freely.
dnext
n 10
N
f t n
Steps one source line.
Steps ten source lines.
Steps one source line. It also runs all other processes
in the group that are in the same lockstep group to the
same line.
Steps the thread one statement.
dfocus 3. dnext
Steps process 3 one step.
TotalView Reference Guide: version 6.3.1
77
2. CLI Commands
Examples:
Alias
dnexti
dnexti
Steps machine instructions, stepping over subroutines
Format:
dnexti [ num-steps ]
Arguments:
num-steps
Description:
The dnexti command executes machine-level instructions; that is, it
advances the program by a single instruction. However, if the instruction
invokes a subfunction, dnexti executes the subfunction as if it were one
instruction; that is, it steps over the call. This command steps the thread of
interest while allowing other threads in the process to run.
An integer greater than 0, indicating the number of
instructions to be executed.
The optional num-steps argument tells the CLI how many dnexti operations
it should perform. If you do not specify num-steps, the default is 1.
The dnexti command iterates over the arenas in the focus set, performing a
thread-level, process-level, or group-level step in each arena, depending
on the width of the arena. The default width is process (p).
For more information on stepping in processes and threads, see dstep on
page 99.
Command alias:
78
You may find the following aliases useful:
Alias
Definition
Meaning
ni
{dnexti}
Runs the thread of interest one instruction
while allowing other threads in the process to
run.
NI
{dfocus g dnexti}
A group stepping command. This searches
for threads in the share group that are at the
same PC as the thread of interest, and steps
one such “aligned” thread in each member
one instruction. The rest of the control group
runs freely.
nil
{dfocus L dnexti}
Steps the process threads in “lockstep.” This
steps the thread of interest one instruction,
and runs all threads in the process that are at
the same PC as the thread of interest to the
same statement. Other threads in the
process run freely. The group of threads that
are at the same PC is called the lockstep group.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
NIL
{dfocus gL dnexti}
Steps “lockstep” threads in the group. This
steps all threads in the share group that are
at the same PC as the thread of interest one
instruction. Other threads in the control
group run freely.
Chapter 2: CLI Commands
dnexti
Definition
Meaning
niw
{dfocus W dnexti}
Steps worker threads in the process. This
steps the thread of interest one instruction,
and runs all worker threads in the process to
the same (goal) statement. The nonworker
threads in the process run freely.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
NIW
{dfocus gW dnexti}
Steps worker threads in the group. This steps
the thread of interest one instruction, and
runs all worker threads in the same share
group to the same statement. All other
threads in the control group run freely.
dnexti
ni 10
NI
f t n
Steps one machine-level instruction.
Steps ten machine-level instructions.
Steps one instruction and runs all other processes in
the group that were executing at that instruction to the
next instruction as well.
Steps the thread one machine-level instruction.
dfocus 3. dnexti
Steps process 3 one machine-level instruction.
TotalView Reference Guide: version 6.3.1
79
2. CLI Commands
Examples:
Alias
dout
dout
Runs out from the current subroutine
Format:
dout [ frame-count ]
Arguments:
frame-count
Description:
The dout command runs a thread until it returns:
■
■
An integer that specifies that the thread return out of
this many levels of subroutine calls. If you omit this
number, the thread returns from the current level.
From the current subroutine.
From one or more nested subroutines.
When process width is specified, TotalView allows all threads in the process
that are not running to this goal to run free. Note that specifying process
width is the default.
Command alias:
80
You may find the following aliases useful:
Alias
Definition
Meaning
ou
{dout}
Runs the thread of interest out of the current
function while allowing other threads in the
process to run.
OU
{dfocus g dout}
A group stepping command. This searches for
threads in the share group that are at the same
PC as the thread of interest, and runs one such
“aligned” thread in each member out of the
current function. The rest of the control group
runs freely.
oul
{dfocus L dout}
Runs the process threads in “lockstep.” This
runs the thread of interest out of the current
function, and also runs all threads in the
process that are at the same PC as the thread of
interest out of the current function. Other
threads in the process run freely. The group of
threads that are at the same PC is called the
lockstep group.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
OUL
{dfocus gL dout}
Runs “lockstep” threads in the group. This runs
all threads in the share group that are at the
same PC as the thread of interest out of the
current function. Other threads in the control
group run freely.
Chapter 2: CLI Commands
dout
Definition
Meaning
ouw
{dfocus W dout}
Runs worker threads in the process. This runs
the thread of interest out of the current
function and runs all worker threads in the
process to the same (goal) statement. The
nonworker threads in the process run freely.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
OUW
{dfocus gW dout}
Runs worker threads in the group. This runs the
thread of interest out of the current function
and also runs all worker threads in the same
share group out of the current function. All
other threads in the control group run freely.
For additional information on the different kinds of stepping, see the dstep
on page 99 command information.
Examples:
f t ou
f p dout 3
TotalView Reference Guide: version 6.3.1
Runs the current thread of interest out of the current
subroutine.
Unwinds the process in the current focus out of the
current subroutine to the routine three levels above it
in the call stack.
81
2. CLI Commands
Alias
dprint
dprint
Evaluates and displays information
Format:
Prints the value of a variable
dprint [ –nowait ] variable
Prints the value of an expression
dprint [ –nowait ] expression
Arguments:
-nowait
variable
expression
Description:
Tells TotalView to evaluate the expression in the background. You will need to use TV::expr to obtain the
results as they are not displayed.
A variable whose value will be displayed. The variable
can be local to the current stack frame or it can be global. If the variable being displayed is an array, you can
qualify the variable’s name with a slice that tells the CLI
to display a portion of the array,
A source-language expression to be evaluated and
printed. Because expression must also conform to Tcl
syntax, you must quote it if it includes any blanks, and
it must be enclosed in braces ({}) if it includes brackets
([ ]), dollar signs ($), quote characters ("), or any other
Tcl special characters.
The dprint command evaluates and displays a variable or an expression.
The CLI interprets the expression by looking up the values associated with
each symbol and applying the operators. The result of an expression can
be a scalar value or an aggregate (array, array slice, or structure).
If an event such as a $stop, SEGV, breakpoint, or the like occurs, the dprint
command throws an exception describing the event. The first exception
subcode returned by TV::errorCodes is the susp-eval-id (a suspension-evaluation-ID). You can use this to manipulate suspended evaluations with the
dflush and TV::expr commands.
If you use –nowait, TotalView evaluates the expression in the background.
It also returns a susp-eval-id that you can use to obtain the results of the
evaluation.
As the CLI displays data, it passes the data through a simple more processor
that prompts you after it displays each screen of text. At this time, you can
press the Enter key to tell the CLI to continue displaying information.
Entering q tells the CLI to stop printing this information.
Since the dprint command can generate a considerable amount of output,
you may want to use the capture command described on page 18 to save
the output into a variable.
Structure output appears with one field printed per line. For example:
sbfo = {
f3 = 0x03 (3)
f4 = 0x04 (4)
f5 = 0x05 (5)
82
Chapter 2: CLI Commands
dprint
f20 = 0x000014 (20)
f32 = 0x00000020 (32)
}
Arrays are printed in a similar manner. For example:
foo = {
[0][0]
[0][1]
[1][0]
[1][1]
[2][0]
[2][1]
[3][0]
[3][1]
}
=
=
=
=
=
=
=
=
0x00000000
0x00000004
0x00000001
0x00000005
0x00000002
0x00000006
0x00000003
0x00000007
(0)
(4)
(1)
(5)
(2)
(6)
(3)
(7)
d.1<> p {master_array[::10]}
master_array(::10) = {
(1) = 1 (0x00000001)
(11) = 1331 (0x00000533)
(21) = 9261 (0x0000242d)
(31) = 29791 (0x0000745f)
(41) = 68921 (0x00010d39)
(51) = 132651 (0x0002062b)
(61) = 226981 (0x000376a5)
(71) = 357911 (0x00057617)
(81) = 531441 (0x00081bf1)
(91) = 753571 (0x000b7fa3)
}
Note that the slice was placed within {} symbols. This prevents Tcl from
trying to evaluate the information in the [] characters. You could, of course,
instead escape the brackets; for example, \[ \].
The CLI evaluates the expression or variable in the context of each thread
in the target focus. Thus, the overall format of dprint output is as follows:
first process or thread:
expression result
second process or thread:
expression result
...
last process or thread:
expression result
You can also use the dprint command to obtain values for your computer’s
registers. For example, on most architectures, $r1 is register 1. You would
obtain the contents of this register by typing:
dprint \$r1
Notice that you must quote the $ since the name of the register’s name
includes the $. This $ is not the standard indicator that tells Tcl to fetch a
variable’s value. Chapter 10, “Architectures,” on page 225 lists the mnemonic
names assigned to registers.
TotalView Reference Guide: version 6.3.1
83
2. CLI Commands
You can append a slice to the variable’s name to tell the CLI that it should
display a portion of an array. For example:
dprint
Do not use a $ when asking dprint to display your program’s variables.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
p
{dprint}
Evaluates and displays information
dprint scalar_y
p argc
p argv
Displays the values of variable scalar_y in all processes
and threads in the current focus.
Displays the value of argc.
Displays the value of argv, along with the first string to
which it points.
p {argv[argc-1]}
Prints the value of argv[argc-1]. If the execution point is
in main(), this is the last argument passed to main().
dfocus p1 dprint scalar_y
f 1.2 p arrayx
Displays the values of variable scalar_y for the threads
in process 1.
Displays the values of the array arrayx for just the second thread in process 1.
for {set i 0} {$i < 100} {incr i} {p argv\[$i\]}
If main() is in the current scope, prints the program’s
arguments followed by the program’s environment
strings.
f {t1.1 t2.1 t3.1} dprint {f()}
The dprint command evaluates a function contained
within three threads. Note that each thread is in a different process:
Thread 1.1:
f(): 2
Thread 2.1:
f(): 3
Thread 3.1:
f(): 5
f {t1.1 t2.1 t3.1} dprint -nowait {f()}
1
This example evaluates a function without waiting. At a
later time, the results are obtained using TV::expr. The
number displayed immediately after the command,
which is “1”, is the susp-eval-id. Here is how this is done:
f t1.1
2
f t2.1
Thread
f(): 2
Thread
f(): 3
84
TV::expr get 1 result
TV::expr get 1 result
1.1:
2.1:
Chapter 2: CLI Commands
dprint
Thread 3.1:
f(): 5
3
f t3.1 TV::expr get 1 result
5
2. CLI Commands
TotalView Reference Guide: version 6.3.1
85
dptsets
dptsets
Shows status of processes and threads
Format:
dptsets [ ptset_array ] ...
Arguments:
ptset_array
Description:
The dptsets command shows the status of each process and thread in a Tcl
array of P/T expressions. These array elements are P/T expressions (see
Chapter 11 of the TotalView Users Guide) and the elements' array indices are
strings that label each element's section in the output. Using this array syntax is explored in the Examples section.
An optional array that indicates the P/T sets that will be
shown. An element of the array can be a number or it
can be a more complicated P/T expression. For more
information, see “Using P/T Set Operators” in Chapter 11
of the TotalView Users Guide.
If you do not use the optional ptset_array argument, the CLI supplies a
default array containing all P/T set designators. These designators are error,
existent, held, running, stopped, unheld, and watchpoint.
Examples:
The following command displays information about processes and threads
in the current focus:
d.1<> dptsets
unheld:
1:
808694
1.1: 808694.1
1.2: 808694.2
1.3: 808694.3
1.4: 808694.4
Stopped
Stopped
Stopped
Stopped
Stopped
[fork_loopSGI]
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
existent:
1:
808694
1.1: 808694.1
1.2: 808694.2
1.3: 808694.3
1.4: 808694.4
Stopped
Stopped
Stopped
Stopped
Stopped
[fork_loopSGI]
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
Stopped
Stopped
Stopped
Stopped
Stopped
[fork_loopSGI]
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
watchpoint:
running:
held:
error:
stopped:
1:
808694
1.1: 808694.1
1.2: 808694.2
1.3: 808694.3
1.4: 808694.4
...
86
Chapter 2: CLI Commands
dptsets
The following example creates a two-element P/T set array, and then displays the results. Notice the labels in this example.
d1.<> set set_info(0) breakpoint(1)
breakpoint(1)
d1.<> set set_info(1) stopped(1)
stopped(1)
d1.<> dptsets set_info
0:
1:
892484
Breakpoint [arraysSGI]
1.1: 892484.1 Breakpoint PC=0x10001544, [arrays.F#81]
1:
1:
892484
Breakpoint
1.1: 892484.1 Breakpoint
[arraysSGI]
PC=0x10001544, [arrays.F#81]
Using numbers as array indices almost ensures that you will not remember
what is being printed. The following almost identical example shows a better way to use these array indices.
d1.<> set set_info(my_breakpoints) breakpoint(1)
breakpoint(1)
d1.<> set set_info(my_stopped) stopped(1)
stopped(1)
d1.<> dptsets set_info
my_stopped:
1:
882547
Breakpoint [arraysSGI]
1.1: 882547.1 Breakpoint PC=0x10001544, [arrays.F#81]
my_breakpoints:
1:
882547
Breakpoint
1.1: 882547.1 Breakpoint
[arraysSGI]
PC=0x10001544, [arrays.F#81]
The following commands also create a two-element array. It differs in that
the second element is the difference between three P/T sets.
d.1<> set mystat(system) a–gW
d.1<> set mystat(reallystopped) \
stopped(a)–breakpoint(a)–watchpoint(a)
d.1<> dptsets t mystat
system:
Threads in process 1 [regress/fork_loop]:
1.-1: 21587.[-1] Running PC=0x3ff805c6998
1.-2: 21587.[-2] Running PC=0x3ff805c669c
...
Threads in process 2 [regress/fork_loop.1]:
2.-1: 15224.[-1] Stopped PC=0x3ff805c6998
2.-2: 15224.[-2] Stopped PC=0x3ff805c669c
...
reallystopped:
2.2
224.2 Stopped PC=0x3ff800d5758
2.-1
5224.[-1] Stopped PC=0x3ff805c6998
2.-2: 15224.[-2] Stopped PC=0x3ff805c669c
...
TotalView Reference Guide: version 6.3.1
87
2. CLI Commands
The array index to set_info becomes a label identifying the kind of information being displayed. In contrast, the information within parentheses in the
breakpoint and stopped functions identify the arena for which the function
will return information.
drerun
drerun
Restarts processes
Format:
Arguments:
drerun [ cmd_args ] [ in_operation infile ]
[ out_operations outfile ]
[ error_operations errfile ]
cmd_args
operations
infile
outfile
errfile
Description:
The arguments to be used for restarting a process.
The in_operation, out_operations, and error_operations arguments are discussed in the Description section.
If specified, indicates a file from which the launched
processes will read information.
If specified, indicates the file into which the launched
processes will write information.
If specified, indicates the file into which the launched
processes will write error information.
The drerun command restarts the process that is in the current focus set
from its beginning. The drerun command uses the arguments stored in the
ARGS and ARGS_DEFAULT variables. These are set every time the process is
run with different arguments. Consequently, if you do not specify the arguments to be used when restarting the process, the CLI uses the arguments
specified when the process was previously run. (See drun on page 92 for
more information.)
The dererun command differs from the drun command in that
If you do not specify an argument, drerun uses the default values. In
contrast, the drun command clears the argument list for the program.
This means that you cannot use an empty argument list with the drerun
command to tell the CLI to restart a process and expect that no arguments will be used.
■ If the process already exists, drun will not restart it. (If you must use the
drun command, you must first kill the process.) In contrast, the drerun
command will kill and then restart the process.
The arguments to this command are similar to the arguments used in the
Bourne shell.
■
The in_operation is follows:
< infile
Reads from infile instead of stdin.
The out_operations are as follows:
> outfile
>& outfile
>>& outfile
>> outfile
Sends output to outfile instead of stdout.
Sends output and error messages to outfile instead of
stdout and stderr.
Appends output and error messages to outfile.
Appends output to outfile.
The error_operations are:
2> errfile
2>>errfile
88
Sends error messages to errfile instead of stderr.
Appends error messages to errfile.
Chapter 2: CLI Commands
drerun
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
rr
{drerun}
Restarts processes
drerun
Reruns the current process. Because arguments are not
used, the process is restarted using its previous values.
rr –firstArg an_argument –aSecondArg a_second_argument
Reruns the current process. The default arguments are
not used because replacement arguments are specified.
2. CLI Commands
TotalView Reference Guide: version 6.3.1
89
drestart
drestart
Restarts a checkpoint (IBM and SGI only)
Format:
Restarts a checkpoint on SGI
drestart [ process-state ] [ –no_unpark ] [ –g gid ] [ –r host ]
[ –ask_attach_parallel | –no_attach_parallel ]
[ –no_preserve_ids ] checkpoint-name
Restarts a checkpoint on AIX
drestart [ –halt ] [ –g gid ] [ –r host ] [ –no_same_hosts ] checkpoint-name
Arguments:
process_state
–detach
–go
–halt
–no_unpark
–g gid
–r host
Defines the state of the process both before and after
the checkpoint. If you do not specify a process state,
parallel processes are held immediately after the place
where the checkpoint occurred. The CLI attaches to
these created parallel processes. You can use one of
the following options:
(SGI only) While TotalView starts checkpointed process,
it does not attach to them.
(SGI only) TotalView starts checkpointed parallel processes and attaches to them.
TotalView stops checkpointed processes after it
restarts them.
(SGI only) Indicates that the checkpoint was created
outside of TotalView or that you used the dcheckpoint
command’s –no_park option when you created the
checkpoint file.
Names the control group into which TotalView places
all created processes.
Names the remote host upon which the restart will
occur.
–ask_attach_parallel
(SGI only) Asks if the CLI should automatically attach to
the parallel processes being created. This is most often
used in procedures.
–no_attach_parallel
(SGI only) Tells TotalView to attach only to the base process. That is, the CLI will not attach to the parallel processes being created.
–no_preserve_ids
–no_same_hosts
checkpoint-name
90
(SGI only) Tells TotalView that it should use new IDs
after it restarts the processes. If you omit this option,
TotalView causes the process to use the same process,
group, session, or ash IDs after restarting.
(IBM only) Restart can use any available hosts. If you do
not use this option, the restart occurs on the same hosts
upon which the program was executing when the checkpoint was made. If these hosts are not available, the
restart operation fails.
The name used when the checkpoint file was saved.
Chapter 2: CLI Commands
drestart
Description:
The drestart command restores and restarts all of the checkpointed processes. By default, the CLI will attach to the base process. Here are some
of your choices.
■
■
■
If there are parallel processes related to this base process, TotalView will
attach to them.
If you do not want the CLI to automatically attach to these parallel processes, use the –no_attach_parallel option.
If you do not know if there are parallel processes, if you want the user to
decide, or if you are using this command within a Tcl procedure, you
should use the –ask_parallel_process option.
Restarting on AIX using LoadLeveler
When attaching to poe, parallel tasks will not yet be created, so do not try to attach to
any of them. Also, you’ll need to use the –no_attach_parallel option when using
dattach.
When doing this, you cannot use the restart the checkpoint using this command. poe will tell TotalView when it is time to attach to the parallel task so
that it can complete the restart.
Examples:
drestart check1
Restarts the processes checkpointed in the check1 file.
The CLI automatically attaches to parallel processes.
This is an SGI checkpoint because a name is being
specified.
drestart –no_unpark check1
Restarts the processes checkpointed in the check1 file.
This file was either created outside of TotalView or it
was created using the –no_park option. This is an SGI
checkpoint because a name is being specified.
TotalView Reference Guide: version 6.3.1
91
2. CLI Commands
On the RS/6000, if you wish to debug a LoadLeveler poe job from the point
at which the checkpoint was made, you must resubmit the program as a
LoadLeveler job to restart the checkpoint. You will also need to set the
MP_POE_RESTART_SLEEP environment variable to an appropriate number of
seconds. After you restart poe, start TotalView and attach to poe.
drun
drun
Starts or restarts processes
Format:
Arguments:
drun [ cmd_arguments ]
cmd_arguments
operations
infile
outfile
errfile
Description:
[ in_operation infile ]
[ out_operations outfile ]
[ error_operations errfile ]
The argument list passed to the process.
The in_operation, out_operations, and error_operations arguments are discussed in the Description section.
If specified, indicates a file from which the launched
processes will read information.
If specified, indicates the file into which the launched
processes will write information.
If specified, indicates the file into which the launched
processes will write error information.
The drun command launches each process in the current focus and starts
it running. The command arguments are passed to the processes, and I/O
redirection for the program, if specified, will occur. Later in the session, you
can use the drerun command to restart the program.
The arguments to this command are similar to the arguments used in the
Bourne shell.
The in_operation is as follows:
< infile
Reads from infile instead of stdin.
The out_operations are as follows:
> outfile
>& outfile
>>& outfile
>> outfile
Sends output to outfile instead of stdout.
Sends output and error messages to outfile instead of
stdout and stderr.
Appends output and error messages to outfile.
Appends output to outfile.
The error_operations are:
2> errfile
2>> errfile
Sends error messages to errfile instead of stderr.
Appends error messages to errfile.
In addition, the CLI uses the following variables to hold the default argument list for each process.
ARGS_DEFAULT
ARGS(n)
92
The CLI sets this variable if you use the –a commandline option when you started the CLI or TotalView. (This
option passes command-line arguments that TotalView
will use when it invokes a process.) This variable holds
the default arguments that TotalView passes to a process when the process has no default arguments of its
own.
An array variable containing the command-line arguments. The index n is the process ID n. This variable
holds a process’s default arguments. It is always set by
Chapter 2: CLI Commands
drun
the drun command, and it also contains any arguments
you used when executing a drerun command.
If more than one process is launched with a single drun command, each
receives the same command-line arguments.
In addition to setting these variables by using the –a command-line option or
specifying cmd_arguments when you use this or the drerun command, you
can modify these variables directly with the dset and dunset commands.
You can only use this command to tell TotalView that it should execute initial processes because TotalView cannot directly run processes that your
program spawns. When you enter this command, the initial process must
be have terminated; if it was not terminated, you are told to kill it and retry.
(You can, of course, use the drerun command.)
Issues With Using
IBM’s poe
Both poe and the CLI can interfere with one another because each believes
that it owns stdin. Because poe is trying to manage stdin on behalf of your
processes, it continually reads from stdin, acquiring all characters that it
sees. This means that the CLI will never see these characters. If your target
process does not use stdin, you can use the –stdinmode none option.
Unfortunately, this option is incompatible with poe’s –cmdfile option that is
used when specifying –pgmmodel mpmd.
If you encounter these problems, you should redirect stdin within the CLI.
For example:
drun < in.txt
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
r
{drun}
Starts or restarts processes
drun
Tells the CLI to begin executing processes represented
in the current focus.
f {p2 p3} drun
f 4.2 r
Begins execution of processes 2 and 3.
Begins execution of process 4. Note that this is the
same as f 4 drun.
dfocus a drun
Restarts execution of all processes known to the CLI. If
they were not previously killed, you are told to use the
dkill command and then try again.
TotalView Reference Guide: version 6.3.1
93
2. CLI Commands
The first time you use the drun command, TotalView copies arguments to
program variables. It also sets up any requested I/O redirection. If you
reenter this command for processes that TotalVIew previously started—or
issued for the first time for a process that was attached to using the
dattach command—the CLI reinitializes your program.
drun
drun < in.txt
Restarts execution of all processes in the current focus,
setting them up to get standard input from file in.txt.
94
Chapter 2: CLI Commands
dset
dset
Changes or views CLI variables
Format:
Changes a CLI variable
dset debugger-var value
Views current CLI variables
dset [ debugger-var ]
Sets the default for a CLI variable
dset -set_as_default debugger-var value
Arguments:
debugger-var
value
Description:
The dset command sets the value of CLI debugger variables. You’ll find a
listing and description of CLI and TotalView variables in Chapter 4,
“TotalView Variables,” on page 155.
If you type dset with no arguments, the CLI displays the names and current
values for all TotalView CLI variables in the global namespace. If you use
only one argument, the CLI returns and displays the variable’s value.
The second argument defines the value that will replace a variable’s previous value. It must be enclosed in quotes if it contains more than one word.
If you do not use an argument, the CLI only displays variables in the current
namespace. To show all variables in a namespace, just enter the
namespace name immediately followed by a double colon; for example,
TV::.
You can use an asterisk (*) as a wildcard to indicate that the CLI should
match more than one string; for example, TV::g* matches all variables
beginning with g in the TV namespace. For example, to view all variables in
the TV:: namespace, you would enter:
dset TV::
or:
dset TV::GUI::
The rightmost double colons are required when obtaining listings for a
namespace. If you omit them, Tcl assumes that you are requesting information on a variable. For example, dset TV::GUI looks for a variable named GUI
in the TV namespace.
Examples:
dset PROMPT "Fixme% "
Sets the prompt to be Fixme% followed by a space.
dset *
dset VERBOSE
TotalView Reference Guide: version 6.3.1
Displays all CLI variables and their current settings.
Displays the current setting for output verbosity.
95
2. CLI Commands
-set_as_default
Name of a CLI variable.
Value to be assigned to debugger-var.
Set the value to be used as the variable’s default. This
option is most often used by system administrators to
set site-specific defaults in the global .tvdrc startup
script. Values set using this option replace the Etnussupplied default.
dset
dset EXECUTABLE_PATH ../test_dir;$EXECUTABLE_PATH
Places ../test_dir at the beginning of the previous value
for the executable path.
dset -set_as_default TV::server_launch_string \
{/use/this/one/tvdsvr}
Sets the default value of the TV::server_launch_string. If
a user changes this value in any way, the user will be
able to select the Defaults button within the File >
Preferences’s Launch String Page to reset it to this
value.
dset TV::GUI::fixed_font_size 12
Sets the TotalView GUI so that it displays fixed fonts
using a 12 font. Commands such as this are often
found in a startup file.
96
Chapter 2: CLI Commands
dstatus
dstatus
Shows current status of processes and threads
Format:
Description:
dstatus
The dstatus command prints information about the current state of each
process and thread in the current focus. The ST command is an alias for
dfocus g dstatus, and acts as a group-status command.
This command has no arguments.
If you have not changed the focus, the default width is process. In this case,
dstatus shows the status for each thread in process 1. In contrast, if you
set the focus to g1.<, the CLI displays the status for every thread in the
control group containing process 1.
Examples:
2. CLI Commands
Command alias:
You may find the following aliases useful:
Alias
Definition
Meaning
st
{dstatus}
Shows current status
ST
{dfocus g dstatus}
Shows group status
dstatus
Displays the status of all processes and threads in the
current focus. For example:
1:
f a st
f p1 st
ST
42898
Breakpoint [arraysAIX]
1.1: 42898.1 Breakpoint \
PC=0x100006a0, [./arrays.F#87]
Displays the status for all threads in all processes.
Displays the status of the threads associated with process 1. If the focus is at its default (d1.<), this is the
same as typing st.
Displays the status of all processes and threads in the
control group containing the focus process. For example:
1:
1.1:
1.2:
1.3:
1.4:
1.5:
2:
2.1:
2.2:
2.3:
2.4:
2.5:
f W st
f W ST
TotalView Reference Guide: version 6.3.1
773686
773686.1
773686.2
773686.3
773686.4
773686.5
779490
779490.1
779490.2
779490.3
779490.4
779490.5
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
Stopped
[fork_loop_64]
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
[fork_loop_64.1]
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
PC=0x0d9cae64
Shows status for all worker threads in the focus set. If
the focus is set to d1.<, the CLI shows the status of
each worker thread in process 1.
Shows status for all worker threads in the control group
associated with the current focus.
97
dstatus
f L ST
98
In this case, TotalView merges the W and g specifiers in
the ST alias. The results is the same as if you had
entered f gW st.
Shows status for every thread in the share group that is
at the same PC as the thread of interest.
Chapter 2: CLI Commands
dstep
dstep
Steps lines, stepping into subfunctions
Format:
dstep [ num-steps ]
Arguments:
num-steps
Description:
The dstep command executes source lines; that is, it advances the program
by steps (source lines). If a statement in a source line invokes a subfunction, dstep steps into the function.
An integer greater than 0, indicating the number of
source lines to be executed.
The optional num-steps argument tells the CLI how many dstep operations it
should perform. If you do not specify num-steps, the default is 1.
If the width is process, the dstep command affects the entire process containing the thread to be stepped. Thus, while only one thread is stepped,
all other threads contained in the same process also resume executing. In
contrast, the dfocus t dstep command tells the CLI that it should just step
the thread of interest.
On systems having identifiable manager threads, the “dfocus t dstep” command allows
the manager threads to run as well as the thread of interest.
The action taken on each term in the focus list depends on whether its
width is thread, process, or group, and on the group specified in the current
focus. (If you do not explicitly specify a group, the default is the control
group.)
If some thread hits an action point other than the goal breakpoint during a
step operation, that ends the step.
Thread Width
Only the thread of interest is allowed to run. (This is not supported on all
systems.)
Process Width (default)
The behavior depends on the group specified in the arena.
Process group
Thread group
TotalView Reference Guide: version 6.3.1
TotalView allows the entire process to run, and execution continues until the thread of interest arrives at its
goal location. TotalView plants a temporary breakpoint
at the goal location while this command executes. If
another thread reaches this goal breakpoint first, your
program continues to execute until the thread of interest reaches the goal.
TotalView runs all threads in the process that are in that
group to the same goal as the thread of interest. If a
thread arrives at the goal that is not in the group of
interest, it also stops there. The group of interest specifies the set of threads for which TotalView will wait.
99
2. CLI Commands
The dstep command iterates over the arenas in the focus set by doing a
thread-level, process-level, or group-level step in each arena, depending
on the width of the arena. The default width is process (p).
dstep
This means that the command does not complete until
all threads in the group of interest are at the goal.
Group Width
The behavior depends on the group specified in the arena.
Process group
Thread group
Command alias:
100
TotalView examines that group and identifies each process having a thread stopped at the same location as
the thread of interest. One matching thread from each
matching process is selected. TotalView then runs all
processes in the group and waits until the thread of
interest arrives at its goal location; each selected
thread also arrives there.
The behavior is similar to process width behavior
except that all processes in the program control group
will run, rather than just the process of interest.
Regardless of what threads are in the group of interest,
TotalView only waits for threads that are in the same
share group as the thread of interest. This is because it
is not useful to run threads executing in different
images to the same goal.
You may find the following aliases useful:
Alias
Definition
Meaning
s
{dstep}
Runs the thread of interest one statement
while allowing other threads in the process to
run.
S
{dfocus g dstep}
A group stepping command. This searches
for threads in the share group that are at the
same PC as the thread of interest, and steps
one such “aligned” thread in each member
one statement. The rest of the control group
runs freely.
sl
{dfocus L dstep}
Steps the process threads in “lockstep.” This
steps the thread of interest one statement,
and runs all threads in the process that are at
the same PC as the thread of interest to the
same (goal) statement. Other threads in the
process run freely. The group of threads that
are at the same PC is called the lockstep group.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
SL
{dfocus gL dstep}
Steps “lockstep” threads in the group. This
steps all threads in the share group that are
at the same PC as the thread of interest one
statement. Other threads in the control
group run freely.
Chapter 2: CLI Commands
dstep
Definition
Meaning
sw
{dfocus W dstep}
Steps worker threads in the process. This
steps the thread of interest one statement,
and runs all worker threads in the process to
the same (goal) statement. The nonworker
threads in the process run freely. This alias
does not force process width. If the default
focus is set to group, this steps the group.
SW
{dfocus gW dstep}
Steps worker threads in the group. This steps
the thread of interest one statement, and
runs all worker threads in the same share
group to the same (goal) statement. All other
threads in the control group run freely.
dstep
s 15
f p1.2 dstep
f t1.2 s
TotalView Reference Guide: version 6.3.1
Executes the next source line, stepping into any procedure call that is encountered. While only the current
thread is stepped, other threads in the process run.
Executes the next 15 source lines.
Steps thread 2 in process 1 by one source line. This
also resumes execution of all threads in process 1; they
are halted as soon as thread 2 in process 1 executes its
statement.
Steps thread 2 in process 1 by one source line. No
other threads in process 1 execute.
101
2. CLI Commands
Examples:
Alias
dstepi
dstepi
Steps machine instructions, stepping into subfunctions
Format:
dstepi [ num-steps ]
Arguments:
num-steps
Description:
The dstepi command executes assembler instruction lines; that is, it
advances the program by single instructions.
An integer greater than 0, indicating the number of
instructions to be executed.
The optional num-steps argument tells the CLI how many dstepi operations
it should perform. If you do not specify num-steps, the default is 1.
For more information, see dstep on page 99.
Command alias:
102
You may find the following aliases useful:
Alias
Definition
Meaning
si
{dstepi}
Runs the thread of interest one instruction
while allowing other threads in the process to
run.
SI
{dfocus g dstepi}
A group stepping command. This searches
for threads in the share group that are at the
same PC as the thread of interest, and steps
one such “aligned” thread in each member
one instruction. The rest of the control group
runs freely.
sil
{dfocus L dstepi}
Steps the process threads in “lockstep.” This
steps the thread of interest one instruction,
and runs all threads in the process that are at
the same PC as the thread of interest to the
same instruction. Other threads in the
process run freely. The group of threads that
are at the same PC is called the lockstep group.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
SIL
{dfocus gL dstepi}
Steps “lockstep” threads in the group. This
steps all threads in the share group that are
at the same PC as the thread of interest one
instruction. Other threads in the control
group run freely.
Chapter 2: CLI Commands
dstepi
Definition
Meaning
siw
{dfocus W dstepi}
Steps worker threads in the process. This
steps the thread of interest one instruction,
and runs all worker threads in the process to
the same (goal) statement. The nonworker
threads in the process run freely.
This alias does not force process width. If the
default focus is set to group, this steps the
group.
SIW
{dfocus gW dstepi}
Steps worker threads in the group. This steps
the thread of interest one instruction, and
runs all worker threads in the same share
group to the same statement. All other
threads in the control group run freely.
dstepi
si 15
f p1.2 dstepi
f t1.2 si
TotalView Reference Guide: version 6.3.1
Executes the next machine instruction, stepping into
any procedure call that is encountered. While only the
current thread is stepped, other threads in the process
are allowed to run.
Executes the next 15 instructions.
Steps thread 2 in process 1 by one instruction and
resumes execution of all other threads in process 1;
they are halted as soon as thread 2 in process 1 executes its instruction.
Steps thread 2 in process 1 by one instruction. No
other threads in process 1 execute.
103
2. CLI Commands
Examples:
Alias
dunhold
dunhold
Releases a held process or thread
Format:
Releases a process
dunhold –process
Releases a thread
dunhold –thread
Arguments:
–process
Indicates that TotalView should release processes in
the current focus. You can abbreviate the –process
argument to –p.
Indicates that TotalView should release threads in the
current focus. You can abbreviate the –thread to –t.
–thread
Description:
Command alias:
Examples:
The dunhold command releases the threads or processes in the current
focus. Note that system manager threads cannot be held or released.
You may find the following aliases useful:
Alias
Definition
Meaning
uhp
{dfocus p dunhold -process}
Releases the process of interest
UHP
{dfocus g dunhold -process}
Releases the processes in the focus
group
uht
{dfocus t dunhold –thread}
Releases the thread of interest
UHT
{dfocus g dunhold –thread}
Releases all threads in the focus
group
uhtp
{dfocus p dunhold –thread}
Releases the threads in the current
process
f w uhtp
htp; uht
104
Unholds all worker threads in the focus process.
Holds all threads in the focus process except the
thread of interest.
Chapter 2: CLI Commands
dunset
dunset
Restores default settings for variables
Format:
Restores a CLI variable to its default value
dunset debugger-var
Restores all CLI variables to their default values
dunset –all
Arguments:
debugger-var
–all
Description:
Name of the CLI variable whose default setting is being
restored.
Restores the default settings of the CLI variables.
Tcl variables (those created with the Tcl set command) are, of course, unaffected by this command.
If you use the –all option, the dunset command affects all changed CLI variables, restoring them to the settings that existed when the CLI session
began. Similarly, specifying debugger-var tells the CLI to restore that one variable.
Examples:
dunset PROMPT
dunset –all
TotalView Reference Guide: version 6.3.1
Restores the prompt string to its default setting; that is,
{[dfocus]>}.
Restores all CLI variables to their default settings.
105
2. CLI Commands
The dunset command reverses the effects of any previous dset commands,
restoring CLI variables to their default settings. See Chapter 4, “TotalView
Variables,” on page 155 for information on these variables.
duntil
duntil
Runs the process until a target place is reached
Format:
Runs to a line
duntil line-number
Runs to an address
duntil –address addr
Runs into a function
duntil proc-name
Arguments:
line-number
–address addr
proc-name
Description:
The duntil command runs the thread of interest until execution reaches a
line or absolute address, or until it enters a function.
A line number in your program.
An address in your program.
The name of a procedure, function, or subroutine in
your program.
If you use a process or group width, all threads in the process or group that
are not running to the goal are allowed to run. If one of the “secondary”
threads arrives at the goal before the thread of interest, it continues running, ignoring this goal. In contrast, if you specify thread width, only the
thread of interest runs.
The duntil command differs from other step commands when you apply it
to a group.
Process group
Thread group
TotalView runs the entire group, and the CLI waits until
all processes in the group have at least one thread that
has arrived at the goal breakpoint. This lets you sync up
all the processes in a group in preparation for groupstepping them.
TotalView runs the process (for p width) or the control
group (for g width) and waits until all the running
threads in the group of interest arrive at the goal.
The differences between this command and other stepping commands are:
■
■
■
106
Process Group Operation: TotalView examines the thread of interest
to see if it is already at the goal. If it is, TotalView does not run the process of interest. Similarly, TotalView examines all other processes in the
share group, and it only runs processes that do not have a thread at the
goal. It also runs members of the control group that are not in the share
group.
Group-Width Thread Group Operation: TotalView identifies all
threads in the entire control group that are not at the goal. Only those
threads are run. While TotalView runs share group members in which all
worker threads are already at the goal, it does not run the workers.
TotalView also runs processes in the control group that are outside the
share group. The duntil command operation ends when all members of
the focus thread group are at the goal.
Process-Width Thread Group Operation: TotalView identifies all
threads in the entire focus process that are not already at the goal. Only
Chapter 2: CLI Commands
duntil
those threads run. The duntil command operation ends when all threads
in the process that are also members of the focus group arrive at the
goal.
Command alias:
Alias
Definition
Meaning
un
{duntil}
Runs the thread of interest until it reaches a
target while allowing other threads in the
process to run.
UN
{dfocus g duntil}
Runs the entire control group until every
process in the share group has at least one
thread at the goal. Processes have a thread
at the goal do not run.
unl
{dfocus L duntil}
Runs the thread of interest until it reaches
the target, and runs all threads in the process
that are at the same PC as the thread of
interest to the same target. Other threads in
the process run freely. The group of threads
that are at the same PC is called the lockstep
group.
This does not force process width. If the
default focus is set to group, this runs the
group.
UNL
{dfocus gL duntil}
Runs “lockstep” threads in the share group
until they reach the target. Other threads in
the control group are allowed to run freely.
unw
{dfocus W duntil}
Runs worker threads in the process to a
target. The nonworker threads in the process
run freely.
This does not force process width. If the
default focus is set to group, this runs the
group.
UNW
{dfocus gW duntil}
Runs worker threads in the same share group
to a target. All other threads in the control
group run freely.
UNW 580
un buggy_subr
TotalView Reference Guide: version 6.3.1
Lines up all worker threads at line 580.
Runs to the start of the buggy_subr routine.
107
2. CLI Commands
Examples:
You may find the following aliases useful:
dup
dup
Moves up the call stack
Format:
dup [ num-levels ]
Number of levels to move up. The default is 1.
Arguments:
num-levels
Description:
The dup command moves the current stack frame up one or more levels. It
also prints the new frame number and function.
Call stack movements are all relative, so dup effectively “moves up” in the
call stack. (“Up” is in the direction of main().)
Frame 0 is the most recent—that is, currently executing—frame in the call
stack, frame 1 corresponds to the procedure that invoked the currently
executing one, and so on. The call stack’s depth is increased by one each
time a procedure is entered, and decreased by one when it is exited. The
effect of dup is to change the context of commands that follow. For example, moving up one level lets you access variables that are local to the procedure that called the current routine.
Each dup command updates the frame location by adding the appropriate
number of levels.
The dup command also modifies the current list location to be the current
execution location for the new frame, so a subsequent dlist displays the
code surrounding this location. Entering dup 2 (while in frame 0) followed
by a dlist, for instance, displays source lines centered around the location
from which the current routine’s parent was invoked. These lines will be in
frame 2.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
u
{dup}
Moves up the call stack
dup
Moves up one level in the call stack. As a result, subsequent dlist commands refer to the procedure that
invoked this one. After this command executes, it displays information about the new frame. For example:
1 check_fortran_arrays_ PC=0x10001254,
FP=0x7fff2ed0 [arrays.F#48]
dfocus p1 u 5
108
Moves up five levels in the call stack for each thread
involved in process 1. If fewer than five levels exist, the
CLI moves up as far as it can.
Chapter 2: CLI Commands
dwait
dwait
Blocks command input until the target processes stop
Format:
Description:
dwait
The dwait command tells the CLI to wait for all threads in the current focus
to stop or exit. Generally, this command treats the focus identically to
other CLI commands.
If you interrupt this command—typically by entering Ctrl+C—the CLI manually stops all processes in the current focus before it returns.
This command has no arguments.
Examples:
dwait
Blocks further command input until all processes in the
current focus have stopped (that is, none of their
threads are still running).
dfocus {p1 p2} dwait
Blocks command input until processes 1 and 2 stop.
TotalView Reference Guide: version 6.3.1
109
2. CLI Commands
Unlike most other CLI commands, this command blocks additional CLI
input until the blocking action is complete.
dwatch
dwatch
Defines a watchpoint
Format:
Defines a watchpoint for a variable
dwatch variable [ –length byte-count ] [ –g | –p | –t ]
[ [ –l lang ] –e expr ] [ –t type ]
Defines a watchpoint for an address
dwatch –address addr –length byte-count [ –g | –p | –t ]
[ [–l lang ] –e expr ] [ –t type ]
Arguments:
variable
–address addr
–length byte-count
–g
–p
–t
–l lang
–e expr
–t type
Description:
A symbol name corresponding to a scalar or aggregate
identifier, an element of an aggregate, or a dereferenced pointer.
An absolute address in the file.
The number of bytes to watch. If a variable is named,
the default is the variable’s byte length.
If you are watching a variable, you only need to specify
the amount of storage to watch if you want to override
the default value.
Tells TotalView to stop all processes in the process’s
control group when the watchpoint is hit.
Tells TotalView to stop the process that hit this watchpoint.
Tells TotalView to stop the thread that hit this watchpoint.
Specifies the language used when you are writing an
expression. The values you can use for lang are c, c++,
f7, f9, and asm, for C, C++, FORTRAN 77, Fortran-9x,
and assembler, respectively. If you do not use a language code, TotalView picks one based on the variable's type. If only an address is used, TotalView uses
the C language.
Not all languages are supported on all systems.
When the watchpoint is triggered, evaluates expr in the
context of the thread that hit the watchpoint. In most
cases, you need to enclose the expression in braces ({
}).
The data type of $oldval/$newval in the expression.
A dwatch command defines a watchpoint on a memory location where the
specified variables are stored. The watchpoint triggers whenever the value
of the variables changes. The CLI returns the ID of the newly created
watchpoint.
Watchpoints are not available on Alpha Linux and HP.
The default action is controlled by the STOP_ALL variable.
110
Chapter 2: CLI Commands
dwatch
The watched variable can be a scalar, array, record, or structure object, or a
reference to a particular element in an array, record, or structure. It can
also be a dereferenced pointer variable.
The CLI lets you obtain a variable’s address in the following two ways if
your application demands that you specify a watchpoint with an address
instead of a variable name:
dprint &variable
■ dwhat variable
■
The dprint command displays an error message if the variable is in a register.
If you do not use the –length modifier, the CLI uses the length attribute
from the program’s symbol table. This means that the watchpoint applies
to the data object named; that is, specifying the name of an array lets you
watch all elements of the array. Alternatively, you can specify that a certain
number of bytes be watched, starting at the named location.
In all cases, the CLI watches addresses. If you specify a variable as the target of a watchpoint, the CLI resolves the variable to an absolute address. If you are watching a local
stack variable, the position being watched is just where the variable happened to be
when space for the variable was allocated.
The focus establishes the processes (not individual threads) for which the
watchpoint is in effect.
The CLI prints a message showing the action point identifier, the location
being watched, the current execution location of the triggering thread, and
the identifier of the triggering threads.
One possibly confusing aspect of using expressions is that their syntax differs from that of Tcl. This is because you will need to embed code written in
Fortran, C, or assembler within Tcl commands. In addition, your expressions will often include TotalView built-in functions.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
wa
{dwatch}
Defines a watchpoint
For these examples, assume that the current process set at the time of the
dwatch command consists only of process 2, and that p is a global variable
that is a pointer.
dwatch *p
TotalView Reference Guide: version 6.3.1
Watches the address stored in pointer p at the time the
watchpoint is defined, for changes made by process 2.
Only process 2 is stopped. Note that the watchpoint
location does not change when the value of p changes.
111
2. CLI Commands
Chapter 14 of the TotalView Users Guide contains additional information on watchpoints.
dwatch
dwatch {*p}
Performs the same action as the previous example.
Because the argument to dwatch contains a space, Tcl
requires that you place the argument within braces.
dfocus {p2 p3} wa *p
Watches the address pointed to by p in processes 2
and 3. Because this example does not contain either a
–p or –g option, the value of the STOP_ALL variable lets
the CLI know if it should stop processes or groups.
dfocus {p2 p3 p4} dwatch –p *p
Watches the address pointed to by p in processes 2, 3,
and 4. The –p option indicates that only the process
triggering the watchpoint is stopped.
wa * aString –length 30 –e {goto $447}
Watches 30 bytes of data beginning at the location
pointed to by aString. If any of these bytes change,
execution control transfers to line 447.
wa my_vbl –type long –e {if ($newval == 0x11ffff38) $stop;}
Watches the my_vbl variable and triggers when
0x11ffff38 is stored into it.
wa my_vbl –e {if (my_vbl == 0x11ffff38) $stop;}
Performs the same function as the previous example.
Note that this tests the variable directly rather than by
using $newval.
112
Chapter 2: CLI Commands
dwhat
dwhat
Determines what a name refers to
Format:
dwhat symbol-name
Arguments:
symbol-name
Description:
The dwhat command tells the CLI to display information about a named
entity in a program. The displayed information contains the name of the
entity and a description of the name. The examples that follow show many
of the kinds of elements that this command can display.
Fully or partially qualified name specifying a variable,
procedure, or other source code symbol.
2. CLI Commands
To view information on CLI variables or aliases, you need to use the dset or alias
commands.
The focus constrains the query to a particular context.
The default width for this command is thread (t).
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
wh
{dwhat}
Determines what a name refers to
These examples show what the CLI displays when you enter one of the
indicated commands.
dprint timeout
timeout = {
tv_sec = 0xc0089540 (-1073179328)
tv_usec = 0x000003ff (1023)
}
dwhat timeout
In thread 1.1:
Name: timeout; Type: struct timeval; Size: 8
bytes; Addr: 0x11fffefc0
Scope: #fork_loop.cxx#snore \
(Scope class: Any)
Address class: auto_var (Local variable)
wh timeval
In process 1:
Type name: struct timeval; Size: 8 bytes; \
Category: Structure
Fields in type:
{
tv_sec
time_t
(32 bits)
tv_usec int
(32 bits)
}
dlist
TotalView Reference Guide: version 6.3.1
20
float field3_float;
21
double field3_double;
22 en_check en1;
23
24 };
25
26 main ()
113
dwhat
27 {
28
29
30 >
31
32
33 }
en_check vbl;
check_struct s_vbl;
vbl = big;
s_vbl.field2_char = 3;
return (vbl + s_vbl.field2_char);
p vbl
vbl = big (0)
wh vbl
In thread 2.3:
Name: vbl; Type: enum en_check; \
Size: 4 bytes; Addr: Register 01
Scope: #check_structs.cxx#main \
(Scope class: Any)
Address class: register_var (Register \
variable)
wh en_check
In process 2:
Type name: enum en_check; Size: 4 bytes; \
Category: Enumeration
Enumerated values:
big
= 0
little = 1
fat
= 2
thin
= 3
p s_vbl
s_vbl = {
field1_int = 0x800164dc (-2147392292)
field2_char = '\377' (0xff, or -1)
field2_chars = "\003"
<padding> = '\000' (0x00, or 0)
field3_int = 0xc0006140 (-1073716928)
field2_uchar = '\377' (0xff, or 255)
<padding> = '\003' (0x03, or 3)
<padding> = '\000' (0x00, or 0)
<padding> = '\000' (0x00, or 0)
field_sub = {
field1_int = 0xc0002980 (-1073731200)
<padding> = '\377' (0xff, or -1)
<padding> = '\003' (0x03, or 3)
<padding> = '\000' (0x00, or 0)
<padding> = '\000' (0x00, or 0)
field2_long = 0x0000000000000000 (0)
...
}
wh s_vbl
In thread 2.3:
Name: s_vbl; Type: struct check_struct; \
Size: 80 bytes; Addr: 0x11ffff240
Scope: #check_structs.cxx#main \
(Scope class: Any)
Address class: auto_var (Local variable)
wh check_struct
In process 2:
Type name: struct check_struct; \
Size: 80 bytes; Category: Structure
114
Chapter 2: CLI Commands
dwhat
}
TotalView Reference Guide: version 6.3.1
115
2. CLI Commands
Fields in type:
{
field1_int
int
(32 bits)
field2_char
char
(8 bits)
field2_chars
<string>[2]
(16 bits)
<padding>
<char>
(8 bits)
field3_int
int
(32 bits)
field2_uchar
unsigned char
(8 bits)
<padding>
<char>[3]
(24 bits)
field_sub
struct sub_struct(320 bits){
field1_int
int
(32 bits)
<padding>
<char>[4]
(32 bits)
field2_long long
(64 bits)
field2_ulong unsigned long
(64 bits)
field3_uint unsigned int
(32 bits)
en1
enum en_check
(32 bits)
field3_double double
(64 bits)
}
...
dwhere
dwhere
Displays locations in the call stack
Format:
Arguments:
dwhere [ num-levels ] [ –a ]
num-levels
–a
Description:
Restricts output to this number of levels of the call
stack. If you omit this option, the CLI shows all levels in
the call stack.
Displays argument names and values in addition to
program location information. If you omit this option,
arguments are not shown.
The dwhere command prints the current execution locations and the call
stacks—or sequences of procedure calls—which led to that point. Information is shown for threads in the current focus, with the default being to
show information at the thread level.
Arguments control the amount of command output in two ways:
■
■
The num-levels argument lets you control how many levels of the call
stacks are displayed, counting from the uppermost (most recent) level. If
you omit this argument, the CLI shows all levels in the call stack. Showing all levels is the default.
The –a option tells the CLI that it should also display procedure argument names and values for each stack level.
A dwhere command with no arguments or options displays the call stacks
for all threads in the target set.
The MAX_LEVELS variable contains the default maximum number of levels
the CLI will display when you don’t use the num-levels argument.
Output is generated for each thread in the target focus.
Command alias:
Examples:
You may find the following alias useful:
Alias
Definition
Meaning
w
{dwhere}
Displays the current location
dwhere
Displays the call stacks for all threads in the current
focus.
dfocus 2.1 dwhere 1
Displays just the most recent level of the call stack corresponding to thread 1 in process 2. This shows just
the immediate execution location of a thread or
threads.
w 1 –a
f p1.< w 5
116
Displays the current execution locations (one level
only) of threads in the current focus together with the
names and values of any arguments that were passed
into the current procedures.
Displays the most recent five levels of the call stacks
for all threads involved in process 1. If the depth of any
Chapter 2: CLI Commands
dwhere
call stack is less than five levels, all of its levels are
shown.
This command is a slightly more complicated way of
saying f p1 w 5 because specifying a process width tells
dwhere to ignore the thread indicator.
2. CLI Commands
TotalView Reference Guide: version 6.3.1
117
dworker
dworker
Adds or removes a thread from a workers group
Format:
Arguments:
dworker { number | boolean }
number
boolean
Description:
If positive, marks the thread of interest as a worker
thread by inserting it into the workers group.
If true, marks the thread of interest as a worker thread
by inserting it into the workers group. If false, marks the
thread as being a nonworker thread by removing it from
the workers group.
The dworker command inserts or removes a thread from the workers
group.
If number is 0 or false, this command marks the thread of interest as a nonworker thread by removing it from the workers group. If number is true or is a
positive value, this command marks the thread of interest as a worker
thread by inserting it in the workers group.
Note that moving a thread into or out of the workers group has no effect
on whether the thread is a “manager” thread. Manager threads are threads
that are created by the pthreads package to manage other threads; they
never execute user code, and cannot normally be controlled individually.
TotalView automatically inserts all threads that are not manager threads
into the workers group.
Command alias:
118
You may find the following aliases useful:
Alias
Definition
Meaning
wof
{dworker false}
Removes the focus thread from the workers
group
wot
{dworker true}
Inserts the focus thread into the workers
group
Chapter 2: CLI Commands
exit
exit
Terminates the debugging session
Format:
exit [ –force ]
Arguments:
–force
Description:
The exit command terminates the TotalView session.
Tells the CLI that TotalView should exit without asking
permission.
After executing this command, the CLI asks if it is all right to exit. If you
answer yes, TotalView exits. If you had entered the CLI from the TotalView
GUI, this command also closes the GUI window.
Any processes and threads that were created by the CLI are destroyed. Any
processes that existed prior to the debugging session (that is, were
attached by the CLI as part of a dattach operation) are detached and left
executing.
The exit and quit commands are interchangeable; they both do exactly the
same thing.
Examples:
exit
TotalView Reference Guide: version 6.3.1
Exits from the CLI, leaving any “attached” processes
running.
119
2. CLI Commands
If you had invoked the CLI from within the TotalView GUI, pressing Ctrl+D closes the
CLI window without exiting from TotalView.
help
help
Displays help information
Format:
help [ topic ]
Arguments:
topic
Description:
The help command prints information about the specified topic or command. If you do no use an argument, the CLI displays a list of the topics for
which help is available.
The topic or command for which the CLI prints information.
If more than one screen of data would be displayed, the CLI fills the screen
with data and then displays a more prompt. You can then press Enter to see
more data or enter q to return to the CLI prompt.
After you type a topic name, the CLI attempts to complete what you type.
The help command also allows you to enter one of the CLI’s built-in
aliases. For example:
d1.<> he a
Ambiguous help topic "a". Possible matches:
alias accessors arguments addressing_expressions
d1.<> he ac
"ac" has been aliased to "dactions":
dactions [ bp-ids ... ] [ -at <source-loc> ] [ -disabled | \
-enabled ]
Default alias: ac
...
d1.<> he acc
The following commands provide access to the properties
of TotalView objects:
...
You can use the capture command to place help information into a variable.
Command alias:
Examples:
120
You may find the following aliases useful:
Alias
Definition
Meaning
he
{help}
Displays help information
help help
Prints information describing the help command.
Chapter 2: CLI Commands
quit
quit
Terminates the debugging session
Format:
quit [ –force ]
Arguments:
–force
Description:
The quit command terminates the CLI session.
Tells the CLI that it should close all TotalView processes
without asking permission.
The exit command terminates the TotalView session.
After executing the quit command, the CLI asks if it is all right to exit. If you
answer yes, TotalView exits. If you had entered the CLI from the TotalView
GUI, this command also closes the GUI window.
Any processes and threads that were created by the CLI are destroyed. Any
processes that existed prior to the debugging session (that is, were
attached by the CLI as part of a dattach operation) are detached and left
executing.
The quit and exit commands are interchangeable; they both do exactly the
same thing.
Examples:
quit
TotalView Reference Guide: version 6.3.1
Exits the CLI, leaving any “attached” processes running (in the run-time environment).
121
2. CLI Commands
If you had invoked the CLI from within the TotalView GUI, pressing Ctrl+D closes the
CLI window without exiting from TotalView.
stty
stty
Sets terminal properties
Format:
stty [ stty-args ]
One or more UNIX stty command arguments as defined
in the man page for your operating system.
Arguments:
stty-args
Description:
The CLI stty command executes a UNIX stty command on the tty associated with the CLI window. This lets you set all of your terminal’s properties.
However, this is most often used to set erase and kill characters.
If you start the CLI from a terminal by using the totalviewcli command, the
stty command alters this terminal’s environment. Consequently, the
changes you make using this command are retained in the terminal after
you exit.
If you omit stty-args, the CLI displays information describing your current
settings.
The output from this command is returned as a string.
Examples:
stty
Prints information about your terminal settings. The
information printed is the same as if you had entered
stty while interacting with a shell.
stty –a
Prints information about all of your terminal settings.
stty erase ^H
Sets the erase key to Backspace.
Resets the terminal’s settings to values that the shell
thinks they should be. If you are having problems with
command-line editing, use this command. (The sane
option is not available in all environments.)
stty sane
122
Chapter 2: CLI Commands
unalias
unalias
Removes a previously defined alias
Format:
Removes an alias
unalias alias-name
Removes all aliases
unalias –all
Arguments:
alias-name
–all
Description:
The unalias command removes a previously defined alias. You can delete all
aliases by using the –all option. Aliases defined in the tvdinit.tvd file are
also deleted.
unalias step2
unalias –all
TotalView Reference Guide: version 6.3.1
Removes the step2 alias; step2 is now undefined and
can no longer be used. If step2 was included as part of
the definition of another command, that command will
no longer work correctly. However, the CLI will only display an error message when you try to execute the alias
that contains this removed alias.
Removes all aliases.
123
2. CLI Commands
Examples:
The name of the alias being deleted.
Tells the CLI to remove all aliases.
unalias
124
Chapter 2: CLI Commands
CLI Namespace
Commands
3
This chapter contains detailed descriptions of CLI namespace commands.
Command Overview ___________________
This section lists all of the CLI namespace commands. It also contains a
short explanation of what each command does.
Accessor Functions
The following functions, all within the TV:: namespace, access and set
TotalView properties:
■
■
■
■
■
■
■
■
■
■
actionpoint: Accesses and sets action point properties.
expr: Manipulates values created by the dprint –nowait command.
focus_groups: Returns a list containing the groups in the current focus.
focus_processes: Returns a list of processes in the current focus.
focus_threads: Returns a list of threads in the current focus.
group: Accesses and sets group properties.
image: Accesses and sets image properties.
process: Accesses and sets process properties.
thread: Accesses and sets thread properties.
type: Accesses and sets data type properties.
The following functions are discussed in the Creating Type Transformations
Guide:
■
■
■
scope: Accesses and sets scope properties.
symbol: Accesses and sets symbol properties.
type_transformation: Accesses and defines type transformations.
TotalView Reference Guide: version 6.3.1
125
Command Overview
Helper Functions
The following functions, all within the TV:: namespace, are most often used
in scripts:
■
■
■
■
■
■
■
126
dll: Manages shared libraries.
dec2hex: Converts a decimal number into hexadecimal format.
errorCodes: Returns or raises TotalView error information.
hex2dec: Converts a hexadecimal number into decimal format.
read_symbols: Reads shared library symbols.
respond: Sends a response to a command.
source_process_startup: “Sources” a .tvd file when a process is loaded.
Chapter 3: CLI Namespace Commands
actionpoint
actionpoint
Format:
Arguments:
Sets and gets action point properties
TV::actionpoint action [ object-id ] [ other-args ]
action
commands
get
properties
set
object-id
An identifier for the action point.
other-args
Are arguments that the get and set actions use.
The TV::actionpoint command lets you examine and set action point properties and states. These states and properties are:
address
enabled
expression
id
language
length
line
The address of the action point.
A value (either 1 or 0) indicating if the action point is
enabled. A value of 1 means enabled. (settable)
The expression to be executed at an action point. (settable)
The ID of the action point.
The language in which the action point expression is
written.
The length in bytes of a watched area. This property is
only valid for watchpoints. (settable)
The source line at which the action point is set. This is
not valid for watchpoints.
satisfaction_group
share
TotalView Reference Guide: version 6.3.1
The group that must arrive at a barrier for the barrier to
be satisfied. (settable)
A value (either 1 or 0) indicating if the action point is
active in the entire share group. A value of 1 means
that it is. (settable)
127
3. Namespace Commands
Description:
The action to perform, as follows:
Displays the subcommands that you can use. The CLI
responds by displaying the four subcommands shown
here. No other arguments are used with this subcommand.
Retrieves the values of one or more action point properties. The other-args argument can include one or more
property names. The CLI returns values for these properties in a list whose order is the same as the property
names you entered.
If you use the –all option as the object-id, the CLI returns
a list containing one (sublist) element for each object.
Lists the action point properties that TotalView can
access. No other arguments are used with this subcommand.
Sets the values of one or more properties. The other-args
argument contains property name and value pairs.
actionpoint
stop_when_done
Indicates what is stopped when a barrier is satisfied (in
addition to the satisfaction set). Values are process,
group, or none. (settable)
stop_when_hit
type
type_values
Examples:
Indicates what is stopped when an action point is hit
(in addition to the thread that hit the action point). Values are process, group, or none. (settable)
The object’s type. See type_values for a list of possible
types.
Lists values that can be assigned to the type property:
break, eval, process_barrier, thread_barrier, and watch.
TV::actionpoint set 5 share 1 enable 1
Shares and enables action point 5.
f p3 TV::actionpoint set –all enable 0
Disables all the action points in process 3.
foreach p [TV::actionpoint properties] {
puts [format “%20s %s” $p: \
[TV::actionpoint get 1 $p]]
Dumps all the properties for action point 1. Here is
what your output might look like:
address:
enabled:
expression:
id:
language:
length:
line:
satisfaction_group:
satisfaction_process:
satisfaction_width:
share:
stop_when_done:
stop_when_hit:
type:
type_values:
128
0x1200019a8
0
1
/temp/arrays.F#84
1
group
break
break eval
process_barrier
thread_barrier watch
Chapter 3: CLI Namespace Commands
dll
dll
Manages shared libraries
Format:
Arguments:
TV::dll action [ dll-id-list ] [ other-args ]
action
close
commands
get
properties
The action to perform, as follows:
Dynamically unloads the shared object libraries that
were dynamically loaded by the ddlopen commands
corresponding to the list of dll-ids.
If you use the –all option, TotalView closes all of the
libraries that it opened.
Displays the subcommands that you can use. The CLI
responds by displaying the subcommands shown here.
No other arguments are used with this subcommand.
Retrieves the values of one or more TV::dll properties.
The other-args argument can include one or more property names.
If you use the –all option as the dll-id-id, the CLI returns
a list containing one (sublist) element for each object.
Lists the TV::dll properties that TotalView can access.
No other arguments are used with this subcommand.
resolution_urgency_values
Returns a list of values that this property can take. This
list is operating system specific, but always includes
{lazy now}.
Returns a list of values that this property can take. This
list is operating system specific, but always includes
{lazy now}.
Description:
The TV::dll command either closes shared libraries that were dynamically
loaded with the ddlopen command or obtains information about loaded
shared libraries. For example, use the following command to close the first
shared library that you opened:
TV::dll close 1
TotalView Reference Guide: version 6.3.1
129
3. Namespace Commands
symbol_availability_values
dec2hex
dec2hex
Converts a decimal number into hexadecimal
Format:
130
TV::dec2hex number
Arguments:
number
Description:
The TV::dec2hex command converts a decimal number into hexadecimal.
This command correctly manipulates 64-bit values, regardless of the size of
a long on the host system.
A decimal number.
Chapter 3: CLI Namespace Commands
errorCodes
errorCodes
Returns or raises TotalView error information
Format:
Returns a list of all error code tags
TV::errorCodes
Returns or raises error information
TV::errorCodes
Arguments:
Description:
number_or_tag [ –raise [ message ] ]
number_or_tag
Enters an error code mnemonic tag or its numeric
value.
–raise
Raises the corresponding error. If you append a message,
TotalView returns this string. Otherwise, TotalView uses
the human-readable string for the error.
message
An optional string used when raising an error.
The TV::errorCodes command lets you manipulate the TotalView error code
information placed in the Tcl errorCodes variable. The CLI sets this variable
after every command error. Its value is intended to be easy to parse in a Tcl
script.
When the CLI or TotalView returns an error, errorCode is set to a list whose
format is:
TOTALVIEW error-code subcodes... string
The contents of this lists are as follows:
■
■
■
The first list element is always TOTALVIEW.
The second is always the error code.
subcodes are not used at this time.
The last element is a string describing the error.
With a tag or number, this command returns a list containing the mnemonic
tag, the numeric value of the tag, and the string associated with the error.
The –raise option tells the CLI to raise an error. If you add a message, that
message is used as the return value; otherwise, the CLI uses its textual
explanation for the error code. This provides an easy way to return
TotalView-style errors from a script.
Examples:
foreach e [TV::errorCodes] {
puts [eval format {"%20s %2d %s"} \
[TV::errorCodes $e]]}
Displays a list of all TotalView error codes.
TotalView Reference Guide: version 6.3.1
131
3. Namespace Commands
■
expr
expr
Manipulates values created by dprint –nowait
Format:
Arguments:
TV::expr action [ susp-eval-id ] [ other-args ]
action
commands
delete
get
properties
Description:
The action to perform, as follows:
Displays the subcommands that you can use. The CLI
responds by displaying the subcommands shown here.
Do not use additional arguments with this subcommand.
Deletes all data associated with a suspended ID. If you
use this command, you can specify an other-args argument. If you specify –done, the CLI deletes the data for
all completed expressions; that is, those where TV::expr
get susp-eval-id done returns 1. If you specify –all, the
CLI deletes all data for all expressions.
Gets the values of one or more expr properties. The
other-args argument can include one or more values. The
CLI returns these values in a list whose order is the
same as the property names.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each object.
Displays the properties that the CLI can access. Do not
use additional arguments with this option.
susp-eval-id
The ID returned or thrown by the dprint command or
printed by the dwhere command.
other-args
Arguments required by the delete subcommand, as just
discussed.
The TV::expr command, in addition to showing you command information,
returns and deletes values returned by a dprint –nowait command. The
properties that you can use for this command are:
done
TV::expr returns 1 if the process associated with susp-
eval-id has finished in all focus threads. Otherwise, it
returns 0.
expression
The expression to execute.
focus_threads
A list of dpid.dtid values in which the expression is being
executed.
id
The susp-eval-id of the object.
initially_suspended_process
A list of dpid’s for the target processes that received
control because they executed the function calls or
compiled code. You can wait for processes to complete
by entering:
dfocus p dfocus [TV::expr get \
susp-eval-id \
initially_suspended_processes] dwait
132
Chapter 3: CLI Namespace Commands
expr
result
A list of pairs for each thread in the current focus. Each
pair contains the thread as the first element and that
thread’s result string as the second element. For example:
d1.<> dfocus {1.1 2.1} TV::expr \
get susp-eval-id result
{{1.1 2} {2.1 3}} d1.<>
The result of expression susp-eval-id in thread 1.1 is 2
and in thread 2.1 is 3:
status
A list of pairs for each thread in the current focus. Each
pair contains the thread ID as the first element and
that thread’s status string as the second element. The
possible status strings are:
done, suspended, and {error diag}
For example, if expression susp-eval-id finished in thread
1.1, suspended on a breakpoint in thread 2.1, and
received a syntax error in thread 3.1, that expression's
status property has the following value when TV::expr is
focused on threads 1.1, 2.1, and 3.1:
d1.<> dfocus {t1.1 t2.1 t3.1} \
TV::expr get 1 status
{1.1 done} {2.1 suspended} {3.1 {error {Symbol
nothing2 not found}}}
d1.<>
3. Namespace Commands
TotalView Reference Guide: version 6.3.1
133
focus_groups
focus_groups
Format:
Description:
Examples:
Returns a list of groups in the current focus
TV::focus_groups
The TV::focus_groups command returns a list of all groups in the current
focus.
f d1.< TV::focus_groups
Returns a list containing one entry, which will be the ID
of the control group for process 1.
134
Chapter 3: CLI Namespace Commands
focus_processes
focus_processes
Format:
Arguments:
Description:
Examples:
Returns a list of processes in the current focus
TV::focus_processes [ –all | –group | –process | –thread ]
–all
Changes the default width to all.
–group
Changes the default width to group.
–process
Changes the default width to process.
–thread
Changes the default width to thread.
The TV::focus_processes command returns a list of all processes in the current focus. If the focus width is something other than d (default), the focus
width determines the set of processes returned. If the focus width is d, the
TV::focus_processes command returns process width. Using any of the
options changes the default width.
f g1.< TV::focus_processes
Returns a list containing all processes in the same control as process 1.
3. Namespace Commands
TotalView Reference Guide: version 6.3.1
135
focus_threads
focus_threads
Format:
Arguments:
Description:
Examples:
Returns a list of threads in the current focus
TV::focus_threads [ –all | –group | –process | –thread ]
–all
Changes the default width to all.
–group
Changes the default width to group.
–process
Changes the default width to process.
–thread
Changes the default width to thread.
The TV::focus_threads command returns a list of all threads in the current
focus. If the focus width is something other than d (default), the focus
width determines the set of threads returned. If the focus width is d,
TV::focus_threads returns thread width. Using any of the options changes
the default width.
f p1.< TV::focus_threads
Returns a list containing all threads in process 1.
136
Chapter 3: CLI Namespace Commands
group
group
Sets and gets group properties
Format:
Arguments:
TV::group action [ object-id ] [ other-args ]
action
commands
get
properties
set
object-id
The group ID. If you use the –all option, the operation
is carried out on all groups in the current focus.
other-args
Arguments required by the get and set subcommands.
The TV::group command lets you examine and set group properties and
states. These states and properties are:
count
The number of members in a group.
id
The ID of the object.
member_type
The type of the group’s members, either process or
thread.
member_type_values
Returns a list of all possible values for the
member_type property.
Examples:
members
A list of a group’s processes or threads.
type
The group’s type. Possible values are control, lockstep,
share, user, and workers.
type_values
Returns a list of all possible values for the type property.
TV::group get 1 count
Returns the number of objects in group 1.
TotalView Reference Guide: version 6.3.1
137
3. Namespace Commands
Description:
The action to perform, as follows:
Displays the subcommands that you can use. The CLI
responds by displaying the four subcommands shown
here. Do not use additional arguments with this subcommand.
Gets the values of one or more group properties. The
other-args argument can include one or more property
names. The CLI returns these values for these properties in a list in the same order as you entered the property names.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each group.
Displays the properties that the CLI can access. Do not
use additional arguments with this option.
Sets the values of one or more properties. The other-args
argument is a sequence of property name and value
pairs.
hex2dec
hex2dec
Converts to decimal
Format:
138
TV::hex2dec number
Arguments:
number
Description:
The TV::hex2dec Converts a hexadecimal number into decimal. You can
type 0x before this value. The CLI correctly manipulates 64-bit values,
regardless of the size of a long.
A hexadecimal number.
Chapter 3: CLI Namespace Commands
image
image
Sets and gets image properties
Format:
Arguments:
TV::image action [ object-id ] [ other-args ]
action
add
commands
get
lookup
TV::image lookup 1|15 type “int *”
lookup_keys
If no matching objects are found, the CLI returns an
empty list. You can obtain a list of class objects by
using the lookup_keys property.
A list containing the object classes that can be used in
a by name lookup; for example:
TV::image lookup 1|20 types foo
properties
set
object-id
Currently, the only value returned is {types}.
Displays the properties that the CLI can access. Do not
use additional arguments with this option.
Sets the values of one or more image properties. The
other-args argument contains property name and value
pairs.
The ID of an image. An image ID is two integers that
identify the base executable and an associated DLL.
You can obtain a list of all image IDs by using the following command:
TV::image get –all id
If you use the –all option, TotalView carries out this
operation on all images in the current focus.
TotalView Reference Guide: version 6.3.1
139
3. Namespace Commands
The action to perform, as follows:
Adds an object to an image. The object-id argument is
required; other-args is followed by two arguments. The
first is the object class of the image. At this release,
this type can only be type_transformation. The second
is the prototype’s ID. (This is illustrated in the Examples
section.)
Displays the subcommands that you can use. The CLI
responds by displaying the six subcommands shown
here. Do not use additional arguments with this subcommand.
Gets the values of one or more image properties. The
other-args argument can include one or more property
names. The CLI returns these values for these properties in a list in the same order as you entered the property names.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each object.
Looks up an object in the image and returns a list of
IDs of matching objects. The object-id argument is
required; other-args contains two arguments. The first is
the object class of the image and the second is the
name of the object. For example:
image
other-args
Description:
Arguments required by the get and set subcommands.
The TV::image command lets you examine and set the image properties
and states. “Image” refers to all the programs, libraries, and other components that make up your executable. These states and properties are:
data_size
The amount of memory used to store initialized data.
dpids
IDs of the process associated with a thread
id
The ID of the object.
is_dll
A true/false value where 1 indicates the image is a
shared library and 0 if it is an executable.
name
The name of the image.
type_transformations
A list of all of the type transformations that apply to an
image.
text_size
Examples:
The amount of memory used to store your program’s
machine code instructions. The “text segment” is
sometimes called the “code segment.”
TV::image lookup 1|15 type “int *”
Finds the type identifiers for the int * type in image
1|15. The result might be:
1|25 1|76
There can be more than one type with the same name
in an image since many debugging formats provide
separate type definitions in each source file.
foreach i [TV::image get –all id] {
puts [format “%40s; %s” [TV::image get $i name]
$i]}
Lists all current images along with their IDs.
140
Chapter 3: CLI Namespace Commands
process
process
Sets and gets process properties
Format:
Arguments:
TV::process action [ object-id ] [ other-args ]
action
commands
get
properties
set
object-id
An identifier for a process. For example, 1 represents
process 1. If you use the –all option, the subcommand
is carried out on all objects of this class in the current
focus.
other-args
Arguments required by the get and set subcommands.
The TV::process command lets you examine and set process properties
and states. These states and properties are:
clusterid
The ID of the cluster containing a process. This is a
number uniquely identifying the TotalView server that
owns the process. The ID for the cluster TotalView is
running in is always 0 (zero).
duid
The internal unique ID associated with an object.
executable
The program’s name.
heap_size
The amount of memory currently being used for data
created at runtime. Stated in a different way, the heap
is an area of memory that your program uses when it
needs to dynamically allocate memory. For example,
calls to malloc() allocate space on the heap while free()
releases it.
held
A value (either 1 or 0) indicating if the process is held; 1
means that the process is held. (settable)
hostname
The name of the process's host system.
id
The process ID.
TotalView Reference Guide: version 6.3.1
141
3. Namespace Commands
Description:
The action to perform, as follows:
Displays the subcommands that you can use. The CLI
responds by displaying the four subcommands shown
here. Do not use other arguments with this subcommand.
Gets the values of one or more process properties. The
other-args argument can include one or more property
names. The CLI returns these property values in a list
whose order is the same as the property names you
entered.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each object.
Displays the properties that the CLI can access. Do not
use other arguments with this subcommand.
Sets the values of one or more properties. The other-args
arguments contains pairs of property names and values.
process
Examples:
image_ids
A list of the IDs of all the images currently loaded into
the process both statically and dynamically. The first
element of the list is the current executable.
nodeid
The ID of the node upon which the process is running.
The ID of each processor node is unique within a cluster.
stack_size
The amount of memory used by the currently executing
block or routines and all the blocks routines that have
invoked it. For example, if your main routines invokes
function foo(), the stack contains two groups of information—these groups are called “frames.” The first
frame contains the information required for the execution of your main routine and the second, which is the
current frame, contains the information needed by
foo(). If foo() invokes bar(), the stack contains three
frames. When foo() finishes executing, the stack only
contains one frame.
stack_vm_size
The logical size of the stack is the difference between
the current value of the stack pointer and address from
which the stack originally grew. This value can be different from the size of the virtual memory mapping in
which the stack resides. For example, the mapping can
be larger than the logical size of the stack if the process
previously had a deeper nest of procedure calls or
made memory allocations on the stack, or it can be
smaller if the stack pointer has advanced but the intermediate memory has not been touched.
The value here is this difference in size.
state
Current state of the process. See state_values for a list
of states.
state_values
Lists all possible values for the state property. These
values can be break, error, exited, running, stopped, or
watch.
syspid
The system process ID.
text_size
The amount of memory used to store your program’s
machine code instructions. The “text segment” is
sometimes called the “code segment.”
threadcount
The number of threads in the process.
threads
A list of threads in the process.
vm_size
The sum of the sizes of the mappings in the process's
address space.
TV::process get 3 threads
Gets the list of threads for process 3. For example:
1.1 1.2 1.4
TV::process get 1 image_ids
Returns a list of image IDs in process 1. For example:
1|1 1|2 1|3 1|4
142
Chapter 3: CLI Namespace Commands
process
f g TV::process get –all id threads
For each process in the group, creates a list with the
process ID followed by the list of threads. For example:
{1 {1.1 1.2 1.4}} {2 {2.3 2.5}} {3 {3.1 3.7
3.9}}
foreach i [TV::process get 1 image_ids] {
puts [TV::image get $i name]}
Prints the name of the executable and all shared libraries currently linked into the focus process. For example, the output of this command might be:
arraysAIX
/usr/lib/libxlf90.a
/usr/lib/libcrypt.a
/usr/lib/libc.a
3. Namespace Commands
TotalView Reference Guide: version 6.3.1
143
read_symbols
read_symbols
Format:
Reads shared library symbols
Reads symbols from libraries
TV::read_symbols –lib lib-name-list
Reads symbols from libraries associated with a stack frame
TV::read_symbols –frame [number]
Reads symbols for all stack frames in the backtrace
TV::read_symbols –stack
Arguments:
Description:
–lib [lib-name-list]
Tells TotalView to read symbols for all libraries whose
names are contained within the lib-name-list argument.
Each name can include the * (asterisk) and ? (question
mark) wildcard characters.
This command ignores the current focus; libraries for
any process can be affected.
–frame [number]
Tells TotalView to read the symbols for the library associated with the current stack frame. If you also enter a
frame number, TotalView will read the symbols for the
library associated with that frame.
–stack
Reads the symbols for every frame in the backtrace.
This is identical to right-clicking in the Stack Trace Pane
and selecting the Load All Symbols in Stack command.
If, while reading in a library, TotalView may also need to
read in the symbols from additional libraries.
The TV::read_symbols command reads debugging symbols from one or
more libraries that TotalView has already loaded but whose symbols have
not yet been read because they were included within either the
TV::dll_read_loader_symbols_only or TV::dll_read_no_symbols lists.
For more information, see “Fine Tuning Shared Library Use” within the “Debugging Programs” chapter of the TotalView Users Guide.
144
Chapter 3: CLI Namespace Commands
respond
respond
Provides responses to commands
Format:
Arguments:
Description:
TV::respond response command
response
The response to one or more commands. If you include
more than one response, separate the responses with
newline characters.
command
One or more commands that the CLI will execute.
The TV::respond command executes a command. The command argument
can be a single command or a list of commands. In most cases, you will
place this information within braces ({}). If the CLI asks questions while
command is executing, you are not asked for the answer. Instead, the CLI
uses the characters in the response string for it. If more than one question is
asked and response is used up, TV::respond starts over at the beginning of
the response string. If response does not end with a newline, TV::respond
appends one.
Do not use this command to suppress the MORE prompt in macros. You
should instead use the following command:
dset LINES_PER_SCREEN 0
The most common values for response are y and n.
Examples:
TV::respond {y} {exit}
Exits from TotalView. This command automatically
answers the “Do you really wish to exit TotalView”
question.
set f1 y
set f2 exit
TV::respond $f1 $f2
A way to exit from TotalView without seeing the “Do
you really wish to exit TotalView” question. Neither of
these two uses is recommended. Instead, you can use
exit –force.
TotalView Reference Guide: version 6.3.1
145
3. Namespace Commands
If you are using the TotalView GUI and the CLI at the same time, your CLI command
may cause dialog boxes to appear. You cannot use the TV::respond command to close or
interact with these dialog boxes.
scope
scope
Sets and gets internal scope properties
Format:
Description:
146
TV::scope action [ object-id ] [ other-args ]
The TV::scope command lets you examine and set the scope properties and
states. This command is explained in the Creating Type Transformation Guide.
Chapter 3: CLI Namespace Commands
source_process_startup
source_process_startup
Format:
“Sources” a .tvd file when a process is loaded
TV::source_proccess_startup process_id
Arguments:
process_id
Description:
The TV::source_process_startup command loads and interprets the .tvd file
associated with the current process. That is, if a file named executable.tvd
exists, the CLI sources it.
The PID of the current process.
3. Namespace Commands
TotalView Reference Guide: version 6.3.1
147
symbol
symbol
Gets and sets symbol properties
Format:
Description:
148
TV::symbol action [ object-id ] [ other-args ]
The TV::symbol command lets you examine and set the symbol properties
and states. This command is explained in the Creating Type Transformation
Guide.
Chapter 3: CLI Namespace Commands
thread
thread
Gets and sets thread properties
Format:
Arguments:
TV::thread action [ object-id ] [ other-args ]
action
commands
get
properties
set
Description:
object-id
A thread ID. If you use the –all option, the operation is
carried out on all threads in the current focus.
other-args
Arguments required by the get and set subcommands.
The TV::thread command lets you examine and set the thread properties
and states. These states and properties are:
continuation_sig
The signal that should be passed to a thread the next
time it runs. On some systems, the thread receiving the
signal may not always be the one for which this property was set.
dpid
The ID of the process associated with a thread.
duid
The internal unique ID associated with the thread.
held
A value (either 1 or 0) indicating if the thread is held; 1
means that the thread is held. (settable)
id
The ID of the thread.
manager
A value (either 1 or 0) indicating if this is a system manger thread; 1 means that it is.
pc
Current PC at which the target is executing. (settable)
sp
The value of the stack pointer.
state
Current state of the target. See state_values for a list of
states.
state_values
A list of values for the state property. These values are
break, error, exited, running, stopped, and watch.
systid
The system thread ID.
f p3 TV::thread get –all id
Returns a list of thread IDs for process 3. For example:
TotalView Reference Guide: version 6.3.1
149
3. Namespace Commands
Examples:
The action to perform, as follows:
Displays the subcommands that you can use. The CLI
responds by displaying the four subcommands shown
here. Do not use other arguments with this option.
Gets the values of one or more thread properties. The
other-args argument can include one or more property
names. The CLI returns these values in a list, and
places them in the same order as the property names
you entered.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each object.
Lists an object’s properties. Do not use other arguments with this option.
Sets the values of one or more properties. The other-args
argument contains paired property names and values.
thread
1.1 1.2 1.4
150
Chapter 3: CLI Namespace Commands
type
type
Gets and sets type properties
Format:
Arguments:
TV::type action [ object-id ] [ other-args ]
action
The action to perform, as follows:
commands
get
properties
set
object-id
An identifier for an object. For example, 1 represents
process 1, and 1.1 represents thread 1 in process 1. If
you use the –all option, the operation is carried out on
all objects of this class in the current focus.
other-args
Arguments required by the get and set subcommands.
The TV::type command lets you examine and set the type properties and
states. These states and properties are:
enum_values
For an enumerated type, a list of {name value} pairs
giving the definition of the enumeration. If you apply
this to a non-enumerated type, the CLI returns an
empty list.
id
The ID of the object.
image_id
The ID of the image in which this type is defined.
language
The language of the type.
length
The length of the type.
name
The name of the type; for example, class foo.
prototype
The ID for the prototype. If the object is not prototyped, the returned value is {}.
rank
(array types only) The rank of the array.
struct_fields
(class/struct/union types only). A list of lists giving the
description of all the type’s fields. Each sublist contains the following fields:
{ name type_id addressing properties }
TotalView Reference Guide: version 6.3.1
151
3. Namespace Commands
Description:
Displays the subcommands that you can use. The CLI
responds by displaying the four subcommands shown
here. Do not use other arguments with this option.
Gets the values of one or more type properties. The
other-args argument can include one or more property
names. The CLI returns these values in a list, and
places them in the same order as the property names
you entered.
If you use the –all option as an object-id, the CLI returns
a list containing one (sublist) element for each object.
Lists a type’s properties. Do not use other arguments
with this option.
Sets the values of one or more type properties. The
other-args argument contains paired property names
and values.
type
where:
name is the name of the field.
type_id is simply the type_id of the field.
addressing contains additional addressing information
that points to the base of the field.
properties contains an additional list of properties in the
following format:
“[virtual] [public|private|protected] base class”
If no properties apply, this string is null.
If you use get struct_fields for a type that is not a class,
struct, or a union, the CLI returns an empty list.
Examples:
target
For an array or pointer type, returns the ID of the array
member or target of the pointer. If this is not applied to
one of these types, the CLI returns an empty list.
type
Returns a string describing this type. For example,
signed integer.
type_values
Returns all possible values for the type property.
TV::type get 1|25 length target
Finds the length of a type and (assuming it is a pointer
or an array type) the target type. The result may look
something like:
4 1|12
The following example uses the TV::type properties command to obtain the
list of properties. It begins by defining a proc:
proc print_type {id} {
foreach p [TV::type
properties] {
puts [format "%13s %s" $p [TV::type get $id $p]]
}
}
You would then display information with the following command:
print_type 1|6
enum_values
id
image_id
language
length
name
prototype
rank
struct_fields
target
type
type_values
152
1|6
1|1
f77
4
<integer>
0
Signed Integer
{Array} {Array of characters}
{Enumeration}...
Chapter 3: CLI Namespace Commands
type_transformation
type_transformation
Format:
Description:
Creates type transformations and examine properties
TV::type_transformation action [ object-id ] [ other-args ]
The TV::type_transformation command lets you examine and set the scope
properties and states. This command is explained in the Creating Type Transformation Guide.
3. Namespace Commands
TotalView Reference Guide: version 6.3.1
153
type_transformation
154
Chapter 3: CLI Namespace Commands
TotalView Variables
4
This chapter contains a list of all CLI and TotalView variables. This
chapter has three sections, each corresponding to a CLI namespace,
as follows:
■
■
■
Top-Level (::) Namespace
TV:: Namespace
TV::GUI:: Namespace
Top-Level (::) Namespace _______________
ARGS(dpid)
Contains the arguments that TotalView passes to the process with
TotalView ID dpid the next time you start the process.
Permitted Values:
Default:
ARGS_DEFAULT
Contains the argument passed to a new process when no ARGS(dpid) variable is defined.
Permitted Values:
Default:
BARRIER_STOP_ALL
A string
None
A string
None
Contains the value for the “stop_when_done” property for newly created
action points. This property tells TotalView what else it should stop when a
barrier point is satisfied. This property also tells TotalView what else it
should stop when a thread encounters this action point. You can also set
this value using the When barrier hit, stop value in the Action Points Page of
the File > Preferences Dialog Box. The values that you can use are as follows:
group
TotalView Reference Guide: version 6.3.1
TotalView will stop all processes in a thread’s control
group when a thread reaches a barrier created using
this as a default.
155
BARRIER_STOP_WHEN_DONE - COMMAND_EDITING
process
TotalView will stop the process in which the thread is
running when a thread reaches a barrier created using
this default.
none
TotalView just stops the thread that hit a barrier created using this default.
This variable is the same as the TV::barrier_stop_all variable.
Permitted Values:
Default:
BARRIER_STOP_
WHEN_DONE
group, process, or thread
group
Contains the default value that TotalView uses when a barrier point is satisfied. You can also set this value if you use the –stop_when_done commandline option or the When barrier done, stop value in the Action Points Page
of the File > Preferences Dialog Box. The values you can use are as follows:
group
When a barrier is satisfied, TotalView stops all processes in the control group.
process
When a barrier is satisfied, TotalView stops the processes in the satisfaction set.
none
TotalView only stops the threads in the satisfaction set;
other threads are not affected. For process barriers,
there is no difference between process and none.
In all cases, TotalView releases the satisfaction set when the barrier is satisfied.
This variable is the same as the TV::barrier_stop_when_done variable.
Permitted Values:
Default:
CGROUP(dpid)
group, process, or thread
group
Contains the control group for the process with the TotalView ID dpid. Setting this variable moves process dpid into a different control group. For
example, the following command moves process 3 into the same group as
process 1:
dset CGROUP(3) $CGROUP(1)
Permitted Values:
Default:
COMMAND_EDITING
A number
None
Enables some Emacs-like commands that you can use while editing text in
the CLI. These editing commands are always available in the CLI window of
the TotalView GUI. However, they are only available in the stand-alone CLI
if the terminal in which you are running it supports cursor positioning and
clear-to-end-of-line. The commands that you can use are:
^A: Moves the cursor to the beginning of the line.
^B: Moves the cursor one character backward.
^D: Deletes the character to the right of cursor.
^E: Moves the cursor to the end of the line.
^F: Moves the cursor one character forward.
^K: Deletes all text to the end of line.
156
Chapter 4: TotalView Variables
EXECUTABLE_PATH - LINES_PER_SCREEN
^N: Retrieves the next entered command (only works after ^P).
^P: Retrieves the previously entered command.
^R or ^L: Redraws the line.
^U: Deletes all text from the cursor to the beginning of the line.
Rubout or Backspace: Deletes the character to the left of the cursor.
Permitted Values:
Default:
EXECUTABLE_PATH
Contains a colon-separated list containing the directories that TotalView
searches when it looks for source and executable files.
Permitted Values:
Default:
GROUP(gid)
true or false
false
Any directory or directory path. To include the current
setting, use $EXECUTABLE_PATH.
. (dot)
Contains a list containing the TotalView IDs for all members in group gid.
The first element in the list indicates what kind of group it is, as follows:
control
The group of all processes in a program
lockstep
A group of threads that share the same PC
process
A user-created process group
share
The group of processes in one program that share the
same executable image
thread
A user-created thread group
workers
The group of worker threads in a program
Elements that follow are either pids (for process groups) or pid.tid pairs (for
thread groups).
The gid is a simple number for most groups. In contrast, a lockstep group’s
ID number is of the form pid.tid. Thus, GROUP(2.3) contains the lockstep
group for thread 3 in process 2. Note, however, that the CLI will not display
lockstep groups when you use dset with no arguments—they are hidden
variables.
The GROUP(id) variable is read-only.
Permitted Values:
Default:
Contains a list that contains all TotalView groups IDs. Lockstep groups are
not contained in this list. This is a read-only value and cannot be set.
Permitted Values:
LINES_PER_SCREEN
A Tcl list of IDs.
Defines the number of lines shown before the CLI stops printing information and displays its more prompt. The following values have special meaning:
0
TotalView Reference Guide: version 6.3.1
No more processing occurs, and the printing does not
stop when the screen fills with data.
157
4. Variables
GROUPS
A Tcl array of lists indexed by the group ID. Each entry
contains the members of one group.
None
MAX_LEVELS - SHARE_ACTION_POINT
NONE
This is a synonym for 0.
AUTO
The CLI uses the tty settings to determine the number
of lines to display. This may not work in all cases. For
example, Emacs sets the tty value to 0. If AUTO works
improperly, you will need to explicitly set a value.
Permitted Values:
Default:
MAX_LEVELS
Defines the maximum number of levels that the dwhere command will display.
Permitted Values:
Default:
MAX_LIST
PTSET
Permitted Values:
Any string. If you wish to access the value of PTSET,
you must place the variable within brackets; that is,
[dset PTSET].
Default:
{[dfocus]> }
Contains the current focus. This is a read-only value and cannot be set.
A string
d1.<
Contains the group ID of the share group for process pid. TotalView decides
which share group this is by looking at the control group for the process
and the executable associated with this process. You cannot directly modify this group.
Permitted Values:
Default:
SHARE_ACTION_
POINT
An integer
None
Defines the CLI prompt. If you use brackets ([ ]) in the prompt, TotalView
assumes the information within the brackets is a Tcl command and evaluates this information before it creates the prompt string.
Permitted Values:
Default:
SGROUP(pid)
A positive integer
20
Contains a list of information associated with a dpid. This is a read-only
value and cannot be set.
Permitted Values:
Default:
PROMPT
A positive integer
512
Defines the number of lines that the dlist command will display.
Permitted Values:
Default:
PROCESS(dpid)
A positive integer, or the AUTO or NONE strings
Auto
A number
None
Indicates the scope in which TotalView places newly created action points.
In the CLI, this is the dbarrier, dbreak, and dwatch commands. If this Boolean value is true, newly created action point are shared across the group. If
it is false, a newly created action point is only active in the process in which
it is set.
As an alternative to setting this variable, you can select the Plant in share
group check box in the Action Points Page in the File > Preferences Dialog
158
Chapter 4: TotalView Variables
STOP_ALL - VERBOSE
Box. You can override this value in the GUI by using selecting the Plant in
share group checkbox in the Action Point > Properties Dialog Box.
Permitted Values:
Default:
STOP_ALL
Indicates a default property for newly created action points. This property
tells TotalView what else it should stop when it encounters this action
point. The values you can set are as follows:
group
Stops the entire control group when the action point is
hit.
process
Stops the entire process when the action point is hit.
thread
Only stops the thread that hit the action point. Note
that none is a synonym for thread.
Permitted Values:
Default:
TAB_WIDTH
Default:
Default:
Any valid directory or directory path. To include the
current setting, use $TOTALVIEW_TCLLIB_PATH.
The directory containing the CLI’s Tcl libraries
A string containing the platform and string
Platform-specific
Controls the error message information displayed by the CLI. The values for
this variable can be:
TotalView Reference Guide: version 6.3.1
159
4. Variables
Contains the version number and the type of computer architecture upon
which TotalView is executing. This is a read-only variable and cannot be set.
Permitted Values:
Default:
VERBOSE
The location of the TotalView installation directory
Contains a list containing the directories in which the CLI searches for TCL
library components.
Permitted Values:
TOTALVIEW_
VERSION
A Tcl list
None
Names the directory in which the TotalView executable is located. This is a
read-only variable and cannot be set. This variable is exported as TVROOT,
and is can be used in launch strings.
Permitted Values:
TOTALVIEW_TCLLIB_
PATH
A positive number. A value of –1 indicates that the CLI
does not simulate tab expansion.
8
Contains a list of all threads in the process pid, in the form {pid.1 pid.2 ...}.
This is a read-only variable and cannot be set.
Permitted Values:
Default:
TOTALVIEW_ROOT_
PATH
group, process, or thread
process
Indicates the number of spaces used to simulate a tab character when the
CLI displays information.
Permitted Values:
THREADS(pid)
true or false
true
WGROUP(pid) - TV::auto_array_cast_bounds
INFO
Prints errors, warnings, and informational messages.
Informational messages include data on dynamic
libraries and symbols.
WARNING
Only print errors and warnings.
ERROR
Only print error messages.
SILENT
Does not print error, warning, and informational messages. This also shuts off the printing of results from
CLI commands. This should only be used when the CLI
is run in batch mode.
Permitted Values:
Default:
WGROUP(pid)
The group ID of the thread group of worker threads associated with the
process pid. This variable is read-only.
Permitted Values:
Default:
WGROUP(pid.tid)
INFO, WARNING, ERROR, and SILENT
INFO
A number
None
Contains one of the following:
■
■
The group ID of the workers group in which thread pid.tid is a member
0 (zero), which indicates that thread pid.tid is not a worker thread
Storing a nonzero value in this variable marks a thread as a worker. In this
case, the returned value is the ID of the workers group associated with the
control group, regardless of the actual nonzero value that you had
assigned to it.
Permitted Values:
Default:
A number representing the pid.tid
None
TV:: Namespace _______________________
TV::ask_on_dlopen
Setting this variable to true tells TotalView that it should ask you about
stopping processes that use the dlopen or load (AIX only) system calls
dynamically load a new shared library.
If this is set to false, TotalView will not ask about stopping a process that
dynamically loads a shared library.
Permitted Values:
Default:
TV::auto_array_cast_
bounds
Indicates the number of array elements that are displayed when the
TV::auto_array_cast_enabled variable is set to true. This is the variable set
by the Bounds field of the Pointer Dive Page in the File > Preferences Dialog
Box.
Permitted Values:
Default:
160
true or false
true
An array specification
[10]
Chapter 4: TotalView Variables
TV::auto_array_cast_enabled - TV::auto_deref_initial_c
TV::auto_array_cast_
enabled
When this is set to true, TotalView will automatically dereference a pointer
into an array. The number of array elements is indicated in the TV::auto_
array_cast_bounds variable. This is the variable set by the Cast dereferenced C pointers to array string checkbox of the Pointer Dive Page in the
File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_deref_in_
all_c
true or false
false
Tells TotalView if and how it should dereference C and C++ pointers when
you perform a View > Dive in All operation, as follows:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value
when performing a Dive in All operation.
yes
You will be able to use the Back control to see undereferenced values.
no
Do not automatically dereference values when performing a Dive in All operation.
This is the variable set when you select the “Dive in All” element in the
Pointer Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_deref_in_
all_fortran
no, yes, or yes_dont_push
no
Tells TotalView if and how it should dereference Fortran pointers when you
perform a Dive in All operation, as follows:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value
when performing a Dive in All operation.
yes
You will be able to use the Back control to see undereference values.
no
Do not automatically dereference values when performing a Dive in All operation.
This is the variable set when you select the Dive in All element in the
Pointer Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
Tells TotalView if and how it should dereference C pointers when they are
displayed, as follows:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value.
yes
You will be able to use the Back control to see undeferenced values.
no
Do not automatically dereference values.
TotalView Reference Guide: version 6.3.1
161
4. Variables
TV::auto_deref_
initial_c
no, yes, or yes_dont_push
no
TV::auto_deref_initial_fortran - TV::auto_load_breakpoints
This is the variable set when you select the initially element in the Pointer
Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_deref_
initial_fortran
no, yes, or yes_dont_push
no
Tells TotalView if and how it should dereference Fortran pointers when they
are displayed, as follows:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value.
yes
You will be able to use the Back control to see undeferenced values.
no
Do not automatically dereference values.
This is the variable set when you select the initially element in the Pointer
Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_deref_
nested_c
no, yes, or yes_dont_push
no
Tells TotalView if and how it should dereference C pointers when you dive
on structure elements:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value.
yes
You will be able to use the Back control to see undeferenced values.
no
Do not automatically dereference values.
This is the variable set when you select the from an aggregate element in
the Pointer Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_deref_
nested_fortran
no, yes, or yes_dont_push
yes_dont_push
Tells TotalView if and how it should dereference Fortran pointers when they
are displayed, as follows:
yes_dont_push
While automatic dereferencing will occur, you can’t use
the Back command to see the undereferenced value.
yes
You will be able to use the Back control to see undeferenced values.
no
Do not automatically dereference values.
This is the variable set when you select the from an aggregate element in
the Pointer Dive Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::auto_load_
breakpoints
162
no, yes, or yes_dont_push
yes_dont_push
Setting this variable to true tells TotalView that it should automatically load
action points from the file named filename.TVD.v3breakpoints where filename is the name of the file being debugged. If the variable is set to false,
TotalView does not automatically load your breakpoints. If you set this to
Chapter 4: TotalView Variables
TV::auto_read_symbol_at_stop - TV::barrier_stop_when_done
false, you can still load breakpoints if you use the Action Point > Load All
or the dactions -load command.
Permitted Values:
Default:
TV::auto_read_
symbol_at_stop
Setting this variable to false tells TotalView that it should not automatically
read symbols if execution stops when the program counter is in a library
whose symbols were not read. Setting it to true tells TotalView that it
should read in loader and debugging symbols. You would set it to false if
you have prevented symbol reading using either the TV::dll_loader_
symbols_only or TV::dll_read_no_symbols variables (or the preference
within the GUI) and reading these symbols is both unnecessary and would
affect performance.
Permitted Values:
Default:
TV::auto_save_
breakpoints
true or false
true
true or false
true
Setting this variable to true tells TotalView that it should automatically write
information about breakpoints to a file named filename.TVD.v3breakpoints
where filename is the name of the file being debugged. Information about
watchpoints is not saved.
TotalView writes this information when you exit from TotalView. If this variable is set to false, you can explicitly save this information by using the
Action Point > Save All or the dactions –save command.
Permitted Values:
Default:
TV::barrier_stop_all
true or false
false
Contains the value for the “stop_all” property for newly created action
points. This property tells TotalView what else it should stop when a thread
encounters this action point. You can also set this value using the –stop_all
command-line option or the When barrier hit, stop value in the Action
Points Page of the File > Preferences Dialog Box. The values that you can
use are as follows:
group
TotalView will stop all processes in a thread’s control
group when a thread reaches a barrier created using
this as a default.
process
TotalView will stop the process in which the thread is
running when a thread reaches a barrier created using
this default.
TotalView just stops the thread that hit a barrier created using this default.
This variable is the same as the BARRIER_STOP_ALL variable.
Permitted Values:
Default:
TV::barrier_stop_
when_done
group, process, or thread
group
Contains the value for the “stop_when_done” property for newly created
action points. This property tells TotalView what else it should stop when a
barrier point is satisfied. You can also set this value if you use the –stop_
TotalView Reference Guide: version 6.3.1
163
4. Variables
none
TV::bulk_launch_base_timeout - TV::bulk_launch_tmpfile1_header_line
when_done command-line option or the When barrier done, stop value in
the Action Points Page of the File > Preferences Dialog Box. The values you
can use are as follows:
group
When a barrier is satisfied, TotalView stops all processes in the control group.
process
When a barrier is satisfied, TotalView stops the processes in the satisfaction set.
none
TotalView only stops the threads in the satisfaction set;
other threads are not affected. For process barriers,
there is no difference between process and none.
In all cases, TotalView releases the satisfaction set when the barrier is satisfied.
This variable is the same as the BARRIER_STOP_WHEN_DONE variable.
Permitted Values:
Default:
TV::bulk_launch_
base_timeout
Defines the base timeout period used when TotalView executes a bulk
server launch.
Permitted Values:
Default:
TV::bulk_launch_
enabled
A string, usually contained within braces {}
The default value depends upon the platform—use the
dset command to see what this default is
Defines the header line used in the first temporary file when TotalView does
a bulk server launch operation. For information on this launch string, see
“Replacement Characters” on page 202.
Permitted Values:
Default:
164
A number from 1 to 3600 (1 hour)
10
Defines the command that will be used to launch the TotalView Debugger
Server (tvdsvr) when remote processes are created. For information on this
launch string, see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::bulk_launch_
tmpfile1_header_
line
true or false
false
Defines the incremental timeout period that TotalView waits for process to
launch when it automatically launches the TotalView Debugger Server
(tvdsvr) using the bulk server feature.
Permitted Values:
Default:
TV::bulk_launch_
string
A number from 1 to 3600 (1 hour)
20
When this is set to true, tells TotalView that it should use its bulk launch
features when it automatically launches the TotalView Debugger Server
(tvdsvr) for remote processes.
Permitted Values:
Default:
TV::bulk_launch_
incr_timeout
group, process, or thread
group
A string
None
Chapter 4: TotalView Variables
TV::bulk_launch_tmpfile1_host_lines - TV::comline_path_area_length
TV::bulk_launch_
tmpfile1_host_
lines
Defines the host line used in the first temporary file when TotalView performs a bulk server launch operation. For information on this launch string,
see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::bulk_launch_
tmpfile1_trailer_
line
A string
None
true or false
true
Allocates the patch space dynamically at the given address. See “Allocating
Patch Space for Compiled Expressions” in Chapter 14 of the TotalView Users Guide.
Default:
A hexadecimal value indicating space accessible to
TotalView
0xffffffffffffffff
Sets the length of the dynamically allocated patch space to the specified
length. See “Allocating Patch Space for Compiled Expressions” in Chapter 14 of the
TotalView Users Guide.
Permitted Values:
Default:
TotalView Reference Guide: version 6.3.1
A positive number
0
165
4. Variables
Permitted Values:
TV::comline_path_
area_length
{tvdsvr –working_directory %D –callback %L –set_pw
%P
-verbosity %V}
When set to true, TotalView uses C type string extensions when it displays
character arrays. When false, TotalView uses its string type extensions.
Permitted Values:
Default:
TV::comline_patch_
area_base
A string
Defines the trailer line used in the second temporary file when TotalView
does a bulk server launch operation. For information on this launch string,
see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::c_type_strings
A string
None
Defines the host line used in the second temporary file when TotalView
does a bulk server launch operation.For information on this launch string,
see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::bulk_launch_
tmpfile2_trailer_
line
A string
None
Defines the header line used in the second temporary file when TotalView
performs a bulk server launch operation. For information on this launch
string, see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::bulk_launch_
tmpfile2_host_
lines
%R
Defines the trailer line used in the first temporary file when TotalView performs a bulk server launch operation. For information on this launch string,
see “Replacement Characters” on page 202.
Permitted Values:
Default:
TV::bulk_launch_
tmpfile2_header_
line
A string
TV::command_editing - TV::compiler_vars
TV::command_
editing
Enables some Emacs-like commands that you can use while editing text in
the CLI. These editing commands are always available in the CLI window of
TotalView GUI. However, they are only available within the stand-alone CLI
if the terminal in which you are running it supports cursor positioning and
clear-to-end-of-line. The commands that you can use are:
^A: Moves the cursor to the beginning of the line.
^B: Moves the cursor one character backward.
^D: Deletes the character to the right of cursor.
^E: Moves the cursor to the end of the line.
^F: Moves the cursor one character forward.
^K: Deletes all text to the end of line.
^N: Retrieves the next entered command (only works after ^P).
^P: Retrieves the previously entered command.
^R or ^L: Redraws the line.
^U: Deletes all text from the cursor to the beginning of the line.
Rubout or Backspace: Deletes the character to the left of the cursor.
Permitted Values:
Default:
TV::compile_
expressions
true or false
false
When this variable is set to true, TotalView enables compiled expressions. If
this is set to false, TotalView interprets your expression.
If you are running on an IBM AIX system, you can use the -use_aix_fast_trap
command line option to speed up the performance of compiled expressions. Check the TotalView Release Notes to determine if your version of the
operating system supports this feature.
Permitted Values:
Default:
TV::compiler_vars
true or false
HP Alpha and IBM AIX: true
SGI IRIX: false
Not settable on other platforms
(HP Alpha, HP, and SGI only) When this is set to true, TotalView shows variables created by your Fortran compiler as well as the variables in your program. When set to false (which is the default), TotalView does not show the
variables created by your compiler.
Some Fortran compilers (HP f90/f77, SGI 7.2 compilers) write debugging
information that describes variables that the compiler created to assist in
some operations. For example, it could create a variable used to pass the
length of character*(*) variables. You might want to set this variable to true
if you are looking for a corrupted runtime descriptor.
You can override the value set to this variable in a startup file by using the
following command-line options:
–compiler_vars:
sets this variable to true
–no_compiler_vars:
166
sets this variable to false
Chapter 4: TotalView Variables
TV::copyright_string - TV::data_format_double
Permitted Values:
Default:
true or false
false
TV::copyright_string
This is a read-only string containing the copyright information displayed
when you start the CLI and TotalView.
TV::current_cplus_
demangler
Setting this variable overrides the C++ demangler that TotalView uses.
TotalView will ignore what you set the value of this variable to unless you
also set the value of the TV::force_default_cplus_demangler variable. You
can set this variable to the following values:
■
■
■
■
■
■
■
■
■
■
■
■
■
■
compaq: HP cxx on running Linux-Alpha
dec: HP Tru64 C++
gnu: GNU C++ on Linux Alpha
gnu_dot: GNU C++ Linux x86
gnu_v3: GNU C++ Linux x86
hp: HP aCC compiler
irix: SGI IRIX C++
kai: KAI C++
kai3_n: KAI C++ version 3.n
kai_4_0: KAI C++
spro: SunPro C++ 4.0 or 5.2
spro5: SunPro C++ 5.0 or later
sun: Sun CFRONT C++
xlc: IBM XLC/VAC++ compilers
Permitted Values:
Default:
TV::current_fortran_
demangler
Setting this variable overrides the Fortran demangler that TotalView uses.
TotalView will ignore what you set the value of this variable to unless you
also set the value of the TV::force_default_f9x_demangler variable. You can
set this variable to the following values:
■
■
■
■
■
■
■
■
xlf90: IBM Fortran
dec: HP Tru64 Fortran
decf90: HP Tru64 Fortran 90
fujitsu_f9x: Fujitsu Fortran 9x
hpux11_64_f9x: HP Fortran 9x
intel: Intel Fortran 9x
mipspro_f9x: SGI IRIX Fortran
sunpro_f9x_4: Sun ProFortran 4
sunpro_f9x_5: Sun ProFortran 5
Permitted Values:
Default:
A string naming the compiler
Derived from your platform and information within
your program
Defines the format TotalView uses when displaying double-precision values. This is one of a series of variables that define how TotalView displays
data. The format of each is similar and is as follows:
TotalView Reference Guide: version 6.3.1
167
4. Variables
■
TV::data_format_
double
A string naming the compiler
Derived from your platform and information within
your program
TV::data_format_double - TV::data_format_double
{presentation format-1 format-2 format 3}
presentation
auto
dec
dechex
hex
hexdec
oct
sci
format
%
width
Selects which format TotalView uses when displaying
information. Note that you can display floating point
information using dec, hex, and oct formats. You can
display integers using auto, dec, and sci formats.
Equivalent to the C language’s printf() function’s %g
specifier. You can use this with integer and floatingpoint numbers. This format will either be hexdec or
dechex, depending upon the programming language
being used.
Equivalent to the printf() function’s %d specifier. You
can use this with integer and floating-point numbers.
Displays information using the dec and hex formats.
You can use this with integers.
Equivalent to the printf() function’s %x specifier. You
can use this with integer and floating-point numbers.
Displays information using the hex and dec formats.
You can use this with integer numbers.
Equivalent to the printf() function’s %o specifier. You
can use this with integer and floating-point numbers.
Equivalent to the printf() function’s %e specifier. You
can use this with floating-point numbers.
For integers, format-1 defines the decimal format, format-2 defines the hexadecimal format, and format-3
defines the octal format.
For floating point numbers, format-1 defines the fixed
point display format, format-2 defines the scientific format, and format-3 defines the auto (printf()’s %g) format.
The format string is a combination of the following
specifiers:
A signal indicating the beginning of a format.
A positive integer. This is the same width specifier that
is used in the printf() function.
. (period) A punctuation mark separating the width from the pre-
cision.
precision
A positive integer. This is the same precision specifier
that is used in the printf() function.
# (pound) Tells TotalView to display a 0x prefix for hexadecimal
and 0 for octal formats. This isn’t used within floatingpoint formats.
0 (zero)
Tells TotalView to pad a value with zeros. This is ignored
if the number is left-justified. If you omit this character,
TotalView pads the value with spaces.
– (hyphen) Tells TotalView to left-justify the value within the field’s
width.
168
Chapter 4: TotalView Variables
TV::data_format_ext - TV::dbfork
Permitted Values:
Default:
TV::data_format_ext
Defines the format TotalView uses when displaying extended floating point
values such as long doubles.For a description of the contents of this variable, see TV::data_format_double.
Permitted Values:
Default:
TV::data_format_
int16
A value in the described format
{auto %1.1 %#10.8 %#12.11}
A value in the described format
{auto %1.1 %#18.16 %#23.22}
Defines the format TotalView uses when displaying 8-bit integer values. For
a description of the contents of this variable, see TV::data_format_double.
Permitted Values:
Default:
TV::data_format_
single
{auto %1.1 %#6.4 %#7.6}
Defines the format TotalView uses when displaying 64-bit integer values.
For a description of the contents of this variable, see TV::data_format_double.
Permitted Values:
Default:
TV::data_format_int8
A value in the described format
Defines the format TotalView uses when displaying 32-bit integer values.
For a description of the contents of this variable, see TV::data_format_double.
Permitted Values:
Default:
TV::data_format_
int64
A value in the described format
{auto %-1.15 %-1.15 %-1.15}
Defines the format TotalView uses when displaying 16-bit integer values.
For a description of the contents of this variable, see TV::data_format_double.
Permitted Values:
Default:
TV::data_format_
int32
A value in the described format
{auto %-1.15 %-1.15 %-20.2}
A value in the described format
{auto %1.1 %#4.2 %#4.3}
Defines the format TotalView uses when displaying single precision, floating-point values. For a description of the contents of this variable, see
TV::data_format_double.
Permitted Values:
Default:
A value in the described format
{auto %-1.6 %-1.6 %-1.6}
Defines the maximum number of characters displayed for a string.
TV::dbfork
When this variable is set to true, TotalView catches the fork(), vfork(), and
execve() system calls if your executable is linked with the dbfork library.
Permitted Values:
Default:
Permitted Values:
Default:
TotalView Reference Guide: version 6.3.1
A positive integer number
100
true or false
true
169
4. Variables
TV::data_format_
stringlen
TV::display_assembler_symbolically - TV::dll_read_loader_symbols_only
TV::display_
assembler_
symbolically
When this variable is set to true, TotalView displays assembler locations as
label+offset. When it is set to false, these locations are displayed as hexadecimal addresses.
Permitted Values:
Default:
TV::dll_ignore_prefix
Defines a list of library files for which you are not asked to stop the process
when it is loaded. This list contains a colon-separated list of prefixes. Also,
TotalView will not ask if you would like to stop a process if:
■
■
■
TV::dll_read_all_
symbols
true or false
false
You also set the TV::ask_on_dlopen variable to true.
The suffix of the library being loaded does not match a suffix contained in
the TV::dll_stop_suffix variable.
One or more of the prefixes in this list match the name of the library being loaded.
Permitted Values:
A list of path names, each item of which is separated
from another by a colon
Default:
/lib/:/usr/lib/:/usr/lpp/:/usr/ccs/lib/:/usr/dt/lib/:/tmp/
TotalView will always read loader and debugging symbols of libraries named
within this variable.
This variable is set to a colon-separated list of library names. A name can
contain the * (asterisk) and ? (question mark) wildcard characters, which
have their usual meaning:
*: zero or more characters.
■ ?: a single character.
■
As this is TotalView’s default behavior, only include library names here that
would be excluded because they are selected by a wildcard match within
the TV:dll_read_loader_symbols_only and TV::dll_read_no_symbols variables.
Permitted Values:
Default:
TV::dll_read_loader_
symbols_only
One or more library names separated by colons
None
When TotalView loads libraries named in this variable, it only reads loader
symbols. Because TotalView checks and processes the names in TV::dll_
read_all_symbols list before it processes this list, it will ignore names that
are in that list and in this one.
This variable is set to a colon-separated list of strings. Any string can contain the * (asterisk) and ? (question mark) wildcard characters, which have
their usual meaning:
*: zero or more characters.
■ ?: a single character.
■
If you are not interested in debugging most of your shared libraries, set this
variable to * and then put the names of any libraries you wish to debug on
the TV::dll_read_all_symbols list.
Permitted Values:
Default:
170
One or more library names separated by colons
None
Chapter 4: TotalView Variables
TV::dll_read_no_symbols - TV::dump_core
TV::dll_read_no_
symbols
When TotalView loads libraries named in this variable, it will not read in
either loader or debugging symbols. Because TotalView checks and processes the names in the TV::dll_read_loader_symbols_only lists before it
processes this list, it will ignore names that are in those lists and in this
one.
This variable is set to a colon-separated list of strings. Any string can contain the * (asterisk) and ? (question mark) wildcard characters having their
usual meaning:
*, which means zero or more characters
■ ?, which means a single character.
■
Because information about subroutines, variables, and file names will not
be known for these libraries, stack backtraces may be truncated. However,
if your program uses large shared libraries and it’s time consuming to read
even their loader symbols, you may want to put those libraries on this list.
Permitted Values:
Default:
TV::dll_stop_suffix
One or more library names separated by colons
None
Contains a colon-separated list of suffixes that tell TotalView that it should
stop the current process when it loads a library file having this suffix.
TotalVIew will ask you if you would like to stop the process:
■
■
If TV::ask_on_dlopen variable is set to true
If one or more of the suffixes in this list match the name of the library being loaded.
Permitted Values:
Default:
TV::dpvm
When this is set to true, TotalView enables support for debugging HP Tru64
UNIX Parallel Virtual Machine applications. This value can only be set in a
startup script. You can override this variable’s value by using the following
command-line options switches:
–dpvm
sets this variable to true
–no_dpvm
sets this variable to false
Permitted Values:
Default:
TV::dump_core
A Tcl list of suffixes
None
true or false
false
–dump_core
sets this variable to true
–no_dumpcore sets
Permitted Values:
Default:
TotalView Reference Guide: version 6.3.1
this variable to false
true or false
false
171
4. Variables
When this is set to true, TotalView will create a core file when an internal
TotalView error occurs. This is only used when debugging TotalView problems. You can override this variable’s value by using the following command-line options:
TV::dynamic - TV::global_typenames
TV::dynamic
When this is set to true, TotalView loads symbols from shared libraries. This
variable is available on all platforms supported by Etnus. (This may not be
true for platforms ported by others. For example, this feature is not available for Hitachi computers.) Setting this value to false can cause the dbfork
library to fail because TotalView might not find the fork(), vfork(), and
execve() system calls.
Permitted Values:
Default:
TV::editor_launch_
string
true or false
true
Defines the editor launch string command. The launch string substitution
characters you can use are:
%E: The editor
%F: The display font
%N: The line number
%S: The source file
TV::force_default_
cplus_demangler
Permitted Values:
Any string value—as this is a Tcl variable, you’ll need
to enclose the string within {} (braces) if the string
contains spaces
Default:
{xterm –e %E +%N %S}
When this is set to true, TotalView uses the demangler set in the
TV::current_cplus_demangler variable. You would set this variable when
TotalView uses the wrong demangler. TotalView can use the wrong demangler if you are using an unsupported compiler, and unsupported language
preprocessor, or if your vendor has made changes to your compiler.
Permitted Values:
Default:
TV::force_default_
f9x_demangler
When this is set to true, TotalView uses the demangler set in the
TV::current_fortran_demangler variable. You would set this variable when
TotalView uses the wrong demangler. TotalView can use the wrong demangler if you are using an unsupported compiler, and unsupported language
preprocessor, or if your vendor has made changes to your compiler.
Permitted Values:
Default:
TV::global_
typenames
true or false
false
true or false
false
When this is set to true, TotalView assumes that type names are globally
unique within a program and that all type definitions with the same name
are identical. This must be true for standard-conforming C++ compilers.
If you set this option to true, TotalView attempts to replace an opaque type
(struct foo *p;) declared in one module with an identically named defined
type (struct foo { … };) in a different module.
If TotalView has read the symbols for the module containing the nonopaque type definition, it will automatically display the variable by using
the non-opaque type definition when displaying variables declared with the
opaque type.
172
Chapter 4: TotalView Variables
TV::ignore_control_c - TV::kcc_classes
If you set this variable to false, TotalView does not assume that type names
are globally unique within a program. Only use this variable if your code has
different definitions of the same named type since TotalView can pick the
wrong definition when it substitutes for an opaque type in this case.
Permitted Values:
Default:
TV::ignore_control_c
When this is set to true, TotalView ignores Ctrl+C characters. This prevents
you from inadvertently terminating the TotalView process. You would set
this option to false when your program catches the Ctrl+C (SIGINT) signal.
Permitted Values:
Default:
TV::image_load_
callbacks
true or false
true
true or false
false
Contains a Tcl list of procedures names. TotalView invokes the procedures
named in this list whenever it loads a new image. This could occur when:
■
■
■
A user invokes a command such as dload.
TotalView resolves dynamic library dependencies.
User code uses dlopen() to load a new image.
TotalView invokes the functions in order, beginning at the first function in
this list.
Permitted Values:
Default:
TV::in_setup
Contains a true value if called while TotalView is being initialized. Your procedures would read the value of this variable so that code can be conditionally executed based on whether TotalView is being initialized. In most
cases, this is used for code that should only be invoked while TotalView is
being initialized. This is a read-only variable.
Permitted Values:
Default:
TV::kcc_classes
A Tcl list of procedure names
TV::propagate_prototypes
true or false
false
When this is set to true, TotalView converts structure definitions created by
the KCC compiler into classes that show base classes and virtual base
classes in the same way as other C++ compilers. When this is set to false,
TotalView does not perform this conversion. In this case, TotalView displays
virtual bases as pointers rather than as the data.
TotalView Reference Guide: version 6.3.1
173
4. Variables
TotalView converts structure definitions by matching the names given to
structure members. This means that TotalView may not convert definitions
correctly if your structure component names look like KCC processed
classes. However, TotalView never converts these definitions unless it
believes that the code was compiled with KCC. (It does this when it sees
one of the tag strings that KCC outputs, or when you use the KCC name
demangler.) Because all of the recognized structure component names
start with “_ _” and the C standard forbids this use, your code should not
contain names with this prefix.
TV::kernel_launch_string - TV::message_queue
Under some circumstances, TotalView may not be able to convert the original type names because type definition are not available. For example, it
may not be able to convert “struct __SO_foo” to “struct foo”. In this case,
TotalView shows the “__SO_foo” type. This is only a cosmetic problem. (The
“__SO__” prefix denotes a type definition for the nonvirtual components of
a class with virtual bases).
Since KCC output does not contain information on the accessibility of base
classes (private, protected, or public), TotalView cannot provide this information.
Permitted Values:
Default:
true or false
true
TV::kernel_launch_
string
This is not currently used.
TV::library_cache_
directory
Specifies the directory into which TotalView writes library cache data.
TV::local_interface
Permitted Values:
Default:
TV::message_queue
A file or path name to the local server
tvdsvr
(Sun only) If TotalView will not be using the server contained in the same
working directory as the TotalView executable, the contents of this string
indicate the shell command that TotalView uses to launch this alternate
server. For information on this launch string, see “Replacement Characters” on
page 202.
Permitted Values:
A string enclosed with {} (braces) if it has embedded
spaces
Default:
{%M –working_directory %D –local %U –set_pw %P
-verbosity %V}
When this is set to true, TotalView displays MPI message queues when you
are debugging an MPI program. When the variable is set to false, these
queues are not displayed. You would disable these queues if something is
overwriting the message queues, thereby confusing TotalView.
Permitted Values:
Default:
174
A string
{}
(Sun only) By default, TotalView finds the local server in the same place as
the remote server. On Sun platforms, TotalView can launch a 32- and 64-bit
version. This variable tells TotalView which local server it should launch.
Permitted Values:
Default:
TV::local_server_
launch_string
$USERNAME/.totalview/lib_cache
Sets the interface name that the server uses when it makes a callback. For
example, on an IBM PS2 machine, you would set this to css0. However, you
can use any legal inet interface name. (You can obtain a list of the interfaces if you use the netstat -i command.)
Permitted Values:
Default:
TV::local_server
A string indicating a path
true or false
true
Chapter 4: TotalView Variables
TV::nptl_threads - TV::platform
TV::nptl_threads
When set to auto, TotalView determines which threads package your program is using. Setting this variable to true tells TotalView that it is using
NPTL threads. false means that the program isn’t using this package.
Permitted Values:
Default:
TV::open_cli_
window_callback
true, false, or auto
auto
The CLI executes the string that is this variable’s value after you open the
CLI by selecting the Tools > Command Line command. It is ignored when
you open the CLI from the command line. It is most commonly used to set
the terminal characteristics of the (pseudo) tty that the CLI is using, since
these are inherited from the tty on which TotalView was started. Therefore,
if you start TotalView from a shell running inside an Emacs buffer, the CLI
uses the raw terminal modes that Emacs is using. You can change your terminal mode by adding the following command to your .tvdrc file:
dset TV::open_cli_window_callback "stty sane"
Permitted Values:
Default:
TV::parallel
When this is set to true, you are enabling TotalView support for parallel program runtime libraries such as MPI, PE, and UPC. You might set this to false
if you need to debug a parallel program as if it were a single-process program.
Permitted Values:
Default:
TV::parallel_attach
A string representing a Tcl or CLI command
Null
true or false
true
Tells TotalView if it should automatically attach to processes. Your choices
are as follows:
yes: Attach to all started processes.
■ no: Do not attach to any started processes.
■ ask: Display a dialog box listing the processes to which TotalView can at■
tach, and let the user decide to which ones TotalView should attach.
Permitted Values:
Default:
TV::parallel_stop
yes, no, or ask
yes
Tells TotalView if it should automatically run processes when your program
launches them. Your choices are as follows:
yes: Stop the processes before they begin executing.
no: Do not interfere with the processes; that is, let them run.
■ ask: Display a question box asking if it should stop before executing.
■
■
TV::platform
yes, no, or ask
ask
Indicates the platform upon which you are running TotalView. This is a readonly variable.
Permitted Values:
TotalView Reference Guide: version 6.3.1
One of the following values: alpha, hpux11-hppa,
hpux11-ia64, irix6-mips, linux-ia64, linux-x86, linuxx86-64, linux-alpha, rs6000, and sun5
175
4. Variables
Permitted Values:
Default:
TV::process_load_callbacks - TV::server_launch_string
Default:
TV::process_load_
callbacks
Platform-specific
Names the procedures that TotalView runs immediately after it loads a program and just before it runs it. TotalView executes these procedures after it
invokes the procedures in the TV::image_load_callbacks list.
The procedures in this list are only called once even though your executable may use many programs and libraries.
Permitted Values:
Default:
A list of procedures
TV::source_process_startup. The default procedure
looks looks for a file with the same name as the newly
loaded process’s executable image that has a .tvd suffix appended to it. If it exists, TotalView executes the
commands contained within it. This function is passed
an argument that is the ID for the newly created prcess.
TV::pvm
When this is set to true, TotalView lets you debug the ORNL (Oak Ridge
National Laboratory) implementation of Parallel Virtual Machine (PVM)
applications. This variable can only be set in a start up script. However, you
can override this value by using the following command-line options:
–pvm
sets this variable to true
–no_pvm
sets this variable to false
Permitted Values:
Default:
TV::save_window_
pipe_or_filename
Names the file to which TotalView writes or pipes the contents of the current window or pane when you select the File > Save Pane command.
Permitted Values:
Default:
TV::search_case_
sensitive
176
true or false
false
When this is set to true, TotalView uses its single-process server launch
procedure when launching remote tvdsvr processes. When the variable is
set to false, tvdsvr is not automatically launched.
Permitted Values:
Default:
TV::server_launch_
string
A string naming a file or pipe
None, until something is saved. Afterward, the saved
string is the default.
When this is set to true, text searches only succeed if a string exists whose
case exactly matches what you enter in the Edit > Find Dialog Box. For
example, searching for Foo won’t find foo if this variable is set to true. It will
be found if this variable is set to false.
Permitted Values:
Default:
TV::server_launch_
enabled
true or false
false
true or false
true
Names the command string that TotalView uses to automatically launch the
TotalView Debugger Server (tvdsvr) when you start to debug a remote process. This command string is executed by /bin/sh. By default, TotalView
uses the rsh command to start the server, but you can use any other com-
Chapter 4: TotalView Variables
TV::server_launch_timeout - TV::signal_handling_mode
mand that can invoke tvdsvr on a remote host. If no command is available
for invoking a remote process, you can’t automatically launch the server;
therefore, you should set this variable to /bin/false. If you cannot automatically launch a server, you should also set the TV::server_launch_enabled
variable to false. For information on this launch string, see “Replacement
Characters” on page 202.
Permitted Values:
Default:
TV::server_launch_
timeout
{%C %R –n "%B/tvdsvr –working_directory %D
–callback %L –set_pw %P –verbosity %V %F"}
Specifies the number of seconds that TotalView waits to hear back from the
TotalView Debugger Server (tvdsvr) that it launches.
Permitted Values:
Default:
TV::share_action_
point
A string
An integer from 1 to 3600 (1 hour)
30
Indicates the scope in which TotalView places newly created action points.
In the CLI, this is the dbarrier, dbreak, and dwatch commands. If this Boolean value is true, newly created action point are shared across the group. If
it is false, a newly created action point is only active in the process in which
it is set.
As an alternative to setting this variable, you can select the Plant in share
group check box in the Action Points Page in the File > Preferences Dialog
Box. You can override this value in the GUI by using selecting the Plant in
share group checkbox in the Action Point > Properties Dialog Box.
Permitted Values:
Default:
TV::signal_handling_
mode
true or false
true
The list that you assign to this variable modifies the way in which TotalView
handles signals. This list consists of a list of signal_action descriptions, separated by spaces:
signal_action[signal_action] ...
A signal_action description consists of an action, an equal sign (=), and a
list of signals:
action=signal_list
An action can be one of the following: Error, Stop, Resend, or Discard.
A signal_list is a list of one or more signal specifiers, separated by commas:
signal_specifier[,signal_specifier] ...
The following rules apply when you are specifying an action_list:
■
If you specify an action for a signal in an action_list, TotalView changes the
default action for that signal.
TotalView Reference Guide: version 6.3.1
177
4. Variables
A signal_specifier can be a signal name (such as SIGSEGV), a signal number
(such as 11), or a star (*), which specifies all signals. We recommend using
the signal name rather than the number because number assignments vary
across UNIX versions.
TV::source_pane_tab_width - TV::stop_all
■
■
■
If you do not specify a signal in the action_list, TotalView does not change
its default action for the signal.
If you specify a signal that does not exist for the platform, TotalView ignores it.
If you specify an action for a signal twice, TotalView uses the last action
specified. In other words, TotalView applies the actions from left to right.
If you need to revert the settings for signal handling to TotalView’s built-in
defaults, use the Defaults button in the File > Signals Dialog Box.
For example, to set the default action for the SIGTERM signal to Resend, you
specify the following action list:
{Resend=SIGTERM}
As another example, to set the action for SIGSEGV and SIGBUS to Error, the
action for SIGHUP and SIGTERM to Resend, and all remaining signals to Stop,
you specify the following action list:
{Stop=* Error=SIGSEGV,SIGBUS Resend=SIGHUP,SIGTERM}
This action list shows how TotalView applies the actions from left to right.
1 Sets the action for all signals to Stop.
2 Changes the action for SIGSEGV and SIGBUS from Stop to Error.
3 Changes the action for SIGHUP and SIGTERM from Stop to Resend.
Permitted Values:
Default:
TV::source_pane_
tab_width
Sets the width of the tab character that is displayed in the Process Window’s Source Pane. You may want to set this value to the same value as
you use in your text editor.
Permitted Values:
Default:
TV::spell_correction
verbose, brief, or none
verbose
Indicates a default property for newly created action points. This property
tells TotalView what else it should stop when it encounters this action
point. The values you can set are as follows:
group
178
An integer
8
When you use the View > Lookup Function or View > Lookup Variable commands in the Process Window or edit a type string in a Variable Window, the
debugger checks the spelling of your entries. By default (verbose), the
debugger displays a dialog box before it corrects spelling. You can set this
resource to brief to run the spelling corrector silently. (TotalView makes the
spelling correction without displaying it in a dialog box first.) You can also
set this resource to none to disable the spelling corrector.
Permitted Values:
Default:
TV::stop_all
A list of signals, as was just described
This differs from platform to platform; type dset
TV::signal_handling_mode to see what a platform’s
default values are
Stops the entire control group when the action point is
hit.
Chapter 4: TotalView Variables
TV::stop_relatives_on_proc_error - TV::visualizer_launch_enabled
process
Stops the entire process when the action point is hit.
thread
Only stops the thread that hit the action point. Note
that none is a synonym for thread.
Permitted Values:
Default:
TV::stop_relatives_
on_proc_error
When this is set to true, TotalView stops the control group when an error
signal is raised. This is the variable used by the Stop control group on error
signal option in the Options Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::suffixes
true or false
true
true or false
true
Indicates the current TotalView version. This is a read-only variable.
A string
Varies from release to release
When this is set to true, TotalView automatically launches the Visualizer
when you first visualize something. If you set this variable to false,
TotalView disables visualization. This is most often used to stop evaluation
points containing a $visualize directive from invoking the Visualizer.
Permitted Values:
Default:
TotalView Reference Guide: version 6.3.1
true or false
true
179
4. Variables
Permitted Values:
Default:
TV::visualizer_
launch_enabled
{:c:include s:asm S:asm c:c h:c:include lex:c:include
y:c:include bmap:c:include f:f77 F:f77 f90:f9x F90:f9x
hpf:hpf HPF:hpf cxx:c++ cpp:c++ cc:c++ c++:c++
C:c++ C++:c++ hxx:c++:include hpp:c++:include
hh:c++:include h++:c++:include HXX:c++:include
HPP:c++:include HH:c++:include H:c++:include
ih:c++:include th:c++}
When this is set to true, it enables TotalView support for handling user-level
(M:N) thread packages on systems that support two-level (kernel and user)
thread scheduling.
Permitted Values:
Default:
TV::version
A list identifying how suffixes are used
When set to true, TotalView uses registered type transformations to change
the appearance of data types that have been registered using the TV::type_
transformation routine.
Permitted Values:
Default:
TV::user_threads
true or false
true
Use a space separated list of items to identify the contents of a file. Each
item on this list has the form: suffix:lang[:include]. You can set more than
suffix for an item. If you want to remove an item from the default list, set its
value to unknown.
Permitted Values:
Default:
TV::ttf
group, process, or thread
group
TV::visualizer_launch_string - TV::GUI::chase_mouse
TV::visualizer_
launch_string
Specifies the command string that TotalView uses when it launches a visualizer. Because the text is actually used as a shell command, you can use a
shell redirection command to write visualization datasets to a file (for
example, “cat > your_file”).
Permitted Values:
Default:
TV::visualizer_max_
rank
Specifies the default value used in the Maximum permissible rank field in
the Launch Strings Page of the File > Preferences Dialog Box. This field sets
the maximum rank of the array that TotalView will export to a visualizer. The
TotalView Visualizer cannot visualize arrays of rank greater than 2. If you are
using another visualizer or just dumping binary data, you can set this value
to a larger number.
Permitted Values:
Default:
TV::warn_step_throw
An integer
2
If this is set to true and your program throws an exception during a
TotalView single-step operation, TotalView asks if you wish to stop the step
operation. The process will be left stopped at the C++ run-time library’s
“throw” routine. If this is set to false, TotalView will not catch C++ exception throws during single-step operations. Setting it to false may mean that
TotalView will lose control of the process, and you may not be able to control the program.
Permitted Values:
Default:
TV::wrap_on_search
A string
visualize
true or false
true
When this is set to true, TotalView will continue searching from either the
beginning (if Down is also selected in the Edit > Find Dialog Box) or the end
(if Up is also selected) if it doesn’t find what you’re looking for. For example, you search for foo and select the Down button. If TotalView doesn’t
find it in the text between the current position and the end of the file,
TotalView will continue searching from the beginning of the file if you set
this option.
Permitted Values:
Default:
true or false
true
TV::GUI:: Namespace ___________________
The variables in this section only have meaning (and in some cases, a value) when your
are displaying TotalView’s GUI.
TV::GUI::chase_
mouse
When this variable is set to true, TotalView displays dialog boxes at the
location of the mouse cursor. If this is set to false, TotalView displays them
centered in the upper third of the screen.
Permitted Values:
Default:
180
true or false
true
Chapter 4: TotalView Variables
TV::GUI::display_font_dpi - TV::GUI::force_window_position
TV::GUI::display_
font_dpi
Indicates the video monitor DPI (dots per inch) at which fonts are displayed.
Permitted Values:
Default:
TV::GUI::enabled
An integer
75
When this is set to true, you invoked the CLI from the GUI or a startup
script. Otherwise, this read-only value is false.
Permitted Values:
Default:
true or false
true if you are running the GUI even though you are
seeing this in a CLI window; false if you are only running
the CLI
TV::GUI::fixed_font
Indicates the specific font TotalView uses when displaying program information such as source code in the Process Window or data in the Variable
Window. This variable contains the value set when you select a Code and
Data Font entry in the Fonts Page of the File > Preferences Dialog Box.
This is a read-only variable.
Permitted Values:
Default:
A string naming a fixed font residing on your system
While this is platform specific, here is a representative value:
-adobe-courier-medium-r-normal--12-120-75-75-m-70iso8859-1
TV::GUI::fixed_font_
family
Indicates the specific font TotalView uses when displaying program information such as source code in the Process Window or data in the Variable
Window. This variable contains the value set when you select a Code and
Data Font entry of the Fonts Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
TV::GUI::fixed_font_
size
A string representing an installed font family
fixed
Indicates the point size at which TotalView displays fixed font text. This is
only useful if you have set a fixed font family because if you set a fixed font,
the value entered contains the point size.
Font sizes are indicated using printer points.
Permitted Values:
Default:
TV::GUI::font
Default:
While this is platform specific, here is a representative
value:
-adobe-helvetica-medium-r-normal--12-120-75-75-p67-iso8859-1
helvetica
Setting this variable to true tells TotalView that it should use the version 4
window layout algorithm. This algorithm tells the window manager where to
TotalView Reference Guide: version 6.3.1
181
4. Variables
Indicates the specific font used when TotalView writes information as the
text in dialog boxes and in menu bars. This variable contains the information set when you select a Select by full name entry in the Fonts Page of the
File > Preferences Dialog Box.
Permitted Values:
TV::GUI::force_
window_position
An integer
12
TV::GUI::geometry_call_tree - TV::GUI::geometry_memory_stats
set the window. It also cascades windows from a base location for each
window type. If this is not set, which is the default, newer window managers
such as kwm or Enlightment can use their smart placement modes.
Dialog boxes still chase the pointer as needed and are unaffected by this
setting.
Permitted Values:
Default:
TV::GUI::geometry_
call_tree
true or false
false
Specifies the position at which TotalView displays the Tools > Call Tree Window. This position is set using a list containing four values: the window’s x
and y coordinates. These are followed by two more values specifying the
window’s width and height.
If you set any of these values to 0 (zero), TotalView uses its default value.
This means, however, you cannot tell TotalView to place a window at x, y
coordinates of 0, 0. Instead, you’ll need to place the window at 1, 1.
If you specify negative x and y coordinates, TotalView aligns the window to
the opposite edge of the screen.
TV::GUI::geometry_
cli
TV::GUI::geometry_
globals
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > CLI Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Program
Browser Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::geometry_
help
TV::GUI::geometry_
memory_stats
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Help Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Memory Statistics Window.
See TV::GUI::geometry_call_tree for information on setting this list.
182
Chapter 4: TotalView Variables
TV::GUI::geometry_message_queue - TV::GUI::geometry_pvm
TV::GUI::geometry_
message_queue
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinate’s and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Message
Queue Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::geometry_
message_queue_
graph
TV::GUI::geometry_
modules
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Message
Queue Graph Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Fortran Modules Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::geometry_
process
TV::GUI::geometry_
ptset
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height.
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Process Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > P/T Set Window.
TV::GUI::geometry_
pvm
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > PVM Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TotalView Reference Guide: version 6.3.1
183
4. Variables
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::geometry_root - TV::GUI::pop_at_breakpoint
TV::GUI::geometry_
root
TV::GUI::geometry_
thread_objects
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Root Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Thread
Objects Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::geometry_
variable
TV::GUI::geometry_
variable_stats
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Variable Window.
See TV::GUI::geometry_call_tree for information on setting this list.
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
Specifies the position at which TotalView displays the Tools > Statistics Window.
See TV::GUI::geometry_call_tree for information on setting this list.
TV::GUI::keep_
search_dialog
Permitted Values:
A list containing four integers indicating the window’s
x and y coordinates and the window’s width and
height
Default:
{0 0 0 0}
When this is set to true, TotalView doesn’t remove the Edit > Find Dialog
Box after you select that dialog box’s Find button. If you select this option,
you will need to select the Close button to dismiss the Edit > Find box.
Permitted Values:
Default:
TV::GUI::pop_at_
breakpoint
When this is set to true, TotalView sets the Open (or raise) process window
at breakpoint check box to be selected by default. If this variable is set to
false, it sets that check box to be deselected by default.
Permitted Values:
Default:
184
true or false
true
true or false
false
Chapter 4: TotalView Variables
TV::GUI::pop_on_error - TV::GUI::version
TV::GUI::pop_on_
error
When this is set to true, TotalView sets the Open process window on error
signal check box in the File > Preferences’s Option Page to be selected by
default. If you set this to false, TotalView sets that check box to be deselected by default.
Permitted Values:
Default:
TV::GUI::single_
click_dive_
enabled
When set, you can perform dive operations using the middle mouse button. Diving using a left-double-click still works. If you are editing a field,
clicking the middle mouse performs a paste operation.
Permitted Values:
Default:
TV::GUI::ui_font
Default:
While this is platform specific, here is a representative
value:
-adobe-helvetica-medium-r-normal--12-120-75-75-p67-iso8859-1
helvetica
Indicates the family of fonts that TotalView uses when displaying such
information as the text in dialog boxes and menu bars. This variable contains the information set when you select a Family in the Fonts Page of the
File > Preferences Dialog Box.
Permitted Values:
Default:
TV::GUI::ui_font_size
true or false
true
Indicates the specific font used when TotalView writes information as the
text in dialog boxes and in menu bars. This variable contains the information set when you select a Select by full name entry in the Fonts Page of the
File > Preferences Dialog Box.
Permitted Values:
TV::GUI::ui_font_
family
true or false
true
A string
helvetica
Indicates the point size at which TotalView writes the font used for displaying such information as the text in dialog boxes and menu bars. This variable contains the information set when you select a User Interface Size in
the Fonts Page of the File > Preferences Dialog Box.
Permitted Values:
Default:
An integer
12
Not implemented.
TV::GUI::using_text_
color
Not implemented.
TV::GUI::using_title_
color
Not implemented.
TV::GUI::version
This number indicates which version of the TotalView GUI is being displayed. This is a read-only variable.
Permitted Values:
TotalView Reference Guide: version 6.3.1
4. Variables
TV::GUI::using_color
A number
185
TV::GUI::version - TV::GUI::version
186
Chapter 4: TotalView Variables
Default Arena Widths
5
This chapter lists all CLI commands and their default arena widths.
Commands in the TV:: namespace and commands that are not
debugger related (for example, alias and help) are not shown as either
focus is not relevant or is obvious (for example, focus_groups).
Table 2: Default Arena
Widths
Command
Default Arena Width
dactions
process
dassign
thread; if the current width is “process”, dassign acts
on each thread in the process
dattach
—
dbarrier
Obtains focus width from the setting of the
SHARE_ACTION_POINT variable; if true, the default is
“group;” if false, the default is “process”
dbreak
Obtains focus width from the setting of the
SHARE_ACTION_POINT variable; if true, the default is
“group;” if false, the default is “process”
dcache
—
dcheckpoint
process
dcont
process
ddelete
process
ddetach
process
ddisable
process
ddown
thread; if the current width is “process,” ddown acts on
each thread in the process
denable
process
dflush
thread
dfocus
—
dgo
process
TotalView Reference Guide: version 6.3.1
187
188
Command
Default Arena Width
dgroups
The –list option ignores the focus; other options use
group width to find the groups being operated on and
thread width to find the operands
dhalt
process
dhold
depends on the –thread or –process option
dkill
process; note that killing the primary process for a
control group always kills all of its slaves
dlappend
—
dlist
thread; if the current width is “process,” dlist iterates
over all threads in the process
dload
—
dmstat
process
dnext
process
dnexti
process
dout
process
dprint
thread; if the current width is “process”, dprint acts on
each thread in the process
dptsets
—
drerun
process
drestart
—
drun
process
dset
—
dstatus
process
dstep
process
dstepi
process
dunhold
depends on the –thread or –process option
dunset
—
duntil
process
dup
thread; if the current width is “process, dup acts on
each thread in the process
dwait
process
dwatch
Obtains focus from the SHARE_ACTION_POINT
variable’s setting
true: default to group
false: default to process
dwhat
thread; if the current width is “process,” dwhat acts on
each thread in the process
dwhere
thread; if the current width is “process,” dwhere acts
on each thread in the process
dworker
thread
Chapter 5: Default Arena Widths
Part II: Running
TotalView
This section of the TotalView Reference Guide contains information about
command-line options you use when starting TotalView and the TotalView
Debugger Server.
Chapter 6: TotalView Command Syntax
TotalView contains a great number of command-line options. Many of these options allow you to override
TotalView’s default behavior or a behavior that you’ve set in
a preference or a startup file.
In previous releases, using options was the best way to set
TotalView’s behavior. Beginning with Release 6.0, you are
better served by setting a preference or a CLI variable.
Chapter 7: TotalView Debugger Server (tvdsvr) Command Syntax
This chapter describes how you modify the behavior of the
tvdsvr. These options are most often used if a problem occurs in launching the server or if you have some very specialized need. In most cases, you can ignore the information in
this chapter.
TotalView Reference Guide: version 6.3.1
189
190
TotalView Command
Syntax
6
This chapter describes the syntax of the totalview command. Topics
in this chapter are:
■
■
Syntax
Options
Syntax________________________________
Format:
Arguments:
Description:
totalview [ filename [ corefile ]] [ options ]
filename
Specifies the path name of the executable being
debugged. This can be an absolute or relative path
name. The executable must be compiled with debugging
symbols turned on, normally the –g compiler option.
Any multiprocess programs that call fork(), vfork(), or
execve() should be linked with the dbfork library.
corefile
Specifies the name of a core file. Use this argument in
addition to filename when you want to examine a core
file with TotalView.
The TotalView debugger is a source-level debugger with a motif-based
graphic user interface and features for debugging distributed programs,
multiprocess programs, and multithreaded programs. TotalView is available on a number of different platforms.
If you specify mutually exclusive options on the same command line (for
example, –dynamic and –no_dynamic), the last option listed is used.
Options
–a args
TotalView Reference Guide: version 6.3.1
Pass all subsequent arguments (specified by args) to the
program specified by filename. This option must be the
last one on the command line.
191
–background color / –demangler=compiler
–background color
Sets the general background color to color.
Default: light blue
–bg color
Same as –background.
–compiler_vars
(Alpha, HP, and SGI only.) Shows variables created by
the Fortran compiler, as well as those in the user’s program.
Some Fortran compilers (HP f90/f77, HP f90, SGI 7.2
compilers) output debugging information that describes
variables the compiler itself has invented for purposes
such as passing the length of character*(*) variables. By
default, TotalView suppresses the display of these compiler-generated variables.
However, you can specify the –compiler_vars option to
display these variables. This is useful when you are looking for a corruption of a run-time descriptor or are writing a compiler.
–no_compiler_vars
(Default) Tells TotalView that it should not show variables created by the Fortran compiler.
–dbfork
(Default) Catches the fork(), vfork(), and execve() system
calls if your executable is linked with the dbfork library.
–no_dbfork
Tells TotalView that it should not catch fork(), vfork(),
and execve() system calls even if your executable is
linked with the dbfork library.
–debug_file consoleoutputfile
Redirects TotalView console output to a file named consoleoutputfile.
Default: All TotalView console output is written to stderr.
–demangler=compiler
Overrides the demangler and mangler TotalView uses by
default. The following indicate override options.
–demangler=compaq HP cxx on Linux (alpha)
–demangler=dec HP Tru64 C++ or Fortran
–demangler=gnu GNU C++ on Linux Alpha
–demangler=gnu_dot GNU C++ on Linux x86
–demangler=gnu_v3GNU C++ Linux x86
–demangler=hp HP aCC compiler
–demangler=irix SGI IRIX C++
–demangler=kai KAI C++
–demangler=kai3_n KAI C++ version 3.n
–demangler=kai_4_0KAI C++
–demangler=spro SunPro C++ 4.0 or 4.2
192
Chapter 6: TotalView Command Syntax
–display displayname / –foreground color
–demangler=spro5 SunPro C++ 5.0 or later
–demangler=sun Sun CFRONT C++
–demangler=xlc IBM XLC/VAC++ compilers
–display displayname
Set the name of the X Windows display to displayname.
For example, –display vinnie:0.0 will display TotalView on
the machine named “vinnie.”
Default: The value of your DISPLAY environment variable.
–dll_ignore_prefix list
–dll_stop_suffix list
The colon-separated argument to this option tells
TotalView that if the library being opened has any of the
entries on this list as a suffix, it should ask if it should
open the library.
–dpvm
HP Tru64 UNIX only: Enable support for debugging the
HP Tru64 UNIX implementation of Parallel Virtual
Machine (PVM) applications.
–no_dpvm
HP Tru64 UNIX only: (Default) Disables support for
debugging the HP Tru64 UNIX implementation of PVM
applications.
–dump_core
Allows TotalView to dump a core file of itself when an
internal error occurs. This is used to help Etnus debug
TotalView problems.
–no_dumpcore
(Default) Does not allow TotalView to dump a core file
when it gets an internal error.
–e commands
Tells TotalView to immediately execute the CLI commands named within this argument. All information you
enter here is sent directly to the CLI’s Tcl interpreter. For
example, the following writes a string to stdout:
cli -e 'puts hello'
You can have more than one –e option on a command
line.
–foreground color
Sets the general foreground color (that is, the text color)
to color.
Default: black
–fg color
TotalView Reference Guide: version 6.3.1
Same as –foreground.
193
6. Command Syntax
The colon-separated argument to this option tells
TotalView that it should ignore files having this prefix
when making a decision to ask about stopping the process when it dlopens a dynamic library. If the DLL being
opened has any of the entries on this list as a prefix, the
question is not asked.
–f9x_demangler=compiler / –message_queue
–f9x_demangler=compiler
Overrides the Fortran demangler and mangler TotalView
uses by default. The following indicate override options.
–demangler=spro_f9x_4 SunPro Fortran, 4.0 or later
–demangler=xlf IBM Fortran
–global_types
(Default) Lets TotalView assume that type names are
globally unique within a program and that all type definitions with the same name are identical. In C++, the
standard asserts that this must be true for standardconforming code.
If this option is set, TotalView will attempt to replace an
opaque type (struct foo *p;) declared in one module,
with an identically named defined type in a different
module.
If TotalView has read the symbols for the module containing the non-opaque type definition, then when displaying variables declared with the opaque type,
TotalView will automatically display the variable by using
the non-opaque type definition.
–no_global_types
Specifies that TotalView cannot assume that type names
are globally unique in a program. You should specify this
option if your code has multiple different definitions of
the same named type, since otherwise TotalView can
use the wrong definition for an opaque type.
–kcc_classes
(Default) Converts structure definitions output by the
KCC compiler into classes that show base classes and
virtual base classes in the same way as other C++
compilers. See the description of the TV::kcc_classes
variable for a description of the conversions that
TotalView performs.
–no_kcc_classes
Specifies that TotalView will not convert structure definitions output by the KCC compiler into classes. Virtual
bases will show up as pointers, rather than as data.
–lb
(Default) Loads action points automatically from the filename.TVD.v3breakpoints file, providing the file exists.
–nlb
Tells TotalView that it should not automatically load
action points from an action points file.
–message_queue
(Default) Enables the display of MPI message queues
when debugging an MPI program.
–mqd
Same as –message_queue.
–no_message_queue
Disables the display of MPI message queues when you
are debugging an MPI program. This might be useful if
194
Chapter 6: TotalView Command Syntax
–nptl_threads / –remote hostname[:portnumber]
something is overwriting the message queues and causing TotalView to become confused.
–no_mqd
Same as –no_message_queue.
–nptl_threads
Tells TotalView that your application is using NPTL
threads. You only need use this option if default cannot
determine that you are using this threads package.
–no_nptl_threads
Tells TotalView that you are not using the NPTL threads
package. Use this option if TotalView thinks your application is using it and it isn’t.
–parallel
–no_parallel
Disables handling of parallel program run-time libraries
such as MPI, PE, and UPC. This is useful for debugging
parallel programs as if they were single-process programs.
–patch_area_base address
Allocates the patch space dynamically at the given
address. See “Allocating Patch Space for Compiled Expressions” in Chapter 14 of the TotalView Users Guide.
–patch_area_length length
Sets the length of the dynamically allocated patch
space to the specified length. See “Allocating Patch Space
for Compiled Expressions” in Chapter 14 of the TotalView
Users Guide.
–pid pid
Tells TotalView to attach to process pid after it starts
executing.
–pvm
Enables support for debugging the ORNL implementation of Parallel Virtual Machine (PVM) applications.
–no_pvm
(Default) Disables support for debugging the ORNL
implementation of PVM applications.
–remote hostname[:portnumber]
Debugs an executable that is not running on the same
machine as TotalView. For hostname, you can specify a
TCP/IP host name (such as vinnie) or a TCP/IP address
(such as 128.89.0.16). Optionally, you can specify a TCP/
IP port number for portnumber, such as :4174. When you
specify a port number, you disable the autolaunch feature. For more information on the autolaunch feature,
see “Setting Single Process Server Launch” in Chapter 14
of the TotalView Users Guide.
TotalView Reference Guide: version 6.3.1
195
6. Command Syntax
(Default) Enables handling of parallel program run-time
libraries such as MPI, PE, and UPC.
–s pathname / –signal_handling_mode “action_list”
–r hostname[:portnumber]
Same as –remote.
–s pathname
Specifies the path name of a startup file that will be
loaded and executed. This path name can be either an
absolute or relative name.
You can have more than one –s option on a command
line.
–serial device[:options]
Debugs an executable that is not running on the same
machine as TotalView. For device, specify the device name
of a serial line, such as /dev/com1. Currently, the only
option you are allowed to specify is the baud rate, which
defaults to 38400. For more information on debugging
over a serial line, see “Debugging Over a Serial Line” in
Chapter 4 of the TotalView Users Guide.
-search_path pathlist
Specify a colon-separated list of directories that
TotalView will search when it looks for source files. For
example:
totalview -search_path proj/bin:proj/util
–signal_handling_mode “action_list”
Modifies the way in which TotalView handles signals. You
must enclose the action_list string in quotation marks to
protect it from the shell.
An action_list consists of a list of signal_action descriptions separated by spaces:
signal_action[ signal_action] ...
A signal action description consists of an action, an
equal sign (=), and a list of signals:
action=signal_list
An action can be one of the following: Error, Stop,
Resend, or Discard, For more information on the meaning of each action, see Chapter 3 of the TotalView Users
Guide.
A signal_specifier can be a signal name (such as SIGSEGV),
a signal number (such as 11), or a star (*), which specifies all signals. We recommend that you use the signal
name rather than the number because number assignments vary across UNIX sessions.
The following rules apply when you are specifying an
action_list:
(1) If you specify an action for a signal in an action_list,
TotalView changes the default action for that signal.
(2) If you do not specify a signal in the action_list,
TotalView does not change its default action for the signal.
196
Chapter 6: TotalView Command Syntax
–shm “action_list” / –verbosity level
(3) If you specify a signal that does not exist for the platform, TotalView ignores it.
(4) If you specify an action for a signal more than once,
TotalView uses the last action specified.
If you need to revert the settings for signal handling to
TotalView’s built-in defaults, use the Defaults button in
the File > Signals dialog box.
For example, here’s how to set the default action for the
SIGTERM signal to resend:
“Resend=SIGTERM”
Here’s how to set the action for SIGSEGV and SIGBUS to
error, the action for SIGHUP to resend, and all remaining
signals to stop:
–shm “action_list”
Same as –signal_handling_mode.
-tvhome pathname
The directory from which TotalView reads preferences
and other related information and the directory to
which it writes this information.
-use_aix_fast_trap Tells TotalView that it support the AIX fast trap mecha-
nism. You must set this option on the command line as
there is no TotalView variable that can be set to perform
this action.
Your operating system may not be configured correctly
to support this option. See the TotalView Release Notes
for more information.
–user_threads
(Default) Enables handling of user-level (M:N) thread
packages on systems where two-level (kernel and user)
thread scheduling is supported.
–no_user_threads
Disables handling of user-level (M:N) thread packages.
This option may be useful in situations where you need
to debug kernel-level threads, but in most cases, this
option is of little use on systems where two-level thread
scheduling is used.
–verbosity level
Sets the verbosity level of TotalView-generated messages to level, which may be one of silent, error, warning,
or info.
Default: info
TotalView Reference Guide: version 6.3.1
197
6. Command Syntax
“Stop=* Error=SIGSEGV,SIGBUS Resend=SIGHUP”
–verbosity level / –verbosity level
198
Chapter 6: TotalView Command Syntax
TotalView Debugger
Server (tvdsvr)
Command Syntax
7
This chapter summarizes the syntax of the TotalView Debugger
Server command, tvdsvr, which is used for remote debugging. For
more information on remote debugging, refer to “Setting Up Remote
Debugging Sessions” in the TotalView Users Guide.
Topics in this chapter are:
■
■
The tvdsvr Command and Its Options
Replacement Characters
The tvdsvr Command and Its Options ____
Format:
tvdsvr {–server | –callback hostname:port | –serial device}
[other options]
Description:
The tvdsvr debugger server allows TotalView to control and debug a program on a remote machine. To accomplish this, the tvdsvr program must
run on the remote machine, and it must have access to the executables
being debugged. These executables must have the same absolute path
name as the executable that TotalView is debugging, or the PATH environment variable for tvdsvr must include the directories containing the executables.
You must specify a –server, –callback, or –serial option with the tvdsvr command. By default, TotalView automatically launches tvdsvr using the –callback option, and the server establishes a connection with TotalView. (Automatically launching the server is called autolaunching.)
If you prefer not to automatically launch the server, you can start tvdsvr
manually and specify the –server option. Be sure to note the password that
tvdsvr prints out with the message:
pw = hexnumhigh:hexnumlow
TotalView will prompt you for hexnumhigh:hexnumlow later. By default,
tvdsvr automatically generates a password that it uses when estabTotalView Reference Guide: version 6.3.1
199
–callback hostname:port / –port number
lishing connections. If desired, you can set your own password by
using the –set_pw option.
To connect to the tvdsvr from TotalView, you use the Fille > New Program
Dialog Box and must specify the host name and TCP/IP port number, hostname:portnumber on which tvdsvr is running. Then, TotalView prompts you
for the password for tvdsvr.
Options
The following options name the port numbers and passwords that
TotalView uses to connect with tvdsvr.
–callback hostname:port
(Autolaunch feature only) Immediately establishes a
connection with a TotalView process running on hostname and listening on port, where hostname is either a
host name or TCP/IP address. If tvdsvr cannot connect
with TotalView, it exits.
If you use the –port, –search_port, or –server options
with this option, tvdsvr ignores them.
–callback_host hostname
Names the host upon which the callback is made. The
hostname argument indicates the machine upon which
TotalView is running. This option is most often used with
a bulk launch.
–callback_ports port-list
Names the ports on the host machines that are used for
callbacks. The port-list argument contains a comma-separated list of the host names and TCP/IP port numbers
(hostname:port,hostname:port...) on which TotalView is listening for connections from tvdsvr. This option is most
often used with a bulk launch.
For more information, see Chapter 4, “Setting Up Remote
Debugging Sessions” in the TotalView Users Guide.
–debug_file console_outputfile
Redirects TotalView Debugger Server console output to
a file named console_outputfile.
Default: All console output is written to stderr.
–dpvm
Uses the HP Tru64 UNIX implementation of the Parallel
Virtual Machine (DPVM) library process as its input
channel and registers itself as the DPVM tasker.
This option is not intended for users launching tvdsvr
manually. When you enable DPVM support within
TotalView, TotalView automatically uses this option
when it launches tvdsvr.
–port number
200
Sets the TCP/IP port number on which tvdsvr should
communicate with TotalView. If this port is busy, tvdsvr
does not select an alternate port number (that is, it
Chapter 7: TotalView Debugger Server
–pvm / –set_pw hexnumhigh:hexnumlow
won’t communicates with anything) unless you also
specify –search_port.
Default: 4142
–pvm
Uses the ORNL implementation of the Parallel Virtual
Machine (PVM) library process as its input channel and
registers itself as the ORNL PVM tasker.
This option is not intended for users launching tvdsvr
manually. When you enable PVM support within
TotalView, TotalView automatically uses this option
when it launches tvdsvr.
–search_port
Searches for an available TCP/IP port number, beginning with the default port (4142) or the port set with the
–port option and continuing until one is found. When
the port number is set, tvdsvr displays the chosen port
number with the following message:
port = number
Be sure that you remember this port number, since you
will need it when you are connecting to this server from
TotalView.
–serial device[:options]
–server
Listens for and accepts network connections on port
4142 (default).
Using –server can be a security problem. Consequently,
you must explicitly enable this feature by placing an
empty file named tvdsvr.conf in your /etc directory. This
file must be owned by user ID 0 (root). When tvdsvr
encounters this option, it checks if this file exists. This
file’s contents are ignored.
You can use a different port by using one of the following options: –search_port or –port. To stop tvdsvr from
listening and accepting network connections, you must
terminate it by pressing Ctrl+C in the terminal window
from which it was started or by using the kill command.
–set_pw hexnumhigh:hexnumlow
Sets the password to the 64-bit number specified by the
hexnumhigh and hexnumlow 32-bit numbers. When a connection is established between tvdsvr and TotalView, the
64-bit password passed by TotalView must match this
password set with this option. tvdsvr displays the
selected number in the following message:
pw = hexnumhigh:hexnumlow
TotalView Reference Guide: version 6.3.1
201
7. tvdsvr Command Syntax
Waits for a serial line connection from TotalView. For
device, specifies the device name of a serial line, such as /
dev/com1. The only option you can specify is the baud
rate, which defaults to 38400. For more information on
debugging over a serial line, see “Debugging Over a Serial
Line” in Chapter 4 of the TotalView Users Guide.
–set_pws password-list / %C
We recommend using this option to avoid connections
by other users.
If necessary, you can disable password checking by
specifying the “–set_pw 0:0” option with the tvdsvr
command. Disabling password checking is dangerous; it
allows anyone to connect to your server and start programs, including shell commands, using your UID.
Therefore, we do not recommend disabling password
checking.
–set_pws password-list
Sets 64-bit passwords. TotalView must supply these
passwords when tvdsvr establishes the connection with
it. The argument to this command is a comma-separated list of passwords that TotalView automatically
generates. This option is most often used with a bulk
launch.
For more information, see Chapter 4, “Setting Up Remote
Debugging Sessions” in the TotalView Users Guide.
–verbosity level
Sets the verbosity level of TotalView Debugger Servergenerated messages to level, which may be one of silent,
error, warning, or info.
Default: info
–working_directory directory
Makes directory the directory to which TotalView will be
connected.
Note that the command assumes that the host machine
and the target machine mount identical file systems.
That is, the path name of the directory to which
TotalView is connected must be identical on both the
host and target machines.
After performing this operation, the TotalView Debugger
Server is started.
Replacement Characters ________________
When placing a tvdsvr command in a Server Launch or Bulk Launch string
(see the File > Preferences command within the online Help for more information), you will need to use special replacement characters. When your
program needs to launch a remote process, TotalView replaces these command characters with what they represent. Here are the replacement characters:
202
%B
Expands to the bin directory where tvdsvr is installed.
%C
Is replaced by the name of the server launch command
being used. On most platforms, this is rsh. On HP, this
command is remsh. If the TVDSVRLAUNCHCMD environ-
Chapter 7: TotalView Debugger Server
%D / %t1 and %t2
ment variable exists, TotalView will use its value instead
of its platform-specific value.
%D
Is replaced by the absolute path name of the directory
to which TotalView will be connected.
%F
Contains the “tracer configuration flags” that need to be
sent to tvdsvr processes. These are system-specific startup options that the tvdsvr process needs.
%H
Expands to the host name of the machine upon which
TotalView is running. (This replacement character is
most often used in bulk server launch commands. However, it can be used in a regular server launch and within
a tvdsvr command contained within a temporary file.)
%L
If TotalView is launching one process, this is replaced by
the host name and TCP/IP port number (hostname:port)
on which TotalView is listening for connections from
tvdsvr.
If a bulk launch is being performed, TotalView replaces
this with a comma-separated list of the host names and
TCP/IP port numbers (hostname:port,hostname:port...) on
which TotalView is listening for connections from tvdsvr.
For more information, see Chapter 4, “Setting Up Remote
Debugging Sessions” in the TotalView Users Guide.
Is replaced by the number of servers that TotalView will
launch. This is only used in a bulk server launch command.
%P
If TotalView is launching one process, this is replaced by
the password that TotalView automatically generated.
If a bulk launch is being performed, TotalView replaces
this with a comma-separated list of 64-bit passwords.
%R
Is replaced by the host name of the remote machine
specified in the File > New Program command.
%S
If TotalView is launching one process, it replaces this
symbol with the port number on the machine upon
which the debugger is running.
If a bulk server launch is being performed, TotalView
replaces this with a comma-separated list of port numbers.
%t1 and %t2
Is replaced by files that TotalView creates containing
information it generates. This is only available in a bulk
launch.
These temporary files have the following structure:
(1) An optional header line containing initialization
commands required by your system.
(2) One line for each host being connected to, containing host-specific information.
TotalView Reference Guide: version 6.3.1
203
7. tvdsvr Command Syntax
%N
%V / %V
(3) An optional trailer line containing information
needed by your system to terminate the temporary file.
The File > Preferences Bulk Server Page allows you to
define templates for the contents of temporary files.
These files may use these replacement characters. The
%N, %t1, and %t2 replacement characters can only be
used within header and trailer lines of temporary files.
All other characters can be used in header or trailer
lines or within a host line defining the command that
initiates a single-process server launch. In header or
trailer lines, they behave as defined for a bulk launch
within the host line. Otherwise, they behave as defined
for a single-server launch
%V
204
Is replaced by the current TotalView verbosity setting.
Chapter 7: TotalView Debugger Server
Part III: Platforms and
Operating Systems
The three chapters in this part of the Reference Guide describe information
that is unique to the computers, operating systems, and environments in
which TotalView runs.
Chapter 8: Compilers and Platforms
Here you will find general information on the compilers and
runtime environments that TotalView supports. This chapter
also contains commands for starting TotalView and information on linking with the dbfork library.
Chapter 9: Operating Systems
While how you use TotalView is the same on all operating
systems, there are some things you will need to know that
are differ from platform to platform.
Chapter 10: Architectures
When debugging assembly-level functions, you will need to
know how TotalView refers to your machines registers.
TotalView Reference Guide: version 6.3.1
205
206
Compilers and
Platforms
8
This chapter describes the compilers and parallel runtime environments used on platforms supported by TotalView. You must refer to
the TotalView Release Notes included in the TotalView distribution
for information on the specific compiler and runtime environment
supported by TotalView.
For information on supported operating systems, please refer to
Chapter 9, “Operating Systems,” on page 215.
Topics in this chapter are:
■
■
■
Compiling with Debugging Symbols
Using Exception Data on Tru64 UNIX
Linking with the dbfork Library
Compiling with Debugging Symbols _____
You need to compile programs with the –g option and possibly other compiler options so that debugging symbols are included. This section shows
the specific compiler commands to use for each compiler that TotalView
supports.
Please refer to the release notes in your TotalView distribution for the latest information
about supported versions of the compilers and parallel runtime environments listed here.
HP Alpha Running
Linux
Table 3 lists the procedures to compile programs on HP Alpha running
Linux.
Table 3: Compiling with
Debugging Symbols on HP
Alpha Linux
Compiler
HP Alpha Linux C
HP Alpha Linux Fortran
GCC EGCS C
TotalView Reference Guide: version 6.3.1
Compiler Command Line
ccc –g program.c
cfal –g program.f
gcc –g program.c
207
Compiling with Debugging Symbols
Compiler
GCC EGCS C++
GCC EGCS Fortran
Compiler Command Line
g++ –g program.cxx
g77 –g program.f
HP Tru64 UNIX
Table 4 lists the procedures to compile programs on HP Tru64 UNIX.
Table 4: Compiling with
Debugging Symbols on HP
Tru64 UNIX
Compiler
HP Tru64 UNIX C
HP Tru64 UNIX C++
HP Tru64 UNIX Fortran 77
HP Tru64 UNIX Fortran 90
HP Tru64 UPC compiler
GCC EGCS C
GCC EGCS C++
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
Compiler Command Line
cc –g program.c
cxx –g program.cxx
f77 –g program.f
f90 –g program.f90
upc -g [-fthreads n] program.upc
gcc –g program.c
g++ –g program.cxx
KCC +K0 program.c
KCC +K0 program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
When compiling with KCC for debugging, we recommend that you use the
+K0 option and not the –g option. Also, the –WG,–cmpo=i option to the
guidef77 command may not be required on all versions because –g can
imply these options.
HP-UX
Table 5 lists the procedures to compile programs on HP-UX.
Table 5: Compiling with
Debugging Symbols on HPUX
Compiler
HP ANSI C
HP C++
HP Fortran 90
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
Compiler Command Line
cc –g program.c
aCC –g program.cxx
f90 –g program.f90
KCC +K0 program.c
KCC +K0 program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
When compiling with KCC for debugging, we recommend that you use the
+K0 option and not the –g option. Also, the –WG,–cmpo=i option to the
guidef77 command may not be required on all versions because –g can
imply these options.
IBM AIX on RS/
6000 Systems
Table 6 lists the procedures to compile programs on IBM RS/6000 systems
running AIX.
Table 6: Compiling with
Debugging Symbols on AIX
Compiler
GCC EGCS C
GCC EGCS C++
IBM xlc C
208
Compiler Command Line
gcc –g program.c
g++ –g program.cxx
xlc –g program.c
Chapter 8: Compilers and Platforms
Compiling with Debugging Symbols
Compiler
IBM xlC C++
IBM xlf Fortran 77
IBM xlf90 Fortran 90
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
Compiler Command Line
xlC –g program.cxx
xlf –g program.f
xlf90 –g program.f90
KCC +K0 –qnofullpath program.c
KCC +K0 –qnofullpath program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
You should not define any of the following variables when debugging
threaded applications:
■
■
■
■
AIXTHREAD_DEBUG
AIXTHREAD_COND_DEBUG
AIXTHREAD_MUTEX_DEBUG
AIXTHREAD_RWLOCK_DEBUG
When compiling with KCC, you must specify the –qnofullpath option; KCC
is a preprocessor that passes its output to the IBM xlc C compiler. It will
discard #line directives necessary for source-level debugging if you do not
use the –qfullpath option. We also recommend that you use the +K0
option and not the –g option.
When compiling with guidef77, the –WG,–cmpo=i option may not be
required on all versions because –g can imply these options.
When compiling Fortran programs with the C preprocessor, pass the –d
option to the compiler driver. For example: xlf –d –g program.F
If you will be moving any program compiled with any of the IBM xl compilers from its creation directory, or you do not want to set the search directory path during debugging, use the –qfullpath compiler option. For example:
xlf –qfullpath –g –c program.f
Linux Running on
an x86 Platform
Table 7 lists the procedures to compile programs on Linux x86 platforms.
Table 7: Compiling with
Debugging Symbols on Linux
x86
Compiler
GCC EGCS C
GCC EGCS C++
Intel C++ Compiler
Intel Fortran Compiler
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
Lahey/Fujitsu Fortran
PGI Fortran 90
8. Compilers & Platforms
TotalView Reference Guide: version 6.3.1
Compiler Command Line
gcc –g program.c
g++ –g program.cxx
icc –g program.cxx
ifc –g program.f
KCC +K0 program.c
KCC +K0 program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
lf95 –g program.f
pgf90 –g program.f
209
Compiling with Debugging Symbols
When compiling with KCC for debugging, we recommend that you use the
+K0 option and not the –g option. Also, the –WG,–cmpo=i option to the
guidef77 command may not be required on all versions because –g can
imply these options.
SGI IRIX-MIPS
Systems
Table 8 lists the procedures to compile programs on SGI MIPS systems running IRIX.
Table 8: Compiling with
Debugging Symbols on IRIXMIPS
Compiler
GCC EGCS C
GCC EGCS C++
Intrepid (GCC UPC)
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
SGI MIPSpro 90
SGI MIPSpro C
SGI MIPSpro C++
SGI MIPSpro77
Compiler Command Line
gcc –g program.c
g++ –g program.cxx
upc -g [-fthreads n] program.upc
KCC +K0 program.c
KCC +K0 program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
f90 –n32 –g program.f90
f90 –64 –g program.f90
cc –n32 –g program.c
cc –64 –g program.c
CC –n32 –g program.cxx
CC –64 –g program.cxx
f77 –n32 –g program.f
f77 –64 –g program.f
You cannot compile your program using either of the –n32 or –64 command line options. TotalView does not support compiling with –32, which is
the default for some compilers. You must specify either –n32 or –64.
When compiling with KCC for debugging, we recommend that you use the
+K0 option and not the –g option. Also, the –WG,–cmpo=i option to the
guidef77 command may not be required on all versions because –g can
imply these options.
SunOS 5 on SPARC
Table 9 lists the procedures to compile programs on SunOS 5 SPARC.
Table 9: Compiling with
Debugging Symbols on
SunOS 5
Compiler
Apogee C
Apogee C++
GCC EGCS C
GCC EGCS C++
KAI C
KAI C++
KAI Guide C (OpenMP)
KAI Guide C++ (OpenMP)
KAI Guide F77 (OpenMP)
SunPro/WorkShop C
SunPro/WorkShop C++
210
Compiler Command Line
apcc –g program.c
apcc –g program.cxx
gcc –g program.c
g++ –g program.cxx
KCC +K0 program.c
KCC +K0 program.cxx
guidec –g +K0 program.c
guidec –g +K0 program.cxx
guidef77 –g –WG,–cmpo=i program.f
cc –g program.c
CC –g program.cxx
Chapter 8: Compilers and Platforms
Using Exception Data on Tru64 UNIX
Compiler
SunPro/WorkShop Fortran 77
WorkShop Fortran 90
Compiler Command Line
f77 –g program.f
f90 –g program.f90
When compiling with KCC for debugging, we recommend that you use the
+K0 option and not the –g option. Also, the –WG,–cmpo=i option to the
guidef77 command may not be required on all versions because –g can
imply these options.
Using Exception Data on Tru64 UNIX _____
If you receive the following error message when you load an executable
into TotalView, you may need to compile your program so that it includes
exception data.
Cannot find exception information. Stack backtraces may not be
correct.
To provide a complete stack backtrace in all situations, TotalView needs for
you to include exception data with the compiled executable. To compile
with exception data, you need to use the following options:
cc –Wl,–u,_fpdata_size program.c
where:
–Wl
Passes the arguments that follow to another compilation phase (–W), which in this case is the linker (l). Each
argument is separated by a comma (,).
–u,_fpdata_size Causes the linker to mark the next argument
(_fpdata_size) as undefined. This forces the exception
data into the executable.
program.c
Is the name of your program.
Compiling with exception data increases the size of your executable
slightly. If you choose not to compile with exception data, TotalView can
provide correct stack backtraces in most situations, but not in all situations.
If your program uses the fork() and execve() system calls, and you want to
debug the child processes, you need to link programs with the dbfork
library.
Linking with
dbfork and HP
Tru64 UNIX
Add one of the following command-line options to the command that you
use to link your programs:
/opt/totalview/alpha/lib/libdbfork.a
■ –L/opt/totalview/alpha/lib –ldbfork
■
TotalView Reference Guide: version 6.3.1
211
8. Compilers & Platforms
Linking with the dbfork Library _________
Linking with the dbfork Library
For example:
cc –o program program.c \
–L/opt/totalview/alpha/lib –ldbfork
As an alternative, you can set the LD_LIBRARY_PATH environment variable
and omit the –L option on the command line:
setenv LD_LIBRARY_PATH /opt/totalview/alpha/lib
Linking with HPUX
Add either the –ldbfork or –ldbfork_64 argument to the command that you
use to link your programs. If you are compiling 32-bit code, use one of the
following arguments:
■
■
/opt/totalview/lib/hpux11-hppa/libdbfork.a
–L/opt/totalview/hpux11-hppa/lib –ldbfork
For example:
cc –n32 –o program program.c \
–L/opt/totalview/hpux11-hppa/lib –ldbfork
If you are compiling 64-bit code, use the following arguments:
■
■
/opt/totalview/lib/hpux11-hppa/libdbfork_64.a
–L/opt/totalview/hpux11-hppa/lib –ldbfork_64
For example:
cc –64 –o program program.c \
–L/opt/totalview/hpux11-hppa/lib \
–ldbfork_64
As an alternative, you can set the LD_LIBRARY_PATH environment variable
and omit the –L command-line option. For example:
setenv LD_LIBRARY_PATH \
/opt/totalview/hpux11-hppa/lib
dbfork on IBM AIX
on RS/6000
Systems
Add either the –dbfork or –ldbfork_64 argument to the command that you
use to link your programs. If you are compiling 32-bit code, use the following arguments:
/usr/totalview/lib/libdbfork.a –bkeepfile:/usr/totalview/lib/rs6000/
libdbfork.a
■ –L/usr/totalview/lib –ldbfork –bkeepfile:/usr/totalview/lib/rs6000/
libdbfork.a
■
For example:
cc –o program program.c \
–L/usr/totalview/rs6000/lib/ –ldbfork \
–bkeepfile:/usr/totalview/rs6000/lib/libdbfork.a
If you are compiling 64-bit code, use the following arguments:
/usr/totalview/lib/libdbfork_64.a \
–bkeepfile:/usr/totalview/rs6000/lib/libdbfork.a
■ –L/usr/totalview/lib –ldbfork_64 \
–bkeepfile:/usr/totalviewrs6000//lib/libdbfork.a
■
212
Chapter 8: Compilers and Platforms
Linking with the dbfork Library
For example:
cc –o program program.c \
–L/usr/totalview/rs6000/lib –ldbfork \
–bkeepfile:/usr/totalview/rs6000/lib/libdbfork.a
When you use gcc or g++, use the –Wl,–bkeepfile option instead of using
the –bkeepfile option, which will pass the same option to the binder. For
example:
gcc –o program program.c \
–L/usr/totalview/rs6000/lib –ldbfork –Wl, \
–bkeepfile:/usr/totalview/rs6000/lib/libdbfork.a
Linking C++ Programs with dbfork
You cannot use the –bkeepfile binder option with the IBM xlC C++ compiler. The compiler passes all binder options to an additional pass called
munch, which will not handle the –bkeepfile option.
To work around this problem, we have provided the C++ header file
libdbfork.h. You must include this file somewhere in your C++ program.
This forces the components of the dbfork library to be kept in your executable. The file libdbfork.h is included only with the RS/6000 version of
TotalView. This means that if you are creating a program that will run on
more than one platform, you should place the include within an #ifdef
statement’s range. For example:
#ifdef _AIX
#include “/usr/totalview/rs6000/lib/libdbfork.h”
#endif
int main (int argc, char *argv[])
{
}
In this case, you would not use the –bkeepfile option and would instead
link your program using one of the following options:
■
■
Linux
/usr/totalview/rs6000/lib/libdbfork.a
–L/usr/totalview/rs6000/lib –ldbfork
Add one of the following arguments or command-line options to the command that you use to link your programs:
■
/usr/totalview/platform/lib/libdfork.a
-L/usr/totalview/platform/lib –lbdbfork
where platform is either linux-86 or linux-alpha.
For example:
cc –o program program.c \
–L/usr/totalview/linux-86/lib –ldbfork
As an alternative, you can set the LD_LIBRARY_PATH environment variable
and omit the –L option on the command line:
setenv LD_LIBRARY_PATH /usr/totalview/platform/lib
where platform is again either linux-86 or linux-alpha.
TotalView Reference Guide: version 6.3.1
213
8. Compilers & Platforms
■
Linking with the dbfork Library
SGI IRIX6-MIPS
Add one of the following arguments or command-line options to the command that you use to link your programs.
If you are compiling your code with –n32, use the following arguments:
■
■
/opt/totalview/irix6-mips/lib/libdbfork_n32.a
–L/opt/totalview/irix6-mips/lib –ldbfork_n32
For example:
cc –n32 –o program program.c \
–L/opt/totalview/irix6-mips/lib –ldbfork_n32
If you are compiling your code with –64, use the following arguments:
■
■
/opt/totalview/irix6-mips/lib/libdbfork.a_n64.a
–L/opt/totalview/irix6-mips/lib –ldbfork_n64
For example:
cc –64 –o program program.c \
–L/opt/totalview/irix6-mips/lib –ldbfork_n64
As an alternative, you can set the LD_LIBRARY_PATH environment variable
and omit the –L option on the command line:
setenv LD_LIBRARY_PATH /opt/totalview/irix6-mips/lib
SunOS 5 SPARC
Add one of the following command line arguments or options to the command that you use to link your programs:
■
■
/opt/totalview/sun5/lib/libdbfork.a
–L/opt/totalview/sun5/lib –ldbfork
For example:
cc –o program program.c \
–L/opt/totalview/sun5/lib –ldbfork
As an alternative, you can set the LD_LIBRARY_PATH environment variable
and omit the –L option on the command line:
setenv LD_LIBRARY_PATH /opt/totalview/sun5/lib
214
Chapter 8: Compilers and Platforms
Operating Systems
9
This chapter describes the operating system features that can be used with
TotalView. This chapter includes the following topics:
■
■
■
■
■
■
■
Supported Operating Systems
Mounting the /proc File System (HP Tru64 UNIX, IRIX, and SunOS
5 only)
Swap Space
Shared Libraries
Debugging Dynamically Loaded Libraries
Remapping Keys (Sun Keyboards only)
Expression System
Supported Operating Systems___________
Here is an overview of operating systems and some of the environments
supported by TotalView at the time when this book was printed. As this
book isn’t printed nearly as often as vendors update compilers and operating systems, the compiler and operating system versions mentioned here
may be obsolete. For a definitive list, see the TotalView Platforms document
on our web site. You can locate this document by going to http://
www.etnus.com/Support/docs/”.
■
■
■
■
■
■
HP Alpha workstations running HP Tru64 UNIX versions V4.0F, V5.1, and
V5.1A. Many versions require patches. See “HP UNIX Patch Procedures”
in the TotalView Platforms document for instructions.
HP PA-RISC 1.1 or 2.0 systems running HP-UX Version 11.00,11.10, and
11.11i.
IBM RS/6000 and SP systems running AIX versions 4.3.3 and 5.1L.
Linux Red Hat 7.1, 7.2, 7.3, and 8.0.
SGI IRIX 6.5.1.15f and 6.5.1.16f on any MIPS R4000, R4400, R4600,
R5000, R8000, R10000, and R12000 processor-based systems.
Sun Sparc Solaris 7, 8 and 9.
TotalView Reference Guide: version 6.3.1
215
Mounting the /proc File System
Mounting the /proc File System
To debug programs on HP Tru64 UNIX, SunOS 5, and IRIX with TotalView,
you need to mount the /proc file system.
If you receive one of the following errors from TotalView, the /proc file system might not be mounted:
■ job_t::launch, creating process: process not found
■ Error launching process while trying to read dynamic symbols
■ Creating Process... Process not found
Clearing Thrown Flag
Operation Attempted on an unbound d_process object
To determine whether the /proc file system is mounted, enter the appropriate command from the following table.
Table 10: Commands for
Determining Whether /proc is
Mounted
Operating System
HP Tru64 UNIX
SunOS 5
IRIX
Command
% /sbin/mount –t procfs
/proc on /proc type procfs (rw)
% /sbin/mount | grep /proc
/proc on /proc read/write/setuid on ...
% /sbin/mount | grep /proc
/proc on /proc type proc (rw)
If you receive one of these messages from the mount command, the /proc
file system is mounted.
Mounting /proc HP
Tru64 UNIX and
SunOS 5
To make sure that the /proc file system is mounted each time your system
boots, add the appropriate line from the following table to the appropriate
file.
Table 11: Commands for
Automatically Mounting the /
proc File System
Operating System
HP Tru64 UNIX
SunOS 5
Name of File
Line to add
/etc/fstab
/proc /proc procfs rw 0 0
/etc/vfstab
/proc - /proc proc - no -
Then, to mount the /proc file system, enter the following command:
/sbin/mount /proc
Mounting proc
SGI IRIX
To make sure that the /proc file system is mounted each time your system
boots, make sure that /etc/rc2 issues the /etc/mntproc command. Then, to
mount the /proc file system, enter the following command:
/etc/mntproc
Swap Space ___________________________
Debugging large programs can exhaust the swap space on your machine. If
you run out of swap space, TotalView exits with a fatal error, such as:
■ Fatal Error: Out of space trying to allocate
This error indicates that TotalView failed to allocate dynamic memory. It
can occur anytime during a TotalView session. It can also indicate that the
216
Chapter 9: Operating Systems
Swap Space
data size limit in the C shell is too small. You can use the C shell’s limit
command to increase the data size limit. For example:
This error indicates that the fork() or execve() system call failed while
TotalView was creating a process to debug. It can happen when TotalView
tries to create a process.
Swap Space on HP
Tru64 UNIX
To find out how much swap space has been allocated and is currently being
used, use the swapon command on HP Tru64 UNIX.
To find out how much swap space is in use while you are running TotalView:
/bin/ps –o LFMT
To add swap space, use the /sbin/swapon(8) command. You must be logged
in as root to use this command. For more information, refer to the online
manual page for this command.
Swap Space on HP
HP-UX
The swapinfo command on an HP-UX system lets you find out how much
swap space is allocated and is being used.
To find out how much swap space is being used while TotalView is running,
enter:
/usr/bin/ps -lf
Here is an example of what you might see. The SZ column shows the pages
occupied by a program.
To add swap space, use the/usr/sbin/swapon(1M) command or the SAM
(System Administration Manager) utility. If you use SAM, invoke the Swap
command in the Disks and File Systems menu.
Maximum Data Size
To see the current data size limit in the C shell, enter:
limit datasize
The following command displays the current hard limit:
limit –h datasize
If the current limit is lower than the hard limit, you can easily raise the current limit. To change the current limit, enter:
limit datasize new_data_size
If the hard limit is too low, you must reconfigure and rebuild the kernel, and
then reboot. This is most easily done using SAM.
To change maxdsiz, use the following path through the SAM menus:
Kernel Configuration > Configurable Parameters >
maxdsiz > Actions > Modify Configurable Parameter >
Specify New Formula/Value > Formula/Value
You can now enter the new maximum data segment size.
You may also need to change the value for maxdsiz_64.
TotalView Reference Guide: version 6.3.1
217
9. Operating Systems
limit datasize unlimited
■ job_t::launch, creating process: Operation failed
Swap Space
Here is the command that lets you rebuild the kernel with these changed
values:
Configurable Parameter > Actions >
Process New Kernel
Answer yes to process the kernel modifications, yes to install the new kernel, and yes again to reboot the machine with the new kernel.
When the machine reboots, the value you set for maxdsiz should be the
new hard limit.
Swap Space on IBM AIX
To find out how much swap space has been allocated and is currently being
used, use the pstat -s command:
To find out how much swap space is in use while you are running TotalView:
1 Start TotalView with a large executable:
totalview executable
Press Ctrl+Z to suspend TotalView.
2 Use the following command to see how much swap space TotalView is
using:
ps u
For example, in this case the value in the SZ column is 5476 KB:
USER
PID %CPU %MEM
SZ RSS
TTY ...
smith 15080 0.0 6.0 5476 5476 pts/1 ...
To add swap space, use the AIX system management tool, smit. Use the
following path through the smit menus:
System Storage Management > Logical Volume Manager >
Paging Space
Swap Space on
Linux
To find out how much swap space has been allocated and is currently being
used, use either the swapon or top commands on Linux:
You can use the mkswap(8) command to create swap space. The swapon(8)
command tells Linux that it should use this space.
Swap Space on
SGI IRIX
To find out how much swap space has been allocated and is currently being
used, use the swap command:
To find out how much swap space is in use while you are running TotalView:
1 Start TotalView with a large executable:
totalview executable
Press Ctrl+Z to suspend TotalView.
2 Use the following command to see how much swap space TotalView is
using:
/bin/ps –l
Use the following command to determine the number of bytes in a page:
sysconf PAGESIZE
218
Chapter 9: Operating Systems
Shared Libraries
Swap Space on
SunOS 5
To find out how much swap space has been allocated and is currently being
used, use the swap -s command:
To find out how much swap space is in use while you are running TotalView:
1 Start TotalView with a large executable:
totalview executable
Press Ctrl+Z to suspend TotalView.
2 Use the following command to see how much swap space TotalView is
using:
/bin/ps –l
To add swap space, use the mkfile(1M) and swap(1M) commands. You
must be root to use these commands. For more information, refer to the
online manual pages for these commands.
Shared Libraries _______________________
TotalView supports dynamically linked executables, that is, executables
that are linked with shared libraries.
When you start TotalView with a dynamically linked executable, TotalView
loads an additional set of symbols for the shared libraries, as indicated in
the shell from which you started TotalView. To accomplish this, TotalView:
1 Runs a sample process and discards it.
2 Reads information from the process.
3 Reads the symbol table for each library.
When you create a process without starting it, and the process does not
include shared libraries, the PC points to the entry point of the process,
usually the start routine. If the process does include shared libraries, however, TotalView takes the following actions:
■
■
Runs the dynamic loader (SunOS 5: ld.so, HP Tru64 UNIX: /sbin/loader,
Linux: /lib/ld-linux.so.?, IRIX: rld).
Sets the PC to point to the location after the invocation of the dynamic
loader but before the invocation of C++ static constructors or the
main() routine.
On HP-UX, TotalView cannot stop the loading of shared libraries until after static
constructors on shared library initialization routines have been run.
When you attach to a process that uses shared libraries, TotalView takes
the following actions:
■
If you attached to the process after the dynamic loader ran, then
TotalView loads the dynamic symbols for the shared library.
TotalView Reference Guide: version 6.3.1
219
9. Operating Systems
To add swap space, use the mkfile(1M) and swap(1M) commands. You
must be root to use these commands. For more information, refer to the
online manual pages for these commands.
Shared Libraries
■
If you attached to the process before it runs the dynamic loader,
TotalView allows the process to run the dynamic loader to completion.
Then, TotalView loads the dynamic symbols for the shared library.
If desired, you can suppress the recording and use of dynamic symbols for
shared libraries by starting TotalView with the –no_dynamic option. Refer to
Chapter 6, “TotalView Command Syntax,” on page 191 for details on this
TotalView startup option.
If a shared library has changed since you started a TotalView session, you
can use the Group > Rescan Library command to reload library symbol
tables. Be aware that only some systems such as AIX permit you to reload
library information.
Changing Linkage
Table Entries and
LD_BIND_NOW
If you are executing a dynamically linked program, calls from the executable
into a shared library are made using the Procedure Linkage Table (PLT). Each
function in the dynamic library that is called by the main program has an
entry in this table. Normally, the dynamic linker fills the PLT entries with
code that calls the dynamic linker. This means that the first time that your
code calls a function in a dynamic library, the runtime environment calls
the dynamic linker. The linker will then modify the entry so that next time
this function is called, it will not be involved.
This is not the behavior you want or expect when debugging a program
because TotalView will do one of the following:
■
■
Place you within the dynamic linker (which you don't want to see).
Step over the function.
And, because the entry is altered, everything appears to work fine the next
time you step into this function.
On most operating systems (except HP), you can correct this problem by
setting the LD_BIND_NOW environment variable. For example:
setenv LD_BIND_NOW 1
This tells the dynamic linker that it should alter the PLT when the program
starts executing rather than doing it when the program calls the function.
HP-UX does not have this (or an equivalent) variable. On HP systems, you
can avoid this problem by using the –B immediate option the executable
being debugged, or by invoking chatr with the –B immediate option. (See
the chatr documentation for complete information on how to use this
command.)
You will also have to enter pxdb –s on.
Using Shared
Libraries on HP-UX
The dynamic library loader on HP-UX loads shared libraries into shared
memory. Writing breakpoints into code sections loaded in shared memory
can cause programs not under TotalView’s control to fail when they execute an unexpected breakpoint.
If you need to single-step or set breakpoints in shared libraries, you must
set your application to load those libraries in private memory. This is done
using HP’s pxdb command.
220
Chapter 9: Operating Systems
Debugging Dynamically Loaded Libraries
For 64-bit platforms, use pxdb64 instead of pxdb. If the version of pxdb64
supplied with HP's compilers does not work correctly, you may need to
install an HP-supplied patch. You will find additional information in the
TotalView Release Notes.
Debugging Dynamically Loaded Libraries _
TotalView automatically reads the symbols of shared libraries that are
dynamically loaded into your program at runtime. These libraries are ones
that are loaded using dlopen (or, on IBM AIX, load and loadbind).
TotalView automatically detects these calls, and then loads the symbol
table from the newly loaded libraries and plants any enabled saved breakpoints for these libraries. TotalView then decides whether to ask you about
stopping the process to plant breakpoints. You will set these characteristics by using the Dynamic Libraries Page in the File > Preferences Dialog
Box. (See “File > Preferences Dialog Box: Dynamic Libraries Page” on page 221.)
Figure 1: File > Preferences
Dialog Box: Dynamic Libraries
Page
TotalView decides according to the following rules:
1 If either the Load symbols from dynamic libraries or Ask to stop when
loading dynamic libraries preference is set to false, TotalView does not ask
you about stopping.
2 If one or more of the strings in the When the file suffix matches preference
list is a suffix of the full library name (including path), TotalView asks you
about stopping.
TotalView Reference Guide: version 6.3.1
221
9. Operating Systems
pxdb -s on appname (load shared libraries into
private memory)
pxdb -s off appname (load shared libraries into
shared memory)
Debugging Dynamically Loaded Libraries
3 If one or more of the strings in the When the file path prefix does not
match list is a prefix of the full library name (including path), TotalView does
not ask you about stopping.
4 If the newly loaded libraries have any saved breakpoints, TotalView does not
ask you about stopping.
5 If none of the rules above apply, TotalView asks you about stopping.
If TotalView does not ask you about stopping the process, the process is
continued.
If TotalView decides to ask you about stopping, it displays a dialog box,
asking if it should stop the process so you can set breakpoints. To stop the
process, answer Yes. (See Figure 2.)
Figure 2: Stop Process Question
Dialog Box
To allow the process to continue executing, answer No. Stopping the process allows you to insert breakpoints in the newly loaded shared library.
Do either or both of the following to tell TotalView if it should ask:
■
■
If you can set the –ask_on_dlopen command-line option to true, or you
can set the –no_ask_on_dlopen option to false.
Unset the Load symbols from dynamic libraries preference.
The following table lists paths where you are not asked if TotalView should
stop the process:
Table 12: Default “Don’t
Ask” on Load List
Platform
HP Tru64 UNIX Alpha
HP-UX
IBM AIX
SGI IRIX
SUN Solaris 2.x
Linux x86
Linux Alpha
222
Value
/usr/shlib/
/usr/lib/cmplrs/cc/
/usr/local/lib/
/usr/lib/
/opt/langtools/lib/
/lib/
/usr/lpp/
/usr/dt/lib/
/lib/
/usr/local/lib/
/usr/lib32/
/lib64/
/usr/local/lib64
/lib/
/usr/ccs/lib/
/lib
/lib
/usr/ccs/lib/
/usr/lib/
/var/shlib/
/usr/lib/pa20_64
/opt/langtools/lib/pa20_64/
/usr/lib/
/usr/ccs/lib/
/tmp/
/usr/lib/
/lib32/
/usr/local/lib32/
/usr/lib64/
/usr/lib/
/usr/lib
/usr/lib
Chapter 9: Operating Systems
Remapping Keys
The values you enter in the TotalView preference should be space-separated lists of the prefixes and suffixes to be used.
Known Limitations
Dynamic library support has the following known limitations:
■
■
TotalView does not deal correctly with parallel programs that call dlopen
on different libraries in different processes. TotalView requires that the
processes have a uniform address space, including all shared libraries.
TotalView does not yet fully support unloading libraries (using dlclose)
and then reloading them at a different address using dlopen.
Remapping Keys _______________________
On the SunOS 5 keyboard, you may need to remap the page-up and pagedown keys to the prior and next keysym so that you can scroll TotalView
windows with the page-up and page-down keys. To do so, add the following
lines to your X Window System startup file:
# Remap F29/F35 to PgUp/PgDn
xmodmap -e 'keysym F29 = Prior'
xmodmap -e 'keysym F35 = Next'
Expression System _____________________
Depending on the target platform, TotalView supports:
■
■
An interpreted expression system only
Both an interpreted and a compiled expression system
Unless stated otherwise below, TotalView supports interpreted expressions
only.
Expression System
on HP Alpha Tru64
UNIX
On HP Tru64 UNIX, TotalView supports compiled and interpreted expressions. TotalView also supports assembly language in expressions.
Expression System
on IBM AIX
On IBM AIX, TotalView supports compiled and interpreted expressions.
TotalView also supports assembly language in expressions.
Some program functions called from the TotalView expression system on
the Power architecture cannot have floating-point arguments that are
passed by value. However, in functions with a variable number of arguments, floating-point arguments can be in the varying part of the argument
list. For example, you can include floating-point arguments with calls to
printf:
double d = 3.14159;
printf("d = %f\n", d);
TotalView Reference Guide: version 6.3.1
223
9. Operating Systems
After starting TotalView, you can change these lists by using the When the
file suffix matches and And the file path prefix does not match preferences.
Expression System
Expression System
on SGI IRIX
On IRIX, TotalView supports compiled and interpreted expressions.
TotalView also supports assembler in expressions.
TotalView includes the SGI IRIX expression compiler. This feature does not
use any MIPS-IV specific instructions. It does use MIPS-III instructions
freely. It fully supports –n32 and –64 executables.
Due to limitations in dynamically allocating patch space, compiled expressions are disabled by default on SGI IRIX. To enable compiled expressions,
use the TV::compile_expressions CLI variable to set the option to true. This
variable tells TotalView to find or allocate patch space in your program for
code fragments generated by the expression compiler.
If you enable compiled patches on SGI IRIX with a multiprocess program,
you must use static patches. For example, if you link a static patch space
into a program and run the program under TotalView’s control, TotalView
should let you debug it. If you attach to a previously started MPI job, however, even static patches will not let the program run properly. If TotalView
still fails to work properly with the static patch space, then you probably
cannot use compiled patches with your program.
For general instructions on using patch space allocation controls with compiled expressions, see “Allocating Patch Space for Compiled Expressions” in
Chapter 14 of the TotalView Users Guide.
224
Chapter 9: Operating Systems
10
Architectures
This chapter describes the architectures TotalView supports, including:
■
■
■
■
■
■
■
“HP Alpha” on page 225
“HP PA-RISC” on page 227
“IBM Power” on page 229
“Intel IA-64” on page 233
“Intel x86” on page 236 (Intel 80386, 80486 and Pentium processors)
“SGI MIPS” on page 240
“Sun SPARC” on page 244
HP Alpha _____________________________
This section contains the following information:
■
■
■
Alpha General Registers
Alpha Floating-Point Registers
Alpha FPCR Register
The Alpha processor supports the IEEE floating-point format.
Alpha General
Registers
Table 13: Alpha GeneralPurpose Integer Registers
TotalView displays the Alpha general registers in the Stack Frame Pane of
the Process Window. The next table describes how TotalView treats each
general register, and the actions you can take with each register.
Register Description
V0
Function value register
T0 – T7 Conventional scratch
registers
S0 – S5 Conventional saved registers
TotalView Reference Guide: version 6.3.1
Data Type
<long>
<long>
Edit
yes
yes
Specify in
Dive Expression
yes
$v0
yes
$t0 – $t7
<long>
yes
yes
$s0 – $s5
225
HP Alpha
Register
S6
A0 – A5
T8 – T11
RA
T12
AT
GP
SP
ZERO
PC
FP
Alpha FloatingPoint Registers
Table 14: Alpha FloatingPoint Registers
Description
Stack frame base register
Argument registers
Conventional scratch
registers
Return Address register
Procedure value register
Volatile scratch register
Global pointer register
Stack pointer
ReadAsZero/Sink register
Program counter
Frame pointer. The Frame
Pointer is a software register
that TotalView maintains; it
is not an actual hardware
register. TotalView computes
the value of FP as part of the
stack backtrace.
Data Type
<long>
<long>
<long>
Edit
yes
yes
yes
Specify in
Dive Expression
yes
$s6
yes
$a0 – $a5
yes
$t8 – $t11
<long>
<long>
<long>
<long>
<long>
<long>
<code>[]
<long>
yes
yes
yes
yes
yes
no
no
no
yes
yes
yes
yes
yes
yes
yes
yes
$ra
$t12
$at
$gp
$sp
$zero
$pc
$fp
TotalView displays the Alpha floating-point registers in the Stack Frame
Pane of the Process Window. Here is a table that describes how TotalView
treats each floating-point register, and the actions you can take with each
register.
Register Description
F0 – F1 Floating-point registers (f
registers), used singly
F2 – F9 Conventional saved
registers
F10 – F15 Conventional scratch
registers
F16 – F21 Argument registers
F22 – F30 Conventional scratch
registers
F31
ReadAsZero/Sink register
FPCR
Floating-point control
register
Data Type
<double>
Edit
yes
Specify in
Dive Expression
yes
$f0 – $f1
<double>
yes
yes
$f2 – $f9
<double>
yes
yes
$f10 – $f15
<double>
<double>
yes
yes
yes
yes
$f16 – $f21
$f22 – $f30
<double>
<long>
yes
yes
yes
no
$f31
$fpcr
Alpha FPCR
Register
For your convenience, TotalView interprets the bit settings of the Alpha
FPCR register. You can edit the value of the FPCR and set it to any of the bit
settings outlined in the following table.
Table 15: Alpha FPCR
Registers
Value
Bit Setting
Meaning
SUM
0x8000000000000000
Summary bit
DYN=CHOP
0x0000000000000000
Rounding mode — Chopped rounding
mode
226
Chapter 10: Architectures
HP PA-RISC
Value
Bit Setting
Meaning
DYN=MINF
0x0400000000000000
Rounding mode — Negative infinity
DYN=NORM
0x0800000000000000
Rounding mode — Normal rounding
DYN=PINF
0x0c00000000000000
Rounding mode — Positive infinity
IOV
0x0200000000000000
Integer overflow
INE
0x0100000000000000
Inexact result
UNF
0x0080000000000000
Underflow
OVF
0x0040000000000000
Overflow
DZE
0x0020000000000000
Division by zero
INV
0x0010000000000000
Invalid operation
This section contains the following information:
■
■
■
■
PA-RISC General
Registers
Table 16: PA-RISC General
Registers
PA-RISC General Registers
PA-RISC Process Status Word
PA-RISC Floating-Point Registers
PA-RISC Floating-Point Format
TotalView displays the PA-RISC general registers in the Stack Frame Pane of
the Process Window. The following table describes how TotalView treats
each general register and the actions you take with them.
Register
r0
r1-r31
pc
nxtpc
pcs
nxtpcs
psw
sar
sr0-sr7
recov
pid1-pid8
Description
Always contains zero
General registers
Current instruction pointer
Next instruction pointer
Current instruction space
Next instruction space
Processor status word
Shift amount register
Space registers
Recovery counter
Protection IDs
Data Type
<long>
<long>
<long>
<long>
<long>
<long>
<long>
<long>
<long>
<long>
<long>
Edit
no
yes
yes
yes
no
no
yes
yes
no
no
no
Dive
no
yes
yes
yes
no
no
no
no
no
no
no
ccr
scr
eiem
Coprocessor configuration
SFU configuration register
External interrupt enable
mask
Interrupt instruction
Interrupt space
Interrupt offset
Temporary registers
Thread pointer
<long>
<long>
<long>
no
no
no
no
no
no
Specify in
Expression
$r0
$r1-$r31
$pc
$nxtpc
$pcs
$nxtpcs
$psw
$sar
$sr0-$sr7
$recov
$pid1$pid8
$ccr
$scr
$eiem
<long>
<long>
<long>
<long>
<long>
no
no
no
no
yes
no
no
no
no
yes
$iir
$isr
$ior
$cr24-$cr26
$tp
iir
isr
ior
cr24-cr26
tp
TotalView Reference Guide: version 6.3.1
227
10. Architectures
HP PA-RISC____________________________
HP PA-RISC
PA-RISC Process
Status Word
For your convenience, TotalView interprets the bit settings of the PA-RISC
Processor Status Word. You can edit the value of this word and set some of
the bits listed in the following table.
Table 17: PA-RISC Processor
Status Word
Value
W
E
S
T
H
L
N
X
B
C
V
M
O
F
R
Q
P
D
I
C/B
PA-RISC FloatingPoint Registers
The PA-RISC has 32 floating-point registers. The first four are used for status and exception registers. The rest can be addressed as 64-bit doubles,
as two 32-bit floats in the right and left sides of the register, or even-odd
pairs of registers as 128-bit extended floats.
Table 18: PA-RISC FloatingPoint Registers
Register
status
er1-er7
fr4-fr31
Bit Setting
0x0000000008000000
0x0000000004000000
0x0000000002000000
0x0000000001000000
0x0000000000800000
0x0000000000400000
0x0000000000200000
0x0000000000100000
0x0000000000080000
0x0000000000040000
0x0000000000020000
0x0000000000010000
0x0000000000000080
0x0000000000000020
0x0000000000000010
0x0000000000000008
0x0000000000000004
0x0000000000000002
0x0000000000000001
0x000000FF0000FF00
Description
Status register
Exception registers
Double floating-point
registers
fr4l-fr31l
Left half floating-point
registers
Right half floating-point
fr4r-fr31r
registers
fr4/fr5-fr30/ Extended floating-point
fr31
register pairs
Meaning
64-bit addressing enable
Little-endian enable
Secure interval timer
Taken branch flag
Higher-privilege transfer trap enable
Lower-privilege transfer trap enable
Nullify current instruction
Data memory break disable
Taken branch flag
Code address translation enable
Divide step correction
High-priority machine check mask
Ordered references
Performance monitor interrupt unmask
Recovery counter enable
Interrupt state collection enable
Protection identifier validation enable
Data address translation enable
External interrupt unmask
Carry/borrow bits
Data Type
<int>
<int>
<double>
Edit
no
no
yes
Specify in
Dive Expression
no
$status
no
$er1-$er7
yes
$fr4-$fr31
<float>
yes
yes
$fr4l-$fr31l
<float>
yes
yes
$fr4r-$fr31r
<extended> yes
yes
$fr4_fr5$fr30_fr31
The floating-point status word controls the arithmetic rounding mode,
enables user-level traps, enables floating-point exceptions, and indicates
the results of comparisons.
228
Chapter 10: Architectures
IBM Power
Table 19: Floating-Point
Status Word Use
Type
Rounding Mode
Exception Enable and
Exception Flag Bits
Comparison Fields
Value
0
1
2
3
V
Z
O
U
I
C
CQ
Other Flags
PA-RISC FloatingPoint Format
T
D
This field occupies the same bits as the CA field
and is undefined after a targeted compare.
Compare array; an array of seven compare bits,
each of which contains the result of the most
recent compare instruction targeting that bit.
This field occupies the same bits as the CQ field
and is undefined after a queued compare.
Delayed trap
Denormalized as zero
The PA-RISC processor supports the IEEE floating-point format.
IBM Power ____________________________
This section contains the following information:
■
■
■
■
■
Power General Registers
Power MSR Register
Power Floating-Point Registers
Power FPSCR Register
Using the Power FPSCR Register
The Power architecture supports the IEEE floating-point format.
Power General
Registers
TotalView displays Power general registers in the Stack Frame Pane of the
Process Window. The following table describes how TotalView treats each
general register, and the actions you can take with each register.
TotalView Reference Guide: version 6.3.1
229
10. Architectures
CA
Meaning
Round to nearest
Round toward zero
Round toward +infinity
Round toward –infinity
Invalid operation
Division by zero
Overflow
Underflow
Inexact result
Compare bit; contains the result of the most
recent queued compare instruction.
Compare queue; contains the result of the
second-most recent queued compare through
the twelfth-most recent queued compare. Each
queued compare instruction shifts the CQ field
right one bit and copies the C bit into the leftmost position.
IBM Power
Table 20: Power GeneralPurpose Integer Registers
Data Type
<int>
<int>
<int>
<int>
<int>
<code>[]
<int>
Edit
yes
yes
yes
yes
yes
no
yes
Dive
yes
yes
yes
yes
no
yes
no
Specify in
Expression
$r0
$sp
$rtoc
$r3 – $r31
$inum
$pc
$srr1
<int>
<int>
<int>
<int>
yes
yes
yes
yes
no
no
no
no
$lr
$ctr
$cr
$xer
<int>
<int>
<int>
<int>
yes
yes
yes
yes
no
no
no
no
SG10 – SG15 Segment registers 10 –15 <int>
yes
no
SCNT
SAD1
SAD2
SCD1
SCD2
TID
yes
yes
yes
yes
yes
yes
no
no
no
no
no
no
$dar
$mq
$msr
$seg0 –
$seg9
$sg10 –
$sg15
$scnt
$sad1
$sad2
$scd1
$scd2
Register
R0
SP
RTOC
R3 – R31
INUM
PC
SRR1
Description
General register 0
Stack pointer
TOC pointer
General registers 3 – 31
Program counter
Machine status save/
restore register
Link register
LR
CTR
Counter register
CR
Condition register
XER
Integer exception
register
DAR
Data address register
MQ
MQ register
MSR
Machine state register
SEG0 – SEG9 Segment registers 0 – 9
SS_COUNT
SS_ADDR 1
SS_ADDR 2
SS_CODE 1
SS_CODE 2
<int>
<int>
<int>
<int>
<int>
<int>
Power MSR
Register
For your convenience, TotalView interprets the bit settings of the Power
MSR register. You can edit the value of the MSR and set it to any of the bit
settings outlined in the following table.
Table 21: Power MSR
Register Bit Settings
Value
0x80000000000000000
0x0000000000040000
0x0000000000020000
0x0000000000010000
0x0000000000008000
0x0000000000004000
0x0000000000002000
0x0000000000001000
0x0000000000000800
0x0000000000000400
0x0000000000000200
0x0000000000000100
0x0000000000000040
0x0000000000000020
230
Bit Setting
SF
POW
TGPR
ILE
EE
PR
FP
ME
FE0
SE
BE
FE1
IP
IR
Meaning
Sixty-four bit mode
Power management enable
Temporary GPR mapping
Exception little-endian mode
External interrupt enable
Privilege level
Floating-point available
Machine check enable
Floating-point exception mode 0
Single-step trace enable
Branch trace enable
Floating-point exception mode 1
Exception prefix
Instruction address translation
Chapter 10: Architectures
IBM Power
Value
0x0000000000000010
0x0000000000000002
0x0000000000000001
Power FloatingPoint Registers
Table 22: Power FloatingPoint Registers
Bit Setting
DR
RI
LE
Meaning
Data address translation
Recoverable exception
Little-endian mode enable
TotalView displays the Power floating-point registers in the Stack Frame
Pane of the Process Window. The next table describes how TotalView treats
each floating-point register, and the actions you can take with each register.
Register
F0 – F31
FPSCR2
Edit
yes
Dive
yes
Specify in
Expression
$f0 – $f31
yes
no
$fpscr
yes
no
$fpscr2
Power FPSCR
Register
For your convenience, TotalView interprets the bit settings of the Power
FPSCR register. You can edit the value of the FPSCR and set it to any of the
bit settings outlined in the following table.
Table 23: Power PFSCR
Register Bit Settings
Value
0x80000000
0x40000000
0x20000000
Bit Setting
FX
FEX
VX
0x10000000
0x08000000
0x04000000
0x02000000
0x01000000
OX
UX
ZX
XX
VXSNAN
0x00800000
VXISI
Meaning
Floating-point exception summary
Floating-point enabled exception summary
Floating-point invalid operation exception
summary
Floating-point overflow exception
Floating-point underflow exception
Floating-point zero divide exception
Floating-point inexact exception
Floating-point invalid operation exception for
SNaN
Floating-point invalid operation exception:
0x00400000
VXIDI
Floating-point invalid operation exception:
0x00200000
VXZDZ
0x00100000
VXIMZ
0x00080000
VXVC
0x00040000
0x00020000
0x00010000
0x00008000
0x00004000
FR
FI
FPRF=(C)
FPRF=(L)
FPRF=(G)
Floating-point invalid operation exception: 0
/0
Floating-point invalid operation exception:
∞*∞
Floating-point invalid operation exception:
invalid compare
Floating-point fraction rounded
Floating-point fraction inexact
Floating-point result class descriptor
Floating-point less than or negative
Floating-point greater than or positive
TotalView Reference Guide: version 6.3.1
∞−∞
∞/∞
231
10. Architectures
FPSCR
Description
Data Type
Floating-point registers <double>
0 – 31
Floating-point status
<int>
register
Floating-point status
<int>
register 2
IBM Power
Value
0x00002000
0x00001000
0x00011000
0x00009000
0x00008000
0x00018000
0x00012000
0x00002000
0x00014000
Bit Setting
FPRF=(E)
FPRF=(U)
FPRF=(QNAN)
FPRF=(-INF)
FPRF=(-NORM)
FPRF=(-DENORM)
FPRF=(-ZERO)
FPRF=(+ZERO)
FPRF=(+DENORM)
0x00004000
0x00005000
0x00000400
FPRF=(+NORM)
FPRF=(+INF)
VXSOFT
0x00000200
VXSQRT
0x00000100
VXCVI
0x00000080
VE
0x00000040
0x00000020
0x00000010
0x00000008
0x00000004
0x00000000
0x00000001
0x00000002
0x00000003
OE
UE
ZE
XE
NI
RN=NEAR
RN=ZERO
RN=PINF
RN=NINF
Meaning
Floating-point equal or zero
Floating-point unordered or NaN
Quiet NaN; alias for FPRF=(C+U)
-Infinity; alias for FPRF=(L+U)
-Normalized number; alias for FPRF=(L)
-Denormalized number; alias for FPRF=(C+L)
-Zero; alias for FPRF=(C+E)
+Zero; alias for FPRF=(E)
+Denormalized number; alias for
FPRF=(C+G)
+Normalized number; alias for FPRF=(G)
+Infinity; alias for FPRF=(G+U)
Floating-point invalid operation exception:
software request
Floating-point invalid operation exception:
square root
Floating-point invalid operation exception:
invalid integer convert
Floating-point invalid operation exception
enable
Floating-point overflow exception enable
Floating-point underflow exception enable
Floating-point zero divide exception enable
Floating-point inexact exception enable
Floating-point non-IEEE mode enable
Round to nearest
Round toward zero
Round toward +infinity
Round toward –infinity
Using the Power FPSCR Register
On AIX, if you compile your program to catch floating-point exceptions
(IBM compiler –qflttrap option), you can change the value of the FPSCR
within TotalView to customize the exception handling for your program.
For example, if your program inadvertently divides by zero, you can edit the
bit setting of the FPSCR register in the Stack Frame Pane. In this case, you
would change the bit setting for the FPSCR to include 0x10 (as shown in
Table 23) so that TotalView traps the “divide by zero” exception. The string
displayed next to the FPSR register should now include ZE. Now, when your
program divides by zero, it receives a SIGTRAP signal, which will be caught
by TotalView. See “Handling Signals” in Chapter 3 of the TotalView Users Guide
for more information. If you did not set the bit for trapping divide by zero
or you did not compile to catch floating-point exceptions, your program
would not stop and the processor would set the ZX bit.
232
Chapter 10: Architectures
Intel IA-64
Intel IA-64
This section contains the following information:
■
■
■
■
■
■
■
Intel IA-64 General
Registers
Intel IA-64 General Registers
“IA-64 Processor Status Register Fields (PSR)” on page 234
“Current Frame Marker Register Fields (CFM)” on page 235
“Register Stack Configuration Register Fields (RSC)” on page 235
“Previous Function State Register Fields (PFS)” on page 235
“Floating Point Registers” on page 235
“Floating Point Status Register Fields” on page 236
TotalView displays the IA-64 general registers in the Stack Frame Pane of
the Process Window. The following table describes how TotalView treats
each general register, and the actions you can take with each.
Table 24: Intel IA-64
General Registers
Register
r0
r1
r2-r31
r31-r127
b0-b7
ip
cfm
psr
rsc
bsp
bspstore
rnat
ccv
unat
fpsr
pfs
lc
Description
register 0
global pointer
static general registers
stacked general registers
(all may not be valid)
branch registers
instruction pointer
current frame marker
processor status register
register stack
configuration register (AR
16)
Data Type
<long>
<long>
<long>
<long>
Edit
N
N
Y
Y
Dive
Y
Y
Y
Y
in expression
$r0
$r1
$r2-$r31
$r32-$r127
<code>[]
<code>[]
<long>
<long>
<long>
Y
Y
Y
Y
Y
$b0-$b7
$ip
$cfm
$psr
$rsc
rse backing store pointer
(AR 17)
rse backing store pointer
for memory stores (AR
18)
rse NAT collection
register (AR 19)
compare and exchange
value register (AR 32)
user NAT collection
register (AR 36)
floating point status
register (AR 40)
previous function state
(AR 64)
loop count register (AR
65)
<long>
Y
N
Y
Y
Y
(N on
HP-UX)
Y
Y
$bsp
<long>
N
Y
$bspstore
<long>
Y
Y
$rnat
<long>
Y
Y
$ccv
<long>
Y
Y
$unat
<long>
Y
Y
$fpsr
<long>
Y
Y
$pfs
<long>
Y
Y
$lc
TotalView Reference Guide: version 6.3.1
233
10. Architectures
The descriptions in this section are taken (almost verbatim) from the “Intel Itanium
Architecture Software Developer’s Manual. Volume 1: Application Architecture”. This
was revision 2.0, printed in December 2001.
Intel IA-64
Register
ec
pr
nat
Description
epilog count register (AR
66)
predication registers
(packed)
nat registers (packed)
Data Type
<long>
Edit
Y
Dive in expression
Y
$ec
<long>
Y
Y
$pr
<long>
Y
Y
$nat
All general registers r32-r127 may not be valid in a given stack frame.
IA-64 Processor
Status Register
Fields (PSR)
These fields control memory access alignment, byte-ordering, and userconfigured performance monitors. It also records the modification state of
floating-point registers.
Bit
1
2
3
4
5
13
14
15
17
18
19
20
21
22
23
24
25
26
27
33:32
34
35
36
37
38
39
40
42:41
43
44
45
234
Field
be
up
ac
mfl
mfh
ic
i
pk
dt
dfl
dfh
sp
pp
di
si
db
lp
tb
rt
cpl
is
mc
it
id
da
dd
ss
ri
ed
bn
ia
Meaning
big-endian enable
user performance monitor enable
alignment check
lower (f2-f31) floating point registers written
upper (f32-f127) floating point registers written
interruption collection
interrupt bit
protection key enable
data address translation
disabled lower floating point register set
disabled upper floating point register set
secure performance monitors
privileged performance monitor enable
disable instruction set transition
secure interval timer
debug breakpoint fault
lower privilege transfer trap
taken branch trap
register stack translation
current privilege level
instruction set
machine check abort mask
instruction address translation
instruction debug fault disable
disable data access and dirty-bit faults
data debug fault disable
single step enable
restart instruction
exception deferral
register bank
disable instruction access-bit faults
Chapter 10: Architectures
Intel IA-64
Current Frame
Marker Register
Fields (CFM)
Bit Range
6:0
13:7
17:14
Field
sof
sol
sor
24:18
31:25
37:32
rrb.gr
rrb.fr
rrb.pr
Bit Range
1:0 00
Size of rotating portion of stack frame (number of
rotating registers is sor*8
Register rename base for general registers
Register rename base for float registers
Register rename base for predicate registers
Field
mode
Meaning
enforced lazy
1:0 01
load intensive
1:0 10
store intensive
eager
pl
be
loadrs
RSE privilege level
RSE endian mode (0=little endian, 1=big endian)
RSE load distance to tear point
The Previous Function State register (PFS) contains multiple fields: Previous
Frame Marker (pfm), Previous Epilog Count (pec), and Previous Privilege
Level (ppl). These values are copied automatically on a call from the CFM
register, Epilog Count Register (EC), and PSR.cpl (Current Privilege Level in
the Processor Status Register) to accelerate procedure calling.
Value
37:0
57:52
63:62
Floating Point
Registers
Size of locals portion of stack frame
The Register Stack Configuration (RSC) Register is a 64-bit register used to
control the operation of the Register Stack Engine (RSE).
1:0 11
3:2
4
29:16
Previous Function
State Register
Fields (PFS)
Meaning
Size of frame
10. Architectures
Register Stack
Configuration
Register Fields
(RSC)
Each general register stack frame is associated with a frame marker. The
frame maker describes the state of the general register stack. The Current
Frame Marker (CFM) holds the state of the current stack frame.
Bit Setting
pfm
pec
ppl
Meaning
previous frame marker
previous epilog count
previous privilege level
The IA-64 contains 128 floating-point registers. The first two are read only.
Register
f0
f1
f2-f31
f32-f127
Description
float register 0
float register 1
lower float registers
upper float registers
TotalView Reference Guide: version 6.3.1
Data Type
<long>
<long>
<long>
<long>
Edit
N
N
Y
Y
Dive
Y
Y
Y
Y
Specify in
Expression
$f0
$f1
$f2-$f31
$f32-$f127
235
Intel x86
Floating Point
Status Register
Fields
The Floating-Point Status Register (FPSR) contains the dynamic control and
status information for floating-point operations. There is one main set of
control and status information and three alternate sets.
Field
traps.vd
traps.dd
Bits
0
1
traps.zd
traps.od
traps.ud
traps.id
sfo
sf1
sf2
sf3
2
3
4
5
18:6
31:19
44:32
57:45
Meaning
Invalid Operation Floating-Point Exception fault disabled
Denormal/Unnormal Operating Floating-Point Exception
fault disabled
Zero Divide Floating-Point Exception trap disabled
Overflow Floating-Point Exception trap disabled
Underflow Floating-Point Exception trap disabled
Inexact Floating-Point Exception trap disabled
main status field
alternate status field 1
alternate status field 2
alternate status field 3
Here is a description of the FPSR status field descriptions.
Table 25: Floating-point
Status Register Status Field
Description
Bits
0
1
3:2
5:4
6
7
8
9
10
11
12
Field
ftz
wre
pc
rc
td
v
d
z
o
u
i
meaning
flush-to-zero mode
widest range exponent
precision control
rounding control
traps disabled
invalid operation
denormal/unnormal operand
zero divide
overflow
underflow
inexact
Intel x86
This section contains the following information:
■
■
■
■
■
Intel x86 General Registers
Intel x86 Floating-Point Registers
Intel x86 FPCR Register
Using the Intel x86 FPCR Register
Intel x86 FPSR Register
The Intel x86 processor supports the IEEE floating-point format.
Intel x86 General
Registers
236
TotalView displays the Intel x86 general registers in the Stack Frame Pane of
the Process Window. The following table describes how TotalView treats
each general register, and the actions you can take with each register.
Chapter 10: Architectures
Intel x86
Table 26: Intel x86 General
Registers
Description
General registers
Selector registers
Instruction pointer
Streaming SIMD
Extension: left half
Streaming SIMD
Extension: right half
Data Type
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<void>
<code>[]
<void>
<void>
<void>
<void>
<long long>
Edit
yes
yes
yes
yes
yes
yes
yes
yes
no
no
no
no
no
no
no
no
no
no
no
no
yes
<long long> yes
Dive
yes
yes
yes
yes
yes
yes
yes
yes
no
no
no
no
no
no
no
yes
no
no
no
no
yes
yes
Specify in
Expression
$eax
$ecx
$edx
$ebx
$ebp
$esp
$esi
$edi
$cs
$ss
$ds
$es
$fs
$gs
$eflags
$eip
$fault
$temp
$inum
$ecode
$xmm0_l
...
$xmm7_l
$xmm0_h
...
$xmm7_h
The Pentium III and 4 have 8 128-bit registers that are used by SSE and SSE2
instructions. TotalView displays these as 16 64-bit registers. These registers can be used
in the following ways: 16 bytes, 8 words, 2 long longs, 4 floating point, 2 double, or a
single 128-bit value. TotalView shows each of these hardware registers as two
<long long> registers. To change the type, dive and then edit the type in the data window to be an array of the type you wish. For example, cast it to “<char>[16]”,
“<float>[4], and so on.
Intel x86 FloatingPoint Registers
Table 27: Intel x86 FloatingPoint Registers
TotalView displays the x86 floating-point registers in the Stack Frame Pane
of the Process Window. The next table describes how TotalView treats each
floating-point register, and the actions you can take with each register.
Register
ST0
ST1
ST2
ST3
ST4
ST5
Description
ST(0)
ST(1)
ST(2)
ST(3)
ST(4)
ST(5)
TotalView Reference Guide: version 6.3.1
Data Type
<extended>
<extended>
<extended>
<extended>
<extended>
<extended>
Edit
yes
yes
yes
yes
yes
yes
Dive
yes
yes
yes
yes
yes
yes
Specify in
Expression
$st0
$st1
$st2
$st3
$st4
$st5
237
10. Architectures
Register
EAX
ECX
EDX
EBX
EBP
ESP
ESI
EDI
CS
SS
DS
ES
FS
GS
EFLAGS
EIP
FAULT
TEMP
INUM
ECODE
XMM0_L
...
XMM7_L
XMM0_H
...
XMM7_H
Intel x86
Register
ST6
ST7
FPCR
FPSR
FPTAG
FPIOFF
FPISEL
FPDOFF
FPDSEL
Intel x86 FPCR
Register
Description
ST(6)
ST(7)
Floating-point control
register
Floating-point status
register
Tag word
Instruction offset
Instruction selector
Data offset
Data selector
Data Type
<extended>
<extended>
<void>
Edit
yes
yes
yes
Dive
yes
yes
no
Specify in
Expression
$st6
$st7
$fpcr
<void>
no
no
$fpsr
<void>
<void>
<void>
<void>
<void>
no
no
no
no
no
no
no
no
no
no
$fptag
$fpioff
$fpisel
$fpdoff
$fpdsel
For your convenience, TotalView interprets the bit settings of the FPCR and
FPSR registers.
You can edit the value of the FPCR and set it to any of the bit settings outlined in the next table.
Table 28: Intel x86 FPCR
Register Bit Settings
Value
RC=RN
RC=RRC=R+
RC=RZ
PC=SGL
PC=DBL
PC=EXT
EM=PM
EM=UM
EM=OM
EM=ZM
EM=DM
EM=IM
Bit Setting
0x0000
0x2000
0x4000
0x6000
0x0000
0x0080
0x00c0
0x0020
0x0010
0x0008
0x0004
0x0002
0x0001
Meaning
To nearest rounding mode
Toward negative infinity rounding mode
Toward positive infinity rounding mode
Toward zero rounding mode
Single-precision rounding
Double-precision rounding
Extended-precision rounding
Precision exception enable
Underflow exception enable
Overflow exception enable
Zero-divide exception enable
Denormalized operand exception enable
Invalid operation exception enable
Using the Intel x86 FPCR Register
You can change the value of the FPCR within TotalView to customize the
exception handling for your program.
For example, if your program inadvertently divides by zero, you can edit the
bit setting of the FPCR register in the Stack Frame Pane. In this case, you
would change the bit setting for the FPCR to include 0x0004 (as shown in
Table 26) so that TotalView traps the “divide-by-zero” bit. The string displayed next to the FPCR register should now include EM=(ZM). Now, when
your program divides by zero, it receives a SIGFPE signal, which you can
catch with TotalView. See “Handling Signals” in Chapter 3 of the TotalView
Users Guide for information on handling signals. If you did not set the bit for
trapping divide by zero, the processor would ignore the error and set the
EF=(ZE) bit in the FPSR.
238
Chapter 10: Architectures
Intel x86
The bit settings of the Intel x86 FPSR register are outlined in the following
table.
Table 29: Intel x86 FPSR
Register
Value
TOP=<i>
B
C0
C1
C2
C3
ES
SF
EF=PE
EF=UE
EF=OE
EF=ZE
EF=DE
EF=IE
Intel x86 MXSCR
Register
This register contains control and status information for the SSE registers.
Some of the bits in this register are editable. You cannot dive in these values.
Bit Setting
0x3800
0x8000
0x0100
0x0200
0x0400
0x4000
0x0080
0x0040
0x0020
0x0010
0x0008
0x0004
0x0002
0x0001
Meaning
Register <i> is top of FPU stack
FPU busy
Condition bit 0
Condition bit 1
Condition bit 2
Condition bit 3
Exception summary status
Stack fault
Precision exception
Underflow exception
Overflow exception
Zero divide exception
Denormalized operand exception
Invalid operation exception
The bit settings of the Intel x86 MXCSR register are outlined in the following table.
Table 30: Intel x86 MXCSR
Register Bit Settings
Value
FZ
RC=RN
RC=RRC=R+
RC=RZ
EM=PM
EM=UM
EM=OM
EM=ZM
EM=DM
EM=IM
DAZ
EF=PE
EF=UE
EF=OE
EF=ZE
EF=DE
EF=IE
Bit Setting
0x8000
0x0000
0x2000
0x4000
0x6000
0x1000
0x0800
0x0400
0x0200
0x0100
0x0080
0x0040
0x0020
0x0010
0x0008
0x0004
0x0002
0x0001
TotalView Reference Guide: version 6.3.1
Meaning
Flush to zero
To nearest rounding mode
Toward negative infinity rounding mode
Toward positive infinity rounding mode
Toward zero rounding mode
Precision mask
Underflow mask
Overflow mask
Divide-by-zero mask
Denormal mask
Invalid operation mask
Denormals are zeros
Precision flag
Underflow flag
Overflow flag
Divide-by-zero flag
Denormal flag
Invalid operation flag
239
10. Architectures
Intel x86 FPSR
Register
SGI MIPS
SGI MIPS _____________________________
This section contains the following information:
■
■
■
■
■
■
MIPS General Registers
MIPS SR Register
MIPS Floating-Point Registers
MIPS FCSR Register
Using the MIPS FCSR Register
MIPS Delay Slot Instructions
The MIPS processor supports the IEEE floating-point format.
MIPS General
Registers
TotalView displays the MIPS general-purpose registers in the Stack Frame
Pane of the Process Window. The following table describes how TotalView
treats each general register, and the actions you can take with each register.
Programs compiled with either –64 or –n32 have 64-bit registers. TotalView
uses <long> for –64 compiled programs and <long long> for –n32 compiled programs.
Table 31: MIPS General
(Integer) Registers
Register
ZERO
AT
V0 – V1
A0 – A7
T0 – T3
S0 – S7
T8 – T9
K0 – K1
GP
SP
S8
RA
MDLO
MDHI
CAUSE
EPC
240
Description
Always has the value 0
Reserved for the assembler
Function value registers
Argument registers
Temporary registers
Saved registers
Temporary registers
Reserved for the operating
system
Global pointer
Stack pointer
Hardware frame pointer
Return address register
Multiply/Divide special
register, holds leastsignificant bits of multiply,
quotient of divide
Multiply/Divide special
register, holds mostsignificant bits of multiply,
remainder of divide
Cause register
Program counter
Data Type
<long>
<long>
<long>
<long>
<long>
<long>
<long>
<long>
Edit
no
yes
yes
yes
yes
yes
yes
yes
Dive
no
yes
yes
yes
yes
yes
yes
yes
Specify in
Expression
$zero
$at
$v0 – $v1
$a0 – $a7
$t0 – $t3
$s0 – $s7
$t8 – $t9
$k1 – $k2
<long>
<long>
<long>
<code>[]
<long>
yes
yes
yes
no
yes
yes
yes
yes
yes
yes
$gp
$sp
$s8
$ra
$mdlo
<long>
yes
yes
$mdhi
<long>
yes
<code>[] no
yes
yes
$cause
$epc
Chapter 10: Architectures
SGI MIPS
Register
SR
VFP
Description
Status register
Virtual frame pointer
Data Type Edit
<long>
no
<long>
no
Specify in
Dive Expression
no
$sr
no
$vfp
The virtual frame pointer is a
software register that
TotalView maintains. It is not
an actual hardware register.
TotalView computes the VFP
as part of stack backtrace.
MIPS SR Register
For your convenience, TotalView interprets the bit settings of the SR register as outlined in the next table.
Table 32: MIPS SR Register
Value
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000018
0x00000000
0x00000020
0x00000040
0x00000080
0x0000FF00
0x00010000
0x00020000
0x00040000
0x00080000
0x00100000
0x00200000
0x00400000
0x02000000
0x04000000
0x08000000
0x10000000
0x20000000
0x40000000
0x80000000
MIPS FloatingPoint Registers
TotalView displays the MIPS floating-point registers in the Stack Frame
Pane of the Process Window. Here is a table that describes how TotalView
treats each floating-point register, and the actions you can take with each
register.
TotalView Reference Guide: version 6.3.1
Meaning
Interrupt enable
Exception level
Error level
Supervisor mode
User mode
Undefined (implemented as User mode)
Kernel mode
User mode 64-bit addressing
Supervisor mode 64-bit addressing
Kernel mode 64-bit addressing
Interrupt Mask value is i
Disable cache parity/ECC
Reserved
Cache hit
Non-maskable interrupt has occurred
Soft reset or NMI exception
TLB shutdown has occurred
Bootstrap vectors
Reverse-Endian bit
Additional floating-point registers enabled
Reduced power mode
Coprocessor 0 usable
Coprocessor 1 usable
Coprocessor 2 usable
MIPS IV instructions usable
10. Architectures
Bit Setting
IE
EXL
ERL
S
U
U
K
UX
SX
KX
IM=i
DE
CE
CH
NMI
SR
TS
BEV
RE
FR
RP
CU0
CU1
CU2
XX
241
SGI MIPS
Table 33: MIPS FloatingPoint Registers
Register
F0, F2
F1 – F3,
F4 – F11
F12 – F19
F20 – F23
F24 – F31
FCSR
Description
Data Type Edit
Hold results of floating-point <double> yes
type function; $f0 has the
real part, $f2 has the
imaginary part
Temporary registers
<double> yes
Pass single- or doubleprecision actual arguments
Temporary registers
Saved registers
FPU control and status
register
Specify in
Dive Expression
yes $f0, $f2
<double> yes
yes
$f1 – $f3,
$f4 – $f11
$f12 – $f19
<double> yes
<double> yes
<int>
yes
yes
yes
no
$f20 – $f23
$f24 – $f31
$fcsr
yes
MIPS FCSR
Register
For your convenience, TotalView interprets the bit settings of the MIPS
FCSR register. You can edit the value of the FCSR and set it to any of the bit
settings outlined in the following table.
Table 34: MIPS FCSR
Register Bit Settings
Value
RM=RN
RM=RZ
RM=RP
RM=RM
flags=(I)
flags=(U)
flags=(O)
flags=(Z)
flags=(V)
enables=(I)
enables=(U)
enables=(O)
enables=(Z)
enables=(V)
cause=(I)
cause=(U)
cause=(O)
cause=(Z)
cause=(V)
cause=(E)
FCC=(0/c)
Bit Setting
0x00000000
0x00000001
0x00000002
0x00000003
0x00000004
0x00000008
0x00000010
0x00000020
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00002000
0x00004000
0x00008000
0x00010000
0x00020000
0x00800000
FS
FCC=(1)
FCC=(2)
FCC=(3)
FCC=(4)
FCC=(5)
0x01000000
0x02000000
0x04000000
0x08000000
0x10000000
0x20000000
242
Meaning
Round to nearest
Round toward zero
Round toward positive infinity
Round toward negative infinity
Flag=inexact result
Flag=underflow
Flag=overflow
Flag=divide by zero
Flag=invalid operation
Enables=inexact result
Enables=underflow
Enables=overflow
Enables=divide by zero
Enables=invalid operation
Cause=inexact result
Cause=underflow
Cause=overflow
Cause=divide by zero
Cause=invalid operation
Cause=unimplemented
FCC=Floating-Point Condition Code 0;
c=Condition bit
Flush to zero
FCC=Floating-Point Condition Code 1
FCC=Floating-Point Condition Code 2
FCC=Floating-Point Condition Code 3
FCC=Floating-Point Condition Code 4
FCC=Floating-Point Condition Code 5
Chapter 10: Architectures
SGI MIPS
Value
FCC=(6)
FCC=(7)
Bit Setting
0x40000000
0x80000000
Meaning
FCC=Floating-Point Condition Code 6
FCC=Floating-Point Condition Code 7
Using the MIPS FCSR Register
You can change the value of the MIPS FCSR register within TotalView to customize the exception handling for your program.
MIPS Delay Slot
Instructions
On the MIPS architecture, jump and branch instructions have a “delay
slot”. This means that the instruction after the jump or branch instruction
is executed before the jump or branch is executed.
In addition, there is a group of “branch likely” conditional branch instructions in which the instruction in the delay slot is executed only if the
branch is taken.
The MIPS processors execute the jump or branch instruction and the delay
slot instruction as an indivisible unit. If an exception occurs as a result of
executing the delay slot instruction, the branch or jump instruction is not
executed, and the exception appears to have been caused by the jump or
branch instruction.
This behavior of the MIPS processors affects both the TotalView instruction
step command and TotalView breakpoints.
The TotalView instruction step command will step both the jump or branch
instruction and the delay slot instruction as if they were a single instruction.
If a breakpoint is placed on a delay slot instruction, execution will stop at
the jump or branch preceding the delay slot instruction, and TotalView will
not know that it is at a breakpoint. At this point, attempting to continue
the thread that hit the breakpoint without first removing the breakpoint will
cause the thread to hit the breakpoint again without executing any instructions. Before continuing the thread, you must remove the breakpoint. If
you need to reestablish the breakpoint, you might then use the instruction
step command to execute just the delay slot instruction and the branch.
A breakpoint placed on a delay slot instruction of a branch likely instruction
will be hit only if the branch is going to be taken.
TotalView Reference Guide: version 6.3.1
243
10. Architectures
For example, if your program inadvertently divides by zero, you can edit the
bit setting of the FCSR register in the Stack Frame Pane. In this case, you
would change the bit setting for the FCSR to include 0x400 (as shown in
Table 31). The string displayed next to the FCSR register should now
include enables=(Z). Now, when your program divides by zero, it receives a
SIGFPE signal, which you can catch with TotalView. See “Setting Up a Debugging Session” in the TotalView Users Guide for more information.
Sun SPARC
Sun SPARC ____________________________
This section has the following information:
■
■
■
■
■
SPARC General Registers
SPARC PSR Register
SPARC Floating-Point Registers
SPARC FPSR Register
Using the SPARC FPSR Register
The SPARC processor supports the IEEE floating-point format.
SPARC General
Registers
Table 35: SPARC General
Registers
TotalView displays the SPARC general registers in the Stack Frame Pane of
the Process Window. The following table describes how TotalView treats
each general register, and the actions you can take with each register.
Data Type
<int>
<int>
<int>
Edit
no
yes
yes
Dive
no
yes
yes
Specify in
Expression
$g0
$g1 – $g7
$o0 – $o5
<int>
<int>
<int>
<int>
yes
yes
yes
yes
yes
yes
yes
yes
$sp
$o7
$l0 – $l7
$i0 – $i5
FP
I7
PSR
Y
WIM
TBR
Description
Global zero register
Global registers
Outgoing parameter
registers
Stack pointer
Temporary register
Local registers
Incoming parameter
registers
Frame pointer
Return address
Processor status register
Y register
WIM register
TBR register
<int>
<int>
<int>
<int>
<int>
<int>
yes
yes
yes
yes
no
no
yes
yes
no
yes
no
no
$fp
$i7
$psr
$y
PC
nPC
Program counter
Next program counter
<code>[]
<code>[]
no
no
yes
yes
$pc
$npc
Register
G0
G1 – G7
O0 – O5
SP
O7
L0 – L7
I0 – I5
SPARC PSR
Register
For your convenience, TotalView interprets the bit settings of the SPARC
PSR register. You can edit the value of the PSR and set some of the bits outlined in the following table.
Table 36: SPARC PSR
Register Bit Settings
Value
ET
PS
S
EF
EC
C
V
244
Bit Setting
0x00000020
0x00000040
0x00000080
0x00001000
0x00002000
0x00100000
0x00200000
Meaning
Traps enabled
Previous supervisor
Supervisor mode
Floating-point unit enabled
Coprocessor enabled
Carry condition code
Overflow condition code
Chapter 10: Architectures
Sun SPARC
Value
Z
N
SPARC FloatingPoint Registers
Table 37: SPARC FloatingPoint Registers
Bit Setting
0x00400000
0x00800000
Meaning
Zero condition code
Negative condition code
TotalView displays the SPARC floating-point registers in the Stack Frame
Pane of the Process Window. The next table describes how TotalView treats
each floating-point register, and the actions you can take with each register.
Register
F0, F1,
F0_F1
F2 – F31
FPSR
Data Type
<float>
Edit
no
<float>
yes
Specify in
Dive Expression
yes $f0, $f1,
$f0_f1
yes $f2– $f31
<double> no
yes
<double> yes
yes
<int>
no
no
$f0, $f1,
$f0_f1
$2 –
$f30_f31
$fpcr
<int>
yes
no
$fpsr
10. Architectures
F0, F1,
F0_F1
F0/F1 –
F30/F31
FPCR
Description
Floating-point registers (f
registers), used singly
Floating-point registers (f
registers), used singly
Floating-point registers (f
registers), used as pairs
Floating-point registers (f
registers), used as pairs
Floating-point control
register
Floating-point status register
TotalView allows you to use these registers singly or in pairs, depending on
how they are used by your program. For example, if you use F1 by itself, its
type is <float>, but if you use the F0/F1 pair, its type is <double>.
SPARC FPSR
Register
For your convenience, TotalView interprets the bit settings of the SPARC
FPSR register. You can edit the value of the FPSR and set it to any of the bit
settings outlined in the following table.
Table 38: SPARC FPSR
Register Bit Settings
Value
CEXC=NX
CEXC=DZ
CEXC=UF
CEXC=OF
CEXC=NV
AEXC=NX
AEXC=DZ
AEXC=UF
AEXC=OF
AEXC=NV
EQ
LT
GT
UN
QNE
NONE
IEEE
Bit Setting
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000020
0x00000040
0x00000080
0x00000100
0x00000200
0x00000000
0x00000400
0x00000800
0x00000c00
0x00002000
0x00000000
0x00004000
TotalView Reference Guide: version 6.3.1
Meaning
Current inexact exception
Current divide by zero exception
Current underflow exception
Current overflow exception
Current invalid exception
Accrued inexact exception
Accrued divide by zero exception
Accrued underflow exception
Accrued overflow exception
Accrued invalid exception
Floating-point condition =
Floating-point condition <
Floating-point condition >
Floating-point condition unordered
Queue not empty
Floating-point trap type None
Floating-point trap type IEEE Exception
245
Sun SPARC
Value
UFIN
UIMP
SEQE
NS
TEM=NX
TEM=DZ
TEM=UF
TEM=OF
TEM=NV
EXT
Bit Setting
0x00008000
0x0000c000
0x00010000
0x00400000
0x00800000
0x01000000
0x02000000
0x04000000
0x08000000
0x00000000
SGL
DBL
NEAR
ZERO
PINF
NINF
0x10000000
0x20000000
0x00000000
0x40000000
0x80000000
0xc0000000
Meaning
Floating-point trap type Unfinished FPop
Floating-point trap type Unimplemented FPop
Floating-point trap type Sequence Error
Nonstandard floating-point FAST mode
Trap enable mask – Inexact Trap Mask
Trap enable mask – Divide by Zero Trap Mask
Trap enable mask – Underflow Trap Mask
Trap enable mask – Overflow Trap Mask
Trap enable mask – Invalid Operation Trap Mask
Extended rounding precision – Extended
precision
Extended rounding precision – Single precision
Extended rounding precision – Double precision
Rounding direction – Round to nearest (tie-even)
Rounding direction – Round to 0
Rounding direction – Round to +Infinity
Rounding direction – Round to –Infinity
Using the SPARC FPSR Register
The SPARC processor does not catch floating-point errors by default. You
can change the value of the FPSR within TotalView to customize the exception handling for your program.
For example, if your program inadvertently divides by zero, you can edit the
bit setting of the FPSR register in the Stack Frame Pane. In this case, you
would change the bit setting for the FPSR to include 0x01000000 (as shown
in Table 35) so that TotalView traps the “divide by zero” bit. The string displayed next to the FPSR register should now include TEM=(DZ). Now, when
your program divides by zero, it receives a SIGFPE signal, which you can
catch with TotalView. See “Handling Signals” in Chapter 3 of the TotalView
Users Guide for more information. If you did not set the bit for trapping
divide by zero, the processor would ignore the error and set the AEXC=(DZ)
bit.
246
Chapter 10: Architectures
Index
Symbols
A
# scoping separator character 25, 29, 70
$newval variable in watchpoints 110
$oldval variable in watchpoints 110
$stop built-in function 82
%B server launch replacement character 202
%C server launch replacement character 202
%D path name replacement character 203
%H hostname replacement character 203
%L host and port replacement character 203
%N line number replacement character 203
%P password replacement
character 203
%S source file replacement character 203
%t1 file replacement character 203
%t2 file replacement character 203
%V verbosity setting replacement character
204
.totalview/lib_cache subdirectory 32
.tvd files 147
/proc file system 216
= symbol for PC of current
buried stack frame 71
> symbol for PC 71
@ symbol for action point
71
–a option to totalview
command 191
ac, see dactions command
acquiring processes 169
Action Point > Save All
command 163
action point identifiers 19,
43
action points
default for newly created 158
deleting 37, 127, 137,
141, 151
disabling 19, 39, 39
displaying 19
enabling 19
identifiers 19
information about 19
loading 19
loading automatically
194
loading saved information 19
reenabling 43
saving 19
saving information
about 19
scope of what is
stopped 159
sharing 158
stopping when reached
178
actionpoint command 127
actionpoint properties 127
actions, see dactions command
add verb, image command
139
adding group members 53
TotalView Reference Guide: version 6.3.1
adding groups 52
address property 127
advancing by steps 99
after_checkpointing options 34
AIX
compiling on 208
linking C++ to dbfork
library 213
linking to dbfork library 212
swap space 218
alias command 16
aliases
default 16
removing 123
Alpha
architecture 225
floating-point registers
226
FPCR register 226
general registers 225
append, see dlappend command
appending to CLI variable
lists 69
architectures 159
Alpha 225
HP PA-RISC 227
Intel IA-64 233
Intel-x86 236
MIPS 240
PowerPC 229
SPARC 244
arenas 47, 78
ARGS variable 88, 92, 155
ARGS_DEFAULT variable
88, 92, 155
arguments
command line 92
default 155
247
B
for totalview command 191
for tvdsvr command
200
arrays
automatic dereferencing 161
number of elements
displayed 160
arriving at barrier 26
as, see dassign command
ask on dlopen option 221
ask_on_dlopen option 222
ask_on_dlopen variable
160
assemble, displaying symbolically 170
assembler instructions,
stepping 102
assign, see dassign command
assigning string values 21
assigning values 21
asynchronous execution
44
at, see dattach command
attach, see dattach command
attaching to parallel processes 23
attaching to processes 23
attaching, using PIDs 23
auto_array_cast_bounds
variable 160
auto_array_cast_enabled
variable 161
auto_deref_in_all_c variable 161
auto_deref_in_all_fortran
variable 161
auto_deref_initial_c variable 161
auto_deref_initial_fortran
variable 162
auto_deref_nested_c variables 162
auto_deref_nested_fortran
variables 162
auto_load_breakpoints
variables 162
auto_read_symbol_at_sto
p variable 163
auto_save_breakpoints
variable 163
automatic dereferencing of
arrays 161
automatically attaching to
processes 175
248
B
b, see dbreak command
ba, see dbarrier command
–background option 192
back-tick analogy 18
barrier breakpoint 26
barrier is satisfied 156, 164
barrier, see dbarrier command
BARRIER_STOP_ALL variable 25, 27, 155
barrier_stop_all variables
163
BARRIER_STOP_WHEN_D
ONE variable 25, 156
barrier_stop_when_done
variables 163
barriers 25, 26
arriving 26
creating 26
scope of what is
stopped 155
what else is stopped 25
baud rate, specifying 201
baw, see dbarrier command
–bg option 192
–bkeepfile option 213
blocking command input
109
blocking input 109
break, see dbreak command
breakpoints
automatically loading
162
barrier 25
default file in which set
30
defined 29
popping Process Window 184
setting at functions 30
stopping all processes
at 29
temporary 106
triggering 29
breakpoints file 20, 162,
163
bt, see dbreak command
bulk launch 203
bulk_launch_base_timeout
variables 164
bulk_launch_enabled variables 164
bulk_launch_incr_timeout
variables 164
bulk_launch_string variables 164
bulk_launch_tmpfile1_hea
der_ line variables
164
bulk_launch_tmpfile1_host
_ lines variables 165
bulk_launch_tmpfile1_trail
er_ line variables 165
bulk_launch_tmpfile2_
header_line variables 165
bulk_launch_tmpfile2_host
_ lines variables 165
bulk_launch_tmpfile2_trail
er_ line variables 165
buried stack frame 70
C
C language escape characters 21
C shell 217
C++
demangler 192
including libdbfork.h
213
C++ demangler 167
c_type_strings variables
165
cache, flushing 32
cache, see dcache command
call stack 108
displaying 116
call tree saved position 182
–callback option 199, 200
–callback_host 200
–callback_ports 200
callbacks 173
after loading a program 176
when opening the CLI
175
capture command 18, 120
case sensitive searching
176
Cast dereferenced C pointers to array string
checkbox 161
CGROUP variable 156
changing CLI variables 95
changing dynamic context
108
changing focus 47
changing value of program
variable 21, 34, 54,
67, 80, 91, 104, 106
chase_mouse variables
180
checkpoint, see dcheckpoint command
checkpointing
preserving IDs 33
process state 33
Index
C
reattaching to parallel
33
restarting 90
scope 33
CLI commands
action points 14
alias 16
aliases 187
capture 18, 120
dactions 19
dassign 21
dattach 23
dbarrier 25
dbreak 29
dcache 32
dcheckpoint 4, 33
dcont 36
ddelete 37
ddetach 38
ddisable 39
ddlopen 40
ddown 42
dec2hex 130
denable 43
dflush 44, 82
dfocus 47
dga 49
dgo 51
dgroups 52
dhalt 57
dheap 58
dhold 67
dkill 68
dlappend 69
dlist 70
dlist command 158
dload 73
dmstat 74
dnext 76
dnexti 78
dout 80
dprint 82
dptsets 86
drerun 88
drestart 8, 90
drun 68, 92
drun, reissuing 93
dset 95
dstatus 97
dstep 99
dstepi 102
dunhold 104
dunset 105
duntil 106
dup 108
dwait 109
dwatch 110
dwhat 113
dwhere 116
dworker 118
TotalView Reference Guide: version 6.3.1
environment 13
executing immediately
193
execution control 14
exit 119
focus of 187
help 120
initialization 13
overview 13, 125
program information
14
quit 121
responding to 145
stty 122
summary 3
termination 13
TV::actionpoint 127
TV::dll command 41,
129
TV::errorCodes 131
TV::expr 82, 132
TV::focus_groups 134
TV::focus_processes
135
TV::focus_threads 136
TV::group 137
TV::hex2dec 138
TV::image 139
TV::process 141
TV::read_symbols command 144
TV::respond 145
TV::source_process_st
artup 147
TV::thread 149
TV::type 151
unalias 123
CLI variables
ARGS 88, 92, 155
ARGS_DEFAULT 88,
92, 155
ask_on_dlopen 160
auto_array_cast_boun
ds 160
auto_array_cast_enabl
ed 161
auto_deref_in_all_c
161
auto_deref_in_all_fortr
an 161
auto_deref_initial_fortr
an 162
auto_deref_intial_c
161
auto_deref_nested_c
162
auto_deref_nested_for
tran 162
auto_load_breakpoints
162
auto_read_symbol_at_
stop 163
auto_save_breakpoints
163
BARRIER_STOP_ALL
25, 27, 155
barrier_stop_all 163
BARRIER_STOP_WHEN
_ DONE 25
BARRIER_STOP_WHEN
_DONE 156
barrier_stop_when_do
ne 163
bulk_launch_base_tim
eout 164
bulk_launch_enabled
164
bulk_launch_incr_time
out 164
bulk_launch_string 164
bulk_launch_tmpfile1_
header_line 164
bulk_launch_tmpfile1_
host_ lines 165
bulk_launch_tmpfile1_
trailer_ line 165
bulk_launch_tmpfile2_
header_ line 165
bulk_launch_tmpfile2_
host_ lines 165
bulk_launch_tmpfile2_
trailer_ line 165
c_type_strings 165
CGROUP 156
changing 95
chase_mouse 180
comline_patch_area_b
ase 165
comline_path_area_le
ngth 165
COMMAND_EDITING
156
command_editing 166
compile_expressions
166
compiler_vars 166
copyright_string 167
current_cplus_demangl
er 167
current_fortran_deman
gler 167
data_format_double
167
data_format_ext 169
data_format_int16 169
data_format_int32 169
data_format_int64 169
data_format_int8 169
data_format_single
169
249
C
data_format_singlen
169
dbfork 169
default value for 95
deleting 95
display_assembler_sy
mbolically 170
display_font_dpi 181
dll_ignore_prefix 170
dll_read_all_symbols
170
dll_read_loader_symbo
ls_only 170
dll_read_no_symbols
171
dll_stop_suffix 171
dpvm 171
dump_core 171
dynamic 172
editor_launch_string
172
enabled 181
errorCodes 82
EXECUTABLE_PATH
24, 71, 157
fixed_font 181
fixed_font_family 181
fixed_font_size 181
font 181
force_default_cplus_de
mangler 172
force_default_f9x_dem
angler 172
force_window_position
181
geometry_call_tree 182
geometry_cli 182
geometry_globals 182
geometry_help 182
geometry_memory_sta
ts 182
geometry_message_qu
eue 183
geometry_message_qu
eue_graph 183
geometry_modules 183
geometry_process 183
geometry_ptset 183
geometry_pvm 183
geometry_root 184
geometry_thread_obje
cts 184
geometry_variable 184
geometry_variable_stat
s 184
global_typenames 172
GROUP 157
GROUPS 23, 73, 157
ignore_control_c 173
250
image_load_callbacks
173
in_setup 173
kcc_classes 173
keep_search_dialog
184
kernel_launch_string
174
library_cache_directory
174
LINES_PER_SCREEN
157
local_interface 174
local_server 174
local_server_launch_st
ring 174
MAX_LIST 70, 158
message_queue 174
parallel 175
parallel_attach 175
parallel_stop 175
platform 175
pop_at_breakpoint
184
pop_on_error 185
process_load_callback
s 176
PROMPT 158
PTSET 158
pvm 176
save_window_pipe_or_
filename 176
search_case_sensitive
176
server_launch_enabled
176
server_launch_string
176
server_launch_timeout
177
SGROUP 158
SHARE_ACTION_POIN
T 158
share_action_point
177
signal_handling_mode
177
single_click_dive_enab
led 185
source_pane_tab_widt
h 178
spell_correction 178
STOP_ALL 29, 112, 159
stop_all 178
stop_relatives_on_pro
c_error 179
suffix 179
TAB_WIDTH 70, 159
THREADS 159
TOTAL_VERSION 159
TOTALVIEW_ROOT_PA
TH 159
TOTALVIEW_TCLLIB_P
ATH 159
ttf 179
ui_font 185
ui_font_family 185
ui_font_size 185
user_threads 179
using_color 185
using_text_color 185
using_title_color 185
VERBOSE 159
version 179, 185
viewing 95
visualizer_launch_enab
led 179
visualizer_launch_strin
g 180
visualizer_max_rank
180
warn_step_throw 180
WGROUP 160
wrap_on_search 180
CLI, activated from GUI flag
181
closes shared libraries 129
clusterid property 141
co, see dcont command
code, displaying 70
color
foreground 193
comline_patch_area_base
variables 165
comline_path_area_length
variables 165
command
Tools > Dynamic Libraries 40
command aliases 187
command arguments 155
command focus 47, 187
command input, blocking
109
command line arguments
92
command output 18
command prompt 158
command summary 3
COMMAND_EDITING variable 156
command_editing variables 166
commands
totalview 191
tvdsvr
syntax and use 199
user-defined 16
commands verb
Index
D
actionpoint command
127, 129
expr command 132
group command 137
image command 139
process command 141
thread command 149
type command 151
commands, responding to
145
compile_expressions variables 166
–compiler_vars option 192
compiler_vars variables
166
compilers, KCC 173
compiling
debugging symbols 207
–g compiler option 207
on HP Tru64 UNIX 207,
208
on HP-UX 208, 209
on IRIX 210
on SunOS 210
options 207
conditional watchpoints
110
connection directory 203
console output for tvdsvr
200
console output redirection
192
cont, see dcont command
continuation_sig property
149
control group variable 156
control group, stopping
179
control list element 157
copyright_string variables
167
core
dumping for TotalView
193
when needing to debug TotalView itself 171
core files, loading 23
count property 137
creating a group 52, 54
creating barrier breakpoints 26
creating commands 16
creating new process objects 73
creating threads 51
Ctrl+C, ignoring 173
Ctrl+D to exit CLI 119, 121
current data size limit 217
TotalView Reference Guide: version 6.3.1
current frame marker register
Intel IA-64 235
current list location 42
current_cplus_demangler
variables 167
current_fortran_demangler
variables 167
D
d, see ddown command
d_process object 216
dactions command 19
dassign command 21
data format, presentation
styles 167
data size 74
data size limit in C shell
217
data_format_double variables 167
data_format_ext variables
169
data_format_int16 variables 169
data_format_int32 variables 169
data_format_int64 variables 169
data_format_int8 variables 169
data_format_single variables 169
data_format_stringlen variables 169
data_size property 140
datatype incompatibilities
21
dattach command 23
dbarrier command 25
dbfork library
linking with 211
syntax 192
–dbfork option 192
dbfork variables 169
dbreak command 29
dcache command 32
dcheckpoint command 4,
33
preserving IDs 33
process 33
reattaching to parallel
33
scope 33
dcont command 36
ddelete command 37
ddetach command 38
ddisable command 39
ddl_read_all_symbols variable 170
ddlopen command 40
ddown command 42
de, see ddelete command
deactivating action points
39
deadlocks at barriers 27
–debug_file option 192,
200
debugger server 176, 199
debugging remote systems
32
debugging session, ending
119
dec2hex command 130
default aliases 16
default arguments 92, 155
modifying 93
default focus 47
default value of variables,
restoring 105
deferred reading, shared library symbols 144
defining the current focus
158
delay slot instructions for
MIPS 243
delete verb, expr command
132
delete, see ddelete command
deleting action points 37,
127, 137, 141, 151
deleting cache 32
deleting CLI variables 95
deleting groups 52, 53
deleting variables 105
demangler
C++ 167
forcing use 172
Fortran 167
overriding 192, 194
–demangler option 192
denable command 43
dereferencing
C pointers automatically 161
C structure pointers
automatically 162
Fortran pointers automatically 162
values automatically
161
dereferencing values automatically 161
det, see ddetach command
detach, see ddetach command
detaching from processes
38
dflush command 44, 82
251
E
dfocus command 47
dga command 49
dgo command 51
dgroups command 52
–add 53
–delete 53
–intersect 53
–list 53
–new 54
–remove 54
dhalt command 57
dheap command 58
dhold command 67
di, see ddisable command
directory search paths 157
disable, see ddisable command
disabling action points 19,
39
disabling PVM support 195
display call stack 116
–display option 193
display_assembler_ symbolically variables
170
display_font_dpi variables
181
displaying
code 70
current execution location 116
error message information 159
help information 120
information on a name
113
lines 158
values 82
displaying expressions 82
diving, single click 185
dkill command 68
dlappend command 69
dlist command 70, 158
dlist, number of lines displayed 158
dll command 129
DLL Do Query on Load list
221
DLL Don’t Query on Load
list 222
dll_ignore_prefix variables
170
dll_read_loader_symbols_
only 170
dll_read_no_symbols variables 171
dll_stop_suffix variables
171
dload command 73
dlopen 40, 221
252
ask when loading 160
dmstat command 74
dnext command 76
dnexti command 78
done property 132
double-precision data format 167
dout command 80
down, see ddown command
dpid 156
dpid property 149
dpids property 140
dprint command 82
dptsets command 86
–dpvm option 193, 200
dpvm variables 171
drerun command 88
drestart command 8, 90
attaching automatically 90
attaching to processes
90
process state 90
drun command 68, 92
poe issues 93
reissuing 93
dset command 95
dstatus command 97
dstep command 99
iterating over focus 99
dstepi command 102
duhtp, see dunhold command
duid property 141, 149
–dump_core option 193
dump_core variables 171
dunhold command 104
dunset command 105
duntil command 106
group operations 106
dup command 108
dwait command 109
dwatch command 110
dwhat command 113
dwhere command 116
levels 158
dworker command 118
dynamic library support
limitations 223
dynamic variables 172
dynamically loaded libraries 221
E
editor_launch_string variables 172
eliminating tab processing
70
en, see denable command
enable, see denable command
enabled property 127
enabled variables 181
enabling action points 19,
43
enabling PVM support 195
ending debugging session
119
enum_values property 151
environment variables
LD_LIBRARY_PATH
212, 213, 214
error message information
159
ERROR state 160
errorCodes command 82,
131
errorCodes variable 131
errors, raising 131
escape characters 21
evaluating functions 82
evaluation points, see
dbreak
evaluations, suspended,
flushing 44
exception data on HP
Tru64 211
exception subcodes 82
exception, warning when
thrown 180
executable property 141
EXECUTABLE_PATH variable 24, 71, 157
executing as one instruction 78
executing as one statement 76
executing assembler instructions 102
executing source lines 99
execution
halting 57
resuming 36
execution location, displaying 116
execve() 211
calling 192
catching 169
exit command 119
expr command 82, 132
expression property 127,
132
expression system
AIX 223
Alpha 223
IRIX 224
expression values, printing
82
expressions, compiling 166
Index
H
extensions for file names
179
F
f, see dfocus command
fatal errors 217
–fg option 193
file name extensions 179
files, libdbfork.h 213
fixed_font variables 181
fixed_font_family variables
181
fixed_font_size variables
181
floating point data format
double-precision 167
extended floating point
169
single-precision 169
SPARC 229
floating point registers
Intel IA-64
Intel IA-64
floating point
registers
235
floating point status register
Intel IA-64 236
flush, see dflush command
flushing cache 32
flushing suspended evaluations 44
focus
see also dfocus command
commands 187
default 47
defining 158
focus_groups command
134
focus_processes command
135
focus_threads command
136
focus_threads property
132
font variables 181
fonts 181
fixed 181
ui 181, 185
ui font family 185
ui font size 185
force_default_cplus_ demangler variables
172
force_default_f9x_ demangler variables 172
force_window_position
variables 181
TotalView Reference Guide: version 6.3.1
–foreground option 193
fork() 211
calling 192
catching 169
Fortran demangler 167
functions
evaluating 82
setting breakpoints at
30
G
g, see dgo command
general registers
Intel IA-64 233
geometry_call_tree variables 182
geometry_cli position 182
geometry_cli variables 182
geometry_globals variables 182
geometry_help variables
182
geometry_memory_stats
variables 182
geometry_message_queue
variables 183
geometry_message_queue
_ graph variables 183
geometry_modules variables 183
geometry_process variables 183
geometry_ptset variables
183
geometry_pvm variables
183
geometry_root variables
184
geometry_thread_objects
variables 184
geometry_variable variables 184
geometry_variable_stats
variables 184
get verb
actionpoint command
127, 129
expr command 132
group command 137
image command 139
process command 141
thread command 149
type command 151
Global Arrays 49
setting language for
display 49
global_typenames variables 172
–global_types option 194
go, see dgo command
goal breakpoint 99
gr, see dgroups command
group command 137
group members, stopping
flag 159
group of interest 99
GROUP variable 157
group width stepping behavior 100
groups
accessing properties
137
adding 52
adding members 53
creating 52, 54
deleting 52, 53
intersecting 52, 53
listing 52, 53
naming 53
placing processes in 24
removing 54
removing members 52
returning list of 134
setting properties 137
GROUPS variable 23, 73,
157
groups, see dgroups command
H
h, see dhalt command
halt, see dhalt command
halting execution 57
handling signals 196
handling user-level (M:N)
thread packages 179
heap debugging
backtraces 58
enabling notification
61
monitoring events 61
notifying when errors
occur 58
heap size 74
heap_size property 141
held property 141, 149
help command 120
help window position 182
hex2dec command 138
hexadecimal conversion
130
hold, see dhold command
holding processes 67
holding threads 26, 67
host ports 200
hostname
expansion 203
for tvdsvr 200
replacement 203
hostname property 141
253
I
HP Tru64 UNIX
/proc file system 216
linking to dbfork library 211
swap space 217
hp, see dhold command
HP-UX
architecture 227
shared libraries 220
swap space 217
ht, see dhold command
htp, see dhold command
I
I/O redirection 88, 92
id property 127, 132, 137,
140, 141, 149, 151
ignore_control_c variables
173
ignoring libraries by prefix
193
image browser window position 182
image command 139
image_id property 151
image_ids property 142
image_load_callbacks variables 173
images
getting properties 140
setting properties 140
in_setup variables 173
inet interface name 174
INFO state 160
information on a name 113
initialization file 123
initially_suspended_proces
s property 132
input, blocking 109
inserting working threads
118
instructions, stepping 102
integer (64-bit) data format 169
integer data format
32-bit 169
8-bit 169
integer data formats
16-bit 169
Intel IA-64
current frame marker
register 235
floating point status
register 236
general registers 233
previous function state
register 235
processor status register 234
254
register stack configuration register 235
Intel IA-64 architecture 233
Intel-x86
architecture 236
floating-point registers
237
FPCR register 238
using 238
FPSR register 239
general registers 236
interface name for server
174
intersecting groups 52, 53
IRIX
/proc file system 216
linking to dbfork library 214
swap space 218
is_dll property 140
J
job_t::launch 216
K
k, see dkill command
–kcc_classes option 194
kcc_classes variables 173
keep_search_dialog variables 184
kernel_launch_string variables 174
keys, remapping 223
keysym 223
kill, see dkill command
killing processes 68
L
l, see dlist command
language property 127, 151
lappend, see dlappend
command
launch string
for editor 172
for server (Sun only)
174
for Visualizer 180
Launch Strings page 180
launching
local server 174
processes 92
single process sever
launch string 176
tvdsvr 199
Visualizer 179
–lb option 194
length property 127, 151
levels for dwhere 158
levels, moving down 42
libdbfork.a 211
libdbfork.h file 213
libraries
dbfork 192
ignoring by prefix 193
loading by suffix 171
loading symbols from
172
not loading based on
prefix 170
shared 219
library cache, flushing 32
library_cache_directory
variables 174
line property 127
LINES_PER_SCREEN variable 157
linking to dbfork library 211
AIX 212
C++ and dbfork 213
HP Tru64 UNIX 211
IRIX 214
SunOS 5 214
Linux swap space 218
list location 42
list, see dlist command
listing groups 52, 53
using a regular expression 53
listing lines 158
lo, see dload command
load and loadbind 221
load, see dload command
loading
action points 19, 194
programs 73
symbols from shared libraries 172
tvd files 147
loading action point information 19
loading libraries 170, 171
loading shared libraries
129
local_interface variables
174
local_server variables 174
local_server_launch_string
variables 174
lockstep list element 157
lookup verb, image command 139
lookup_keys verb, image
command 139
M
machine instructions, stepping 102
manager property 149
manager threads, running
99
Index
P
managing shared libraries
129
mangler, overriding 192,
194
MAX_LIST variable 70, 158
maxdsiz_64 217
maximum data segment
size 217
Maximum permissible rank
field 180
member_type property 137
member_type_values
property 137
members property 137
memory
data size 74
heap 74
stack 74
text size 74
memory statistics window
position 182
memory use 74
message queue graph window position 183
message queue window
position 183
message verbosity variable
159
–message_queue option
194
message_queue variables
174
MIPS
architecture 240
delay slot instructions
243
FCSR register 242
using 243
floating-point registers
241
general registers 240
SR register 241
mkswap command 218
modules window position
183
more processing 82
more prompt 120, 157
mounting /proc file system
216
–mqd option 194
multiprocess programs, attaching to processes
24
N
n, see dnext command
name property 140, 151
name, information about
113
namespaces 95
TotalView Reference Guide: version 6.3.1
TV:: 95
TV::GUI:: 95
using wildcards 95
naming the host 200
nested subroutines, stepping out of 80
new groups 54
newval variable in watchpoints 110
next, see dnext command
nexti, see dnexti command
ni, see dnexti command
nil, see dnexti command
niw, see dnexti command
nl, see dnext command
–nlb option 194
–no_ask_on_dlopen option 222
–no_compiler_vars option
192
–no_dbfork option 192
–no_dpvm option 193
–no_dump_core option
193
–no_dynamic option 220
–no_global_types option
194
–no_kcc_classes option
194
–no_message_queue option 194
–no_mqd option 195
–no_parallel option 195
–no_pvm option 195
–no_user_threads option
197
nodeid property 142
nw, see dnext command
O
oldval variable in watchpoints 110
Open (or raise) process
window at breakpoint
checkbox 184
Open process window on
error signal check
box 185
opening shared libraries 40
options
tvdsvr
–callback 199
–serial 199
–server 199
–set_pw 200
–user_threads 197
ou, see dout command
oul, see dout command
out, see dout command
ouw, see dout command
P
p, see dprint command
p/t expressions 86
p/t set browser position
183
panes, width 178
–parallel option 195
parallel processes, attaching to 23
parallel runtime libraries
175
parallel variables 175
Parallel Virtual Machine
171, 176, 193
parallel_attach variables
175
parallel_stop variables 175
password checking 202
passwords 201, 202
generated by tvdsvr
199
–patch_area_base option
195
–patch_area_length option 195
PATH environment variable
for tvdsvr 199
pc property 149
Plant in share group checkbox 158, 177
platform variables 175
pop_at_breakpoint variables 184
pop_on_error variables
185
popping Process Window
on error variable 185
port 4142 201
port number 200
for tvdsvr 200
replacement 203
searching 201
–port option 200
ports on host 200
PowerPC
architecture 229
floating-point registers
231
FPSCR register 231
using the 232
FPSCR register, using
232
general registers 229
MSR register 230
preserving IDs in checkpoint 33
previous function state
register
Intel IA-64 235
print, see dprint command
255
Q
printing expression values
82
printing information about
current state 97
printing registers 83
printing slices 83
printing variable values 82
proc file system problems
216
Process > Startup command 51
process barrier breakpoint, see barrier
breakpoint
process command 141
process groups, see groups
process information, saving 34
process list element 157
process objects, creating
new 73
process statistics 74
process width stepping behavior 99
process window position
183
process/thread sets
changing 47
process_load_callbacks
variable 176
process_set checkpoint
options 34
processes
attaching to 23, 73
automatically acquiring 169
automatically attaching to 175
current status 97
destroyed when exiting CLI 119, 121
detaching from 38
holding 67
killing 68
properties 141
releasing 104
releasing control 38
restarting 88, 92
returning list of 135
starting 88, 92
terminating 68
processor status register
Intel IA-64 234
program control groups,
placing processes in
24
program stepping 99
program variable, changing value 21, 34, 54,
67, 80, 91, 104, 106
256
programs, loading 73
PROMPT variable 158
prompting when screen is
full 82
properties
address 127
clusterid 141
continuation_sig 149
count 137
data_size 140
done 132
dpid 149
dpids 140
duid 141, 149
enabled 127
enum_values 151
executable 141
expression 127, 132
focus_threads 132
heap_size 141
held 141, 149
hostname 141
id 127, 132, 137, 140,
141, 149, 151
image_id 151
image_ids 142
initially_suspended_pr
ocess 132
is_dll 140
language 127, 151
length 127, 151
line 127
manager 149
member_type 137
member_type_values
137
members 137
name 140, 151
nodeid 142
pc 149
prototype 151
rank 151
result 133
satisfaction_group 127
share 127
sp 149
stack_size 142
stack_vm_size 142
state 142, 149
state_values 142, 149
status 133
stop_when_done 128
stop_when_hit 128
struct_fields 151
syspid 142
systid 149
text_size 140, 142
threadcount 142
threads 142
type 137
type_transformations
140
type_values 128, 137
vm_size 142
properties verb
actionpoint command
127, 129
expr command 132
group command 137
image command 139
process command 141
thread command 149
type command 151
prototype property 151
PTSET variable 158
ptsets, see dptsets
PVM 201
–pvm option 195, 201
pvm variables 176
pvm window position 183
pxdb command 220
pxdb64 command 221
Q
qualifying symbol names
70
quit command 121
quotation marks 21
R
–r option 196
r, see drun command
raising errors 131
rank property 151
read_symbols command
144
reading action points file
19
reading symbols 144, 163,
170, 171
reenabling action points 43
register stack configuration register
Intel IA-64 235
registers
Alpha FPCR 226
floating-point
Alpha 226
Intel-x86 237
MIPS 241
PowerPC 231
SPARC 245
general
Alpha 225
Intel-x86 236
MIPS 240
PowerPC 229
SPARC 244
Intel-x86 FPCR 238
using the 238
Intel-x86 FPSR 239
Index
S
MIPS FCSR 242
using the 243
MIPS SR 241
Power FPSCR 231
Power MSR 230
PowerPC FPSCR 231
using 232
PowerPC FPSCR,
using 232
PowerPC MSR 230
printing 83
SPARC FPSR 245
SPARC FPSR, using 246
SPARC PSR 244
registers, using in evaluations 30
release 156
releasing control 38
releasing processes and
threads 25, 104
remapping keys 223
remote debugging, tvdsvr
command syntax 199
–remote option 195
remote systems
debugging 32
removing
aliases 123
group member 52
groups 54
variables 105
worker threads 118
remsh command 202
replacement characters
202
replacing tabs with spaces
159
rerun, see rerun command
respond 145
restart, see drestart command
restarting processes 88, 92
restoring variables to default values 105
result property 133
resuming execution 29, 36,
51, 68
returning error information
131
root path 159
of TotalView 159
Root Window position 184
routines, stepping out of
80
rr, see drerun command
rsh command, with tvdsvr
176
RTLD_GLOBAL 40
RTLD_LAZY 40
RTLD_LOCAL 40
TotalView Reference Guide: version 6.3.1
RTLD_NOW 40
run, see drun command
running to an address 106
S
s, see dstep command
satisfaction set 26, 156,
164
satisfaction_group property 127
save_window_pipe_or_
filename variables
176
saved position
Call Tree Window 182
CLI Window 182
Help Window 182
Image Browser Window
182
Memory Statistics Window 182
Message Queue Graph
Window 183
Message Queue window 183
Modules Window 183
P/T Set Browser Window 183
Process Window 183
PVM Window 183
Root Window 184
Thread Objects Window 184
Variable Window 184
saving action point information 19
saving action points 19
saving process information 34
screen size 157
search dialog, remaining
displayed 184
search paths 157
search_case_sensitive variables 176
–search_port option 201
searching
case sensitive 176
wrapping 180
serial line connection 201
–serial option 196, 199,
201
server launch command
202
–server option 199, 201
server_launch_enabled
variables 176
server_launch_string variables 176
server_launch_timeout
variables 177
servers, number of 203
set verb
actionpoint command
127
group command 137
image command 139
process command 141
thread command 149
type command 151
set, see dset command
–set_pw option 200, 201
–set_pws option 202
setting lines between more
prompts 157
setting terminal properties
122
SGROUP variable 158
share groups
share group variable
158
share list element 157
share property 127
SHARE_ACTION_POINT
variable 158
share_action_point variables 177
share_in_group flag 158
shared libraries 219
closing 129
deferred reading 144
HP-UX 220
information about 129
managing 129
manually loading 40
reading deferred symbols 144
reading symbols 163,
170, 171
shared libraries, loading
symbols from 172
–shm option 196, 197
showing current status 97
showing Fortran compiler
variables 166
si, see dstepi command
SIGINT 173
–signal_handling_mode
option 196
signal_handling_mode
variable 177
–signal_handling_mode
option 196
signals, handling in
TotalView 196
sil, see dstepi command
SILENT state 160
single process server
launch 176
257
T
single_click_dive_enabled
variables 185
siw, see dstepi command
sl, see dstep command
slices, printing 83
source code, displaying 70
source_pane_tab_width
variables 178
source_process_startup
command 147
sourcing tvd files 147
sp property 149
SPARC
architecture 244
floating-point format
229
floating-point registers
245
FPSR register 245
using 246
general registers 244
PSR register 244
spell_correction variable
178
st, see dstatus command
stack frame 70
moving down through
42
stack memory 74
stack movements 108
stack, unwinding 44
stack_size property 142
stack_vm_size property
142
starting a process 88, 92
Startup command 51
start-up file, tvdinit.tvd 16
state property 142, 149
state_values property 142,
149
status property 133
status, see dstatus command
stderr redirection 88, 92
stdin redirection 88, 92
stdout redirection 88, 92
step, see dstep command
stepi, see dstepi command
stepping
group width behavior
100
machine instructions
78, 102
process width behavior 99
see also dnext command, dnexti
command, dstep
command, and
dstepi command
258
thread width behavior
99
warning when exception thrown 180
stop group breakpoint 30
STOP_ALL variable 29,
112, 155, 159
stop_all variable 178
stop_group flag 159
stop_relatives_on_proc_
error variables 179
–stop_when_done command-line option
156
stop_when_done property
128
stop_when_hit property
128
stopped process, responding to resume commands 26
stopping execution 57
stopping group members
flag 159
stopping the control group
179
string length format 169
strings, assigning values to
21
struct_fields property 151
structure definitions in
KCC 173
stty command 122
suffixes variable 179
SunOS 5
/proc file system 216
key remapping 223
linking to dbfork library 214
swap space 219
sw, see dstep command
swap command 219
swap space 216, 219
AIX 218
HP Tru64 217
HP-UX 217
IRIX 218
Linux 218
SunOS 219
swapon command 218
symbol name qualification
70
symbols
reading 170, 171
symbols, interpreting 21
syspid property 142
system variables, see CLI
variables
systid property 149
T
tab processing 70
TAB_WIDTH variable 70,
159
tabs, replacing with spaces 159
target processes 57
terminating 68
target property 152
terminal properties, setting 122
terminating debugging session 119
terminating processes 68
text size 74
text_size property 140, 142
thread barrier breakpoint,
see barrier breakpoint
thread command 149
thread groups, see groups
thread list element 157
thread objects window position 184
thread of interest 99, 106
thread width stepping behavior 99
threadcount property 142
threads
barriers 27
creating 51
current status 97
destroyed when exiting CLI 119, 121
getting properties 149
holding 26, 67
list variable 159
releasing 104
returning list of 136
setting properties 149
threads property 142
THREADS variable 159
Tools > Dynamic Libraries
command 40
totalview command 191
options 191
synopsis 191
syntax and use 191
TotalView Debugger Server
23, 34
TotalView executable 159
TotalView GUI version 185
TotalView version 179
totalview/lib_cache subdirectory 32
TOTALVIEW_ROOT_PATH
variable 159
TOTALVIEW_TCLLIB_PATH
variable 159
TOTALVIEW_VERSION variable 159
Index
W
triggering breakpoints 29
troubleshooting xiii
ttf variable 179
TV:: namespace 95
TV::actionpoint command
127
TV::dll command 41, 129
TV::dll_read_loader_symbo
ls_only variable 144
TV::dll_read_no_symbols
variable 144
TV::errorCodes command
131
TV::expr command 82, 132
TV::focus_groups command 134
TV::focus_processes command 135
TV::focus_threads command 136
TV::group command 137
TV::GUI:: namespace 95
TV::hex2dec command 138
TV::image command 139
TV::process command 141
TV::read_symbols command 144
TV::respond command 145
TV::source_process_startu
p command 147
TV::thread command 149
TV::type command 151
tvd files 147
TVD.breakpoints file 20,
162, 163
tvdinit.tvd start-up file 16,
123
tvdsvr command 199, 200,
202
description 199
options 200
password 199
PATH environment
variable 199
synopsis 199
use with DPVM applications 200
use with PVM applications 201
tvdsvr.conf 201
TVDSVRLAUNCHCMD environment variable 202
type command 151
type names 172
type property 128, 137,
152
type transformation variable 179
type_transformations
applied to image 140
TotalView Reference Guide: version 6.3.1
type_transformations
property 140
type_values property 128,
137, 152
U
u, see dup command
uhp, see dunhold command
uht, see dunhold command
ui_font variables 185
ui_font_family variables
185
ui_font_size variables 185
un, see duntil command
unalias command 123
unconditional watchpoints
110
undefined symbols 40
unhold, see dunhold command
unl, see duntil command
unset, see dunset command
until, see duntil command
unw, see duntil command
unwinding the stack 44
up, see dup command
–user_threads option 197
user_threads variables 179
user-defined commands 16
user-level (M:N) thread
packages 179
using quotation marks 21
using_color variables 185
using_text_color variables
185
using_title_color variables
185
V
value for newly created action points 158
values, printing 82
Variable Window position
184
variables
assigning command
output to 18
changing values 21, 34,
54, 67, 80, 91,
104, 106
default value for 95
printing 82
removing 105
watched 111
watching 110
VERBOSE variable 159
–verbosity option 197, 202
verbosity setting replacement character 204
version variables 179, 185
version, TotalView 159
vfork()
calling 192
catching 169
viewing CLI variables 95
visualizer_launch_enabled
variables 179
visualizer_launch_string
variables 180
visualizer_max_rank variables 180
vm_size property 142
W
w, see dwhere command
wa, see dwatch command
wait, see dwait command
warn_step_throw variables
180
WARNING state 160
watch, see dwatch command
watchpoints 110
$newval 110
$oldval 110
conditional 110
information not saved
20
length of 111
supported systems 110
WGROUP variable 160
wh, see dwhat command
what, see dwhat command
When barrier done, stop
value 156
When barrier hit, stop value
155
where, see dwhere command
window position, forcing
181
worker group list variable
160
worker threads 160
inserting 118
removing 118
worker, see dworker command
workers list element 157
–working_directory option
202
wot, see dworker command
wrap_on_search variables
180
259
W
260
Index