<< " border=0>

> " border=0>

15 The PGDBG Debugger

• 15.1 Definition of Terms
  • 15.1.1 Definition of Terms
  • 15.1.2 Invocation and Initialization
  • 15.1.2.1 Command-Line Arguments
  • 15.1.3 Command Language
  • 15.1.4 Commands
  • 15.1.4.1 Constants
  • 15.1.4.2 Symbols
  • 15.1.4.3 Scope Rules
  • 15.1.4.4 Register Symbols
  • 15.1.4.5 Source Code Locations
  • 15.1.4.6 Statements
  • 15.1.4.7 Events
  • 15.1.4.8 Expressions
  • 15.1.5 Debugging Fortran
  • 15.1.5.1 Arrays
  • 15.1.5.2 Operators
  • 15.1.5.3 Name of Main Routine
  • 15.1.5.4 Fortran Common Blocks
  • 15.1.6 Debugging C++
  • 15.1.7 Core Files
  • 15.1.8 Debugger Commands
• 15.2 PGDBG Commands
  • 15.2.1 Commands
  • 15.2.1.1 Process Control
  • 15.2.1.2 Events
  • 15.2.1.3 Program Locations
  • 15.2.1.4 Printing and Setting Variables
  • 15.2.1.5 Symbols and Expressions
  • 15.2.1.6 Scope
  • 15.2.1.7 Register Access
  • 15.2.1.8 Memory Access
  • 15.2.1.9 Conversions
  • 15.2.1.10 Miscellaneous
• 15.3 Commands and Registers
  • 15.3.1 Command Summary
    
  • 15.3.2 IA-32 Register Symbols
• 15.4 X-Windows Graphical User Interface
  • 15.4.1 Startup
  • 15.4.2 Main Window
  • 15.4.3 Disassembly Window
  • 15.4.4 Register Window
  • 15.4.5 Memory Window
  • 15.4.6 Custom Window

This chapter describes the PGDBG symbolic debugger. PGDBG is a symbolic debugger for Fortran, C, C++ and assembly language programs. It allows you to control the execution of programs using breakpoints and single-stepping, and lets you check the state of a program by examining variables, memory locations, and registers.

15.1 Definition of Terms

Use the -g compiler command line option to build programs for debugging. This option causes information about the symbols and source files in the program to be included in the executable file (this option also sets the optimization to level zero unless you specify -O on the command line). Programs built without -g can be debugged; however, information about types, local variables, arguments and source file line numbers is not available unless you specify -g.

15.1.1 Definition of Terms

Host

The system on which PGDBG executes. This will generally be the system where source and executable files reside, and where compilation is performed.

Target

A program being debugged.

Target Machine

The system on which a target runs. This may or may not be the same system as the host.

15.1.2 Invocation and Initialization

PGDBG is invoked using the pgdbg command as follows:

% pgdbg arguments program arg1 arg2 ... argn

where arguments may be any of the command-line arguments described in the following Section, Command-line Arguments.

The program is the name of the target program being debugged. The arguments arg1 arg2 ... argn are the command-line arguments to the target program. The debugger begins by creating a symbol table for the program. Then the program is loaded into memory.If an initialization file named .pgdbgrc exists in the current directory or in the home directory, it is opened and PGDBG executes the commands in the file. The initialization file is useful for defining common aliases, setting breakpoints and for other startup commands. If an initialization file is found in the current directory, then the initialization file in the home directory, if there is one, is ignored. However, a script command placed in the initialization file may execute the initialization file in the home directory, or execute PGDBG commands in any other file (for example in the file .dbxinit if you have a dbx debugger initialization file set up).

After processing the initialization file, PGDBG is ready to process commands. Normally, a session begins by setting one or more breakpoints, using the break, stop or trace commands, and then issuing a run command followed by cont, step, trace or next.

15.1.2.1 Command-Line Arguments

The pgdbg command accepts several command line arguments that must appear on the command line before the name of the program being debugged. The valid options are:

-dbx

Start the debugger in dbx mode.

-s startup

The default startup file is ~/.pgdbgrc. The -s option specifies an
alternate startup file startup.

-c "command"

Execute the debugger command command (command must be in double quotes) before executing the commands in the startup file.

-r

Run the debugger without first waiting for a command. If the program being debugged runs successfully, the debugger terminates. Otherwise the debugger is invoked and stops when the trap occurs.

-text

Run the debugger using a command-line interface (CLI). The default is for the debugger to launch in graphical user interface (GUI) mode.

15.1.3 Command Language

User input is processed one line at a time. Each line must begin with the name of a command and its arguments, if any. The command language is composed of commands, constants, symbols, locations, expressions, and statements.

15.1.4 Commands

Commands are named operations, which take zero or more arguments and perform some action. Commands may also return values that may be used in expressions or as arguments to other commands. Section 15.2 describes the commands in detail.

There are two command modes: pgi and dbx. The pgi command mode maintains the original PGDBG command interface. In dbx mode, the debugger uses commands with a syntax compatible with the familiar dbx debugger. Both command sets are available in both command modes, however some commands have a slightly different syntax depending on the mode. The pgienv command allows you to change modes while running the debugger.

15.1.4.1 Constants

The debugger supports C language style integer (hex, octal and decimal), floating point, character, and string constants.

15.1.4.2 Symbols

PGDBG uses the symbolic information contained in the executable object file to create a symbol table for the target program. The symbol table contains symbols to represent source files, subprograms (functions, and subroutines), types (including structure, union, pointer, array, and enumeration types), variables, and arguments. Symbol names are case-sensitive and must match the name as it appears in the object file.

The compilers add an underscore character, "_", to the beginning of each external identifier. On UNIX systems, the PGI Fortran compilers also add an underscore to the end of each external identifier. Therefore, if PGDBG is unable to locate a symbol as entered, it prepends an underscore and tries again. If that fails, it adds an underscore to the end of the name and tries again. If that fails, the leading underscore is stripped and the search is repeated. For example, if cfunc and ffunc are C and Fortran functions, respectively, then the names for the symbols in the object file are _cfunc and _ffunc_. PGDBG will accept cfunc, and _cfunc as names for _cfunc, and will accept ffunc, _ffunc, and _ffunc_ as names for _ffunc_. Note however, that due to case-sensitivity, FFUNC, _FFUNC, etc. are not accepted as names for _ffunc_.

15.1.4.3 Scope Rules

Since several symbols may have the same name, scope rules are used to bind identifiers to symbols. PGDBG uses a notion of search scope for looking up identifiers. The search scope is a symbol which represents a function, a source file, or global scope. When the user enters a name, PGDBG first tries to find the symbol in the search scope. If the symbol is not found, the containing scope, (source file, or global) is searched, and so forth, until either the symbol is located or the global scope is searched and the symbol is not found.

Normally, the search scope will be the same as the current scope, which is the function where execution is currently stopped. The current scope, and the search scope are both set to the current function each time execution of the target program stops. However, the enter command changes the search scope.

A scope qualifier operator @ allows selection of out-of-scope identifiers. For example, if f is a function with a local variable i, then:

	f@i

represents the variable i local to f. Identifiers at file scope can be specified using the quoted file name with this operator, for example:

	"xyz.c"@i

represents the variable i defined in file xyz.c.

15.1.4.4 Register Symbols

In order to provide access to the system registers, PGDBG builds symbols for them. Register names generally begin with $ to avoid conflicts with program identifiers. Each register symbol has a type associated with it, and registers are treated like global variables of that type, except that their address may not be taken. See section 15.3 for a complete list of the register symbols.

15.1.4.5 Source Code Locations

Some commands need to reference code locations. Source file names must be enclosed in double quotes. Source lines are indicated by number, and may be qualified by a quoted filename using the scope qualifier operator. Thus

break 37

sets a breakpoint at line 37 of the current source file, and

break "xyz.c"@37

sets a breakpoint at line 37 of the source file xyz.c.

A range of lines is indicated using the range operator ":". Thus,

list 3:13

lists lines 3 through 13 of the current file, and

list "xyz.c"@3:13

lists lines 3 through 13 of the source file xyz.c.

Some commands accept both line numbers and addresses as arguments. In these commands, it is not always obvious whether a numeric constant should be interpreted as a line number or an address. The description for these commands says which interpretation is used. However, the conversion commands line, and addr convert a constant to a line, or to an address respectively. For example:

{line 37}

means "line 37",

{addr 0x1000}

means "address 0x1000" , and

{addr {line 37}}

means "the address associated with line 37" , and

{line {addr 0x1000}}

means "the line associated with address 0x1000".

15.1.4.6 Statements

Although input is processed one line at a time, statement constructs allow multiple commands per line, and conditional and iterative execution. The statement constructs roughly correspond to the analogous C language constructs. Statements may be of the following forms.

Simple Statement: A command, and its arguments. For example:

print i

Block Statement: One or more statements separated by semicolons and enclosed in curly braces. Note: these may only be used as arguments to commands or as part of if or while statements. For example:

if(i>1) {print i; step }

If Statement: The keyword if followed by a parenthesized expression, followed by a block statement, followed by zero or more else if clauses, and at most one else clause. For example:

if(i>j) {print i} else if(i<j) {print j} else {print "i==j"}

While Statement: The keyword while followed by a parenthesized expression, followed by a block statement. For example:

while(i==0) {next} 

Multiple statements may appear on a line by separating them with a semicolon. For example:

break main; break xyz; cont; where

sets breakpoints in functions main and xyz, continues, and prints the new current location. Any value returned by the last statement on a line is printed.

15.1.4.7 Events

Breakpoints, watchpoints and other mechanisms used to define the response to certain conditions, are collectively called events. An event is defined by the conditions under which the event occurs, and by the action taken when the event occurs. A breakpoint occurs when execution reaches a particular address. The default action for a breakpoint is simply to halt execution and prompt the user for commands. A watchpoint occurs when the value of an expression changes. The default action is to print the new value of the expression, and prompt the user for commands. By adding a location, or a condition, the event can be limited to a particular address or function, or may occur only when the condition is true. The action to be taken when an event occurs can be defined by specifying a command list.

PGDBG supports four basic commands for defining events. Each command takes a required argument and may also take one or more optional arguments. The basic commands are break, watch, track and do. The command break takes an argument specifying a breakpoint location. Execution stops when that location is reached. The watch command takes an expression argument. Execution stops and the new value is printed when the value of the expression changes. The track command is like watch except that execution continues after the new value is printed. The do command takes a list of commands as an argument. The commands are executed whenever the event occurs.

The optional arguments bring flexibility to the event definition. They are:

at line

Event occurs at indicated line.

at addr

Event occurs at indicated address.

in function

Event occurs throughout indicated
function.

if (condition)

Event occurs only when condition is
true.

do {commands}

When event occurs execute commands.

The optional arguments may appear in any order after the required argument and should not be delimited by commas. For example:

watch i at 37 if(y>1)

This event definition says that whenever execution is at line 37, and the value of i has changed since the last time execution was at line 37, and y is greater than 1, stop and print the new value of i.

do {print xyz} in f 

This event definition says that at each line in the function f print the value of xyz.

break func1 if (i==37) do {print a[37]; stack} 

This event definition says that each time the function func1 is entered and i is equal to 37, then the value of a[37] should be printed, and a stack trace should be performed.

Event commands that do not explicitly define a location will occur at each source line in the program. For example:

do {where}

prints the current location at the start of each source line, and

track a.b

prints the value of a.b at the start of each source line if the value has changed.

Events that occur at every line can be useful, but to perform them requires single-stepping the target program (this may slow execution considerably). Restricting an event to a particular address causes minimal impact on program execution speed, while restricting an event to a single function causes execution to be slowed only when that function is executed.

PGDBG supports instruction level versions of several commands ( for example breaki, watchi, tracki, and doi). The basic difference in the instruction version is that these commands will interpret integers as addresses rather than line numbers, and events will occur at each instruction rather than at each line.

When multiple events occur at the same location, all event actions will be taken before the prompt for input. Defining event actions that resume execution is allowed but discouraged, since continuing execution may prevent or defer other event actions. For example:

break 37 do {continue} 
break 37 do {print i} 

This creates an ambiguous situation. It's not clear whether i should ever be printed.

Events only occur after the continue and run commands. They are ignored by step, next, call, etc.

Identifiers and line numbers in events are bound to the current scope when the event is defined. For example:

break 37 

sets a breakpoint at line 37 in the current file.

track i 

will track the value of whatever variable i is currently in scope. If i is a local variable then it is wise to add a location modifier (at or in) to restrict the event to a scope where i is defined.

Scope qualifiers can also specify lines or variables that are not currently in scope.

15.1.4.8 Expressions

The debugger supports evaluation of expressions composed of constants, identifiers, commands if they return values, and operators. Table 15-1 shows the C language operators that are supported. The operator precedence is the same as in the C language.

To use a value returned by a command in an expression, the command and arguments must be enclosed in curly braces. For example:

break {pc}+8

invokes the pc command to compute the current address, adds 8 to it, and sets a breakpoint at that address. Similarly, the following command compares the start address of the current function, with the start address of function xyz, and prints the value 1, if they are equal, and 0 otherwise.

print {addr {func}}=={addr xyz}

The @ operator, introduced previously, may be used as a scope qualifier. Its precedence is the same as the C language field selection operators "." , and "->" .

PGDBG recognizes a range operator ":" which indicates array sub-ranges or source line ranges. For example,

print a[1:10]

prints elements 1 through 10 of the array a, and

list 5:10

lists source lines 5 through 10, and

list "xyz.c"@5:10 

lists lines 5 through 10 in file xyz.c. The precedence of ':' is between '||' and '=' .

The general format for the range operator is [ lo : hi : step] where:

lo

is the array or range lower bound for this expression.

hi

is the array or range upper bound for this expression.

step

is the step size between elements.

Table 15-1 PGDBG Operators

15.1.5 Debugging Fortran

In order to create symbolic information for debugging, invoke your PGI Fortran compiler with the -g option. Fortran type declarations are printed using Fortran type names, not C type names. The only exception is Fortran character types, which are treated as arrays of C characters.

15.1.5.1 Arrays

Large arrays, arrays with lower dimensions, and adjustable arrays are all supported. Fortran array elements and ranges should be accessed using parentheses, rather than square brackets.

15.1.5.2 Operators

Only those operators that exist in the C language may be used in expressions. In particular .eq., .ne., and so forth are not supported. The analogous C operators =, !=, etc. must be used instead. Note that the precedence of operators matches the C language, which may in some cases be different than for Fortran.

15.1.5.3 Name of Main Routine

If a PROGRAM statement is used, the name of the main routine is the name in the program statement. Otherwise the name of the main routine is __unnamed_. A function symbol named _MAIN_ is defined with start address equal to the start of the main routine. As a result,

break MAIN 

can always be used to set a breakpoint at the start of the main routine.

15.1.5.4 Fortran Common Blocks

Each subprogram that defines a common block will have a local static variable symbol to define the common. The address of the variable will be the address of the common block. The type of the variable will be a locally defined structure type with fields defined for each element of the common. The name of the variable will be the common name, if the common has a name, or _BLNK_ otherwise.

For each member of the common block, a local static variable is declared which represents the common variable. Thus given declarations:

common /xyz/ integer a, real b

then the entire common can be printed out using,

print xyz

and the individual elements can be accessed by name as in,

print a, b

15.1.6 Debugging C++

In order to create symbolic information for debugging, invoke your PGI C++ compiler with the -g option.

Calling C++ Instance Methods

As noted above, the call command has been significantly enhanced in PGDBG 3.2. To call a C++ instance method, the object must be explicitly passed as the first parameter to the call. For example, given the following definition of class Person and the appropriate implementation of its methods:

        class Person {
            public:
            char name[10];
            Person(char * name);
            void print();
        };
        main(){
          Person * pierre;
          pierre =  new Person("Pierre");
          pierre.print();
        }

To call the instance method print on object pierre, use the following syntax:

        pgdbg> call Person::print(pierre)

Notice that pierre is explicitly passed into the method, and the class name must also be specified.

15.1.7 Core Files

Some implementations of PGDBG are capable of interpreting core files. The debugger invocation for these systems has been modified as follows:

pgdbg [-core corefile] program arg1 ... argn

Using the -core option an informational message is printed on invocation indicating that the core file is being read. Before any data from the core file can be accessed, you must use the cont command. The debugger will then indicate that it is stopped at the location of the violation which caused the core file to be generated. At this point, memory, registers and instruction space may be displayed just as if the program were active, and breakpoints may be set.

While most execution related commands will be ignored, the run command will cause the program to be loaded and executed. Thereafter, PGDBG will behave just as if it had been invoked without the -core option.

15.1.8 Debugger Commands

15.2 PGDBG Commands

This section describes the PGDBG command set in detail. Section 15.3, Commands and Registers, presents a table of all the debugger commands, with a summary of their syntax.

15.2.1 Commands

Command names may be abbreviated as indicated. Some commands accept a variety of arguments. Arguments contained in [ and ] are optional. Two or more arguments separated by | indicate that any one of the arguments is acceptable. An ellipsis (...) indicates an arbitrarily long list of arguments. Other punctuation (commas, quotes, etc.) should be entered as shown. Argument names appear in italics and are chosen to indicate what kind of argument is expected. For example:

lis[t] [count | lo:hi | function | line,count] 

indicates that the command list may be abbreviated to lis, and that it will accept either no argument, an integer count, a line range, a function name, or a line and a count.

15.2.1.1 Process Control

The following commands, together with the breakpoints described in the next section let you control the execution of the target program. Note that when debugging an auto-parallelized or OpenMP parallel program, step and next commands executed within a parallel region are applied only to the currently active thread. The cont command is applied to all live threads. The currently active thread is modified using the thread command, and a list of all live threads is displayed by using the threads command.

c[ont]

Continue execution from the current location. This command may also be used to begin execution of the program at the beginning of the session.

de[bug]

Print the name and arguments of the program being debugged.

n[ext] [count]

Stop after executing one source line in the current function. This command steps over called functions. The count argument stops execution after executing count source lines. In a parallel region of code, next applies only to the currently active thread.

nexti [count]

Stop after executing one instruction in the current function. This command steps over called functions. The count argument stops execution after executing count instructions. In a parallel region of code, nexti applies only to the currently active thread.

q[uit]

Terminate the debugging session.

rer[un]
rer[un] [arg0 arg1 ... argn] [< inputfile ] [> outputfile ]

Works like run except if no args are specified, none are used.

ru[n]
ru[n] [arg0 arg1 ...argn] [< inputfile ] [> outputfile ]

Execute program from the beginning. If arguments arg0, arg1, .. are specified, they are set up as the command line arguments of the program. Otherwise, the arguments for the previous run command are used. Standard input and standard output for the target program can be redirected using < or > and an input or output filename.

s[tep]
s[tep] count
s[tep] up

Stop after executing one source line. This command steps into called functions. The count argument, stops execution after executing count source lines. The up argument stops execution after stepping out of the current function. In a parallel region of code, step applies only to the currently active thread.

stepi
stepi count
stepi up

Stop after executing one instruction. This command steps into called functions. The count argument stops execution after executing count instructions. The up argument stops the execution after stepping out of the current function. In a parallel region of code, stepi applies only to the currently active thread.

stepo[ut]

Stop after returning to the caller of the current function. This command sets a breakpoint at the current return address, and does a continue. To work correctly it must be possible to compute the value of the return address. Some functions, particularly terminal functions at higher optimization levels, may not set up a stack frame. Executing stepout from such a function will cause the breakpoint to be set in the caller of the most recent function that set up a stack frame. This command stops immediately upon return to the calling function. This means that the current location may not be the start of a source line because multiple function calls may occur on a single source line, and a user might want to stop after the first call. Users who want to step out of the current function and continue to the start of the next source line should simply follow stepout with next. In a parallel region of code, stepout applies only to the currently active thread.

thread [number]

Set the active thread to number. When issued with no argument, thread lists the current program location of the currently active thread. On Linux systems, number will be a 5 digit thread identifier. On Solaris86 systems, number will be a thread identifier between 1 and NCPUS+1 inclusive, where NCPUS is the environment variable which specifies how many processors the program should use (alternatively, OMP_NUM_THREADS in OpenMP programs)..

threads

Print a status of all live threads. NCPUS+1 live threads will be listed, where NCPUS is the environment variable which specifies how many processors the program should use. One of the threads is a master thread which is not used in computations. It will always be listed as waiting at _fini.

15.2.1.2 Events

The following commands deal with defining and managing events. See section 15.1.4.7 for a general discussion of events, and the optional arguments.

b[reak]
b[reak] line [if (condition)] [do {commands}]
b[reak] func [if (condition)] [do {commands}]

If no argument is specified, print the current breakpoints. Otherwise, set a breakpoint at the indicated line or function. If a function is specified, and the function was compiled for debugging, then the breakpoint is set at the start of the first statement in the function, that is, after the function's prologue code. If the function was not compiled for debugging, then the breakpoint is set at the first instruction of the function, prior to any prologue code. This command interprets integer constants as line numbers. To set a breakpoint at an address, use the addr command to convert the constant to an address, or use the breaki command.

When a condition is specified with if, the breakpoint occurs only when the specified condition evaluates true. If do is specified with a command or several commands as an argument, the command or commands are executed when the breakpoint occurs.

The following examples set breakpoints at line 37 in the current file, line 37 in file xyz.c, the first executable line of function main, address 0xf0400608, the current line, and the current address, respectively.

break 37
break  "xyz.c"@37
break main
break {addr 0xf0400608}
break {line}
break {pc}

More sophisticated examples include:

break xyz if(xyz@n > 10) 

This command stops when function xyz is entered only if the argument n is greater than 10.

break 100 do {print n; stack}

This command prints the value of n and performs a stack trace every time line 100 in the current file is reached.

breaki
breaki func [if (condition)] [do {commands}]
breaki addr [if (condition)] [do {commands}]

Set a breakpoint at the indicated address or function. If a function is specified, the breakpoint is set at the first address of the function. This means that when the program stops at this breakpoint the prologue code which sets up the stack frame will not yet have been executed, and hence, values of stack arguments will not be correct. Integer constants are interpreted as addresses. To specify a line, use the line command to convert the constant to a line number, or use the break command.

The if, and do arguments are interpreted as in the break command. The next examples set breakpoints at address 0xf0400608, line 37 in the current file, line 37 in file xyz.c, the first executable address of function main, the current line, and the current address, respectively:

breaki 0xf0400608
breaki {line 37}
breaki "xyz.c"@37
breaki main
breaki {line}
breaki {pc}

Similarly,

breaki 0x6480 if(n>3) do {print "n=", n}

stops and prints the new value of n at address 0x6480 only if n is greater than 3.

breaks

Display all the existing breakpoints.

catch
catch [sig:sig]
catch [sig [, sig...]]

With no arguments, print the list of signals being caught. With the : argument, catch the specified range of signals. With a list, trap signals with the specified number.

clear
clear all
clear func
clear line
clear addr {addr}

Clear all breakpoints at current location. Clear all breakpoints. Clear all breakpoints from first statement in the specified function func. Clear breakpoints from line number line. Clear breakpoints from the address addr.

del[ete] event-number
del[ete] 0
del[ete] all
del[ete] event-number [, event-number...]

Delete the event event-number or all events (delete 0 is the same as delete all). Multiple event numbers can be supplied if they are separated by a comma.

disab[le] event-number
disab[le] all

Disable the indicated event event-number, or all events. Disabling an event definition suppresses actions associated with the event, but leaves the event defined so that it can be used later.

do {commands} [if (condition)]
do {commands} at line [if (condition)]
do {commands} in func [if (condition)]

Define a do event. This command is similar to watch except that instead of defining an expression, it defines a list of commands to be executed. Without the optional arguments at or in, the commands are executed at each line in the program The at argument with a line specifies the commands to be executed each time that line is reached. The in argument with a func specifies the commands are executed at each line in the function. The if option has the same meaning as in watch. If a condition is specified, the do commands are executed only when condition is true.

doi {commands} [if (condition)]
doi {commands} at addr [if (condition)]
doi {commands} in func [if (condition)]

Define a doi event. This command is similar to watchi except that instead of defining an expression, it defines a list of commands to be executed. If an addr is specified, the commands are executed each time that address is reached. If a function func is specified, the commands are executed at each line in the function. If neither are specified, the commands are executed at each line in the program. The if option has the same meaning as in do above

enab[le] event-number | all

Enable the indicated event event-number, or all events.

hwatch addr [if (condition)] [do {commands}]

Define a hardware watchpoint. This command uses hardware support to create a watchpoint for a particular address. The event is triggered by hardware when the byte at the given address is written. This command is only supported on systems that provide the necessary hardware and software support. Only one hardware watchpoint can be defined at a time.

If an if option is specified, the event will cause no action unless the expression is true. If a do option is specified then the commands will be executed when the event occurs.

hwatchr[ead] addr [if (condition)] [do {commands}]

Define a hardware read watchpoint. This event is triggered by hardware when the byte at the given address is read. As with hwatch system hardware and software support must exist for this command to be supported. The if and do options have the same meaning as for hwatch.

hwatchb[oth] addr [if (condition)] [do {commands}]

Define a hardware read/write watchpoint. This event is triggered by hardware when the byte at the given address is either read or written. As with hwatch system hardware and software support must exist for this command to be supported. The if and do options have the same meaning as for hwatch.

ignore
ignore[sig:sig]
ignore [sig [, sig...]]

With no arguments, print the list of signals being ignored. With the : argument, ignore the specified range of signals. With a list, ignore signals with the specified number.

stat[us]

Display all the event definitions, including an event number by which the event can be identified.

stop var
stop at line [if (condition)][do {commands}]
stop in func [if (condition)][do {commands}]
stop if (condition)

Set a breakpoint at the indicated function or line. Break when the value of the indicated variable var changes. The at keyword and a number specifies a line number. The in keyword and a function name specifies the first statement of the specified function. With the if keyword, the debugger stops when the condition condition is true.

stopi var
stopi at address [if (condition)][do {commands}]
stopi in func [if (condition)][do {commands}]
stopi if (condition)

Set a breakpoint at the indicated address or function. Break when the value of the indicated variable var changes. The at keyword and a number specifies an address to stop at. The in keyword and a function name specifies the first address of the specified function to stop at. With the if keyword, the debugger stops when condition is true.

track expression [at line | in func] [if (condition)][do {commands}]

Define a track event. This command is equivalent to watch except that execution resumes after a new value is printed.

tracki expression [at addr | in func] [if (condition)][do {commands}]

Define an instruction level track event. This command is equivalent to watchi except that execution resumes after the new value is printed.

trace var [if (condition)][do {commands}]
trace func [if (condition)][do {commands}]
trace at line [if (condition)][do {commands}]
trace in func [if (condition)][do {commands}]

Activate source line tracing when var changes. Activate source line tracing and trace when in function func. With at, activate source line tracing to display the specified line each time it is executed. With in, activate source line tracing to display the specified each source line when in the specified function. If condition is specified, trace is on only if the condition evaluates to true. The do keyword defines a list of commands to execute at each trace point. Use the command pgienv speed secs to set the time in seconds between trace points. Use the clear command to remove tracing for a line or function.

tracei var [if (condition)][do {commands}]
tracei func [if (condition)][do {commands}]
tracei at addr [if (condition)][do {commands}]
tracei in func [if (condition)][do {commands}]

Activate instruction tracing when var changes. Activate instruction tracing when in function func. With at, activate tracing to display the specified line each time it is executed. With the in keyword, display instructions while in the specified function. Use the command pgienv speed secs to set the time in seconds between trace points. Use the clear command to remove tracing for a line or function.

unb[reak] line
unb[reak] func
unb[reak] all

Remove a breakpoint from the statement line. Remove a breakpoint from the function func. Remove all breakpoints.

unbreaki addr
unbreaki func
unbreaki all

Remove a breakpoint from the address addr. Remove a breakpoint from the function func Remove all breakpoints.

wa[tch] expression
wa[tch] expression [if (condition)][do {commands}]
wa[tch] expression at line [if (condition)][do {commands}]
wa[tch] expression in func [if (condition)][do {commands}]

Define a watch event. The given expression is evaluated, and subsequently, each time the value of the expression changes, the program stops and the new value is printed. If a particular line is specified, the expression is only evaluated at that line. If a function func is specified, the expression is evaluated at each line in the function. If no location is specified, the expression will be evaluated at each line in the program. If a condition is specified, the expression is evaluated only when the condition is true. If commands are specified, they are executed whenever the expression is evaluated and the value changes.

The watched expression may contain local variables, although this is not recommended unless a function or address is specified to ensure that the variable will only be evaluated when it is in scope.

Using watchpoints indiscriminately can dramatically slow program execution. Using the at and in options speeds up execution by reducing the amount of single-stepping and expression evaluation that must be performed to watch the expression. For example:

watch i at 40

will barely slow program execution at all, while

watch i

will slow execution considerably.

watchi expression
watchi expression [if(condition)][do {commands}]
watchi expression at addr [if(condition)][do {commands}]
watchi expression in func [if(condition)][do {commands}]

Define an instruction level watch event. This is just like the watch command except that the at option interprets integers as addresses rather than line numbers, and the expression is evaluated at every instruction instead of at every line.

This command is useful if line number information is limited. It causes programs to execute more slowly than watch.

when do {commands} [if (condition)]
when at line do {commands} [if (condition)]
when in func do {commands} [if (condition)]

Execute command at every line in the program. Execute commands at specified line in the program. Execute command in the specified function. If the optional condition is specified, commands are executed only when the expression evaluates to true.

wheni do {commands} [if (condition)]
wheni at addr do {commands} [if (condition)]
wheni in func do {commands} [if (condition)]

Execute commands at each address in the program. If a addr is specified, the commands are executed each time the address is reached If a function func is specified, the commands are executed at each line in the function. If the optional condition is specified, commands are executed whenever the expression is evaluated true.

15.2.1.3 Program Locations

arri[ve]

Print location information and update GUI markers for the current location.

cd [dir]

Change to the $HOME directory or to the specified directory dir.

dis[asm]
dis[asm] count
dis[asm] lo:hi
dis[asm] func
dis[asm] addr, count

Disassemble memory. If no argument is given, disassemble four instructions starting at the current address. If an integer count is given, disassemble count instructions starting at the current address. If an address range is given, disassemble the memory in the range. If a function name is given, disassemble the entire function. If the function was compiled for debug, and source code is available, the source code will be interleaved with the disassembly. If an address and a count are given, dissassemble count instructions starting at address addr.

edit
edit filename
edit func

If no argument is supplied, edit the current file starting at the current location. With a filename argument, edit the specified file filename. With the func argument, edit the file containing function func. This command uses the editor specified by the environment variable $EDITOR.

file [filename]

Change the source file to the file filename and change the scope accordingly. With no argument, print the current file.

lines function

Print the lines table for the specified function.

lis[t]
lis[t] count
lis[t] line,num
lis[t] lo:hi
lis[t] function

With no argument list 10 lines centered about the current source line. If a count is given list count lines centered about the source line. If a line and count are given, list number lines starting at line number line. For the dbx environment, this option lists lines from start to number. If a line range is given, list the indicated source lines in the current source file (this option is not valid in the dbx environment). If a function name is given, list the source code for the indicated function.

pwd

Print the current working directory.

stack[trace] [count]

Print a stacktrace. For each live function print the function name, source file, line number, current address. This command also prints the names and values of the arguments, if available. If a count is specified, display a maximum of count stack frames.

stackd[ump] [count]

Print a formatted dump of the stack. This command displays a hex dump of the stack frame for each live function. This command is a machine-level version of the stacktrace command. If a count is specified, display a maximum of count stack frames.

w[here] [count]

Print the address, function, source file and line number for the current location. If count is specified, print a maximum of count live functions on the stack.

/
/ [string] /

Search forward for a string string of characters in the current file. With just /, search for the next occurrence of string in the current file.

?
?[string] ?

Search backward for a string string of characters in the current file. With just ?, search for the previous occurrence of string in the current file.

15.2.1.4 Printing and Setting Variables

p[rint] exp1 [,...expn]

Evaluate and print one or more expressions. This command is invoked to print the result of each line of command input. Values are printed in a format appropriate to their type. For values of structure type, each field name and value is printed. Character pointers are printed as a hex address followed by character string.

Character string constants print out literally. For example:

	pgdbg> print "The value of i is ", i
	The value of i is 37

The array sub-range operator : prints a range of an array. The following example prints elements 0 through 10 of the array a:

	print a[0:10]

printf "format_string", expr,...expr

Print expressions in the format indicated by the format string. Behaves like the C library function printf. For example:

	pgdbg> printf "f[%d]=%G",i,f[i]
	f[3]=3.14

The pgienv command with the stringlen argument sets the maximum number of characters that will print with a print command. For example, the char declaration below:

char *c="a whole bunch of chars over 1000 chars long....";

A print c command will only print the first 512 (or stringlen) bytes. Normally the printing occurs until a NULL is reached, but without some limit, the printing may never end.

asc[ii] exp [,...exp]

Evaluate and print as an ascii character. Control characters are prefixed with the '^' character; that is,. 3 prints as ^c. Otherwise, values that can not be printed as characters are printed as integer values prefixed by ´\'. for example,. 250 prints as \250.

bin exp [,...exp]

Evaluate and print the expressions. Integer values are printed in binary.

dec exp [,...exp]

Evaluate and print the expressions. Integer values are printed in decimal.

display
display exp [,...exp]

Without arguments, list the expressions set to display at breakpoints. With an argument or several arguments, print expression exp at every breakpoint. See the description for undisplay.

hex exp [,...exp]

Evaluate and print the expressions. Integer values are printed in hex.

oct exp [,...exp]

Evaluate and print the expressions. Integer values are printed in octal.

set var=expression

Set variable var to the value of expression.

str[ing] exp [,...exp]

For each expression, evaluate, treat the result as a character pointer, and fetch and print a null terminated string from that address. This command will fetch a maximum of 70 characters.

undisplay 0
undisplay all
undisplay exp [,...exp]

Remove all expressions being printed at breakpoints. With an argument or several arguments, remove the expression exp from the list of display expressions.

15.2.1.5 Symbols and Expressions

The following describes the commands that deal with symbols and expressions.

as[sign] var = exp

Assign the value of the expression exp to the specified variable var.

call func [(exp,...)]

Call the named function. C argument passing conventions are used. Breakpoints encountered during execution of the function are ignored. If a signal is caught during execution of the function, execution will stop, but continued execution may produce unpredictable results. The return value, is assumed to be an integer, and is returned by this command. Fortran functions and subroutines can be called, but the argument values will be passed according to C conventions.

decl[aration] name

Print the declaration for the symbol, based on the type of the symbol in the symbol table. The symbol must be a variable, argument, enumeration constant, function, a structure, union, enum, or a typedef tag. For example, given declarations:

int i, iar[10];
struct abc {int a; char b[4]; struct abc *c;}val;

The commands,

decl I
decl iar
decl val
decl abc

will respectively print out as

int i
int iar[10]
struct abc val
struct abc {
   int a;
   char b[4];
   struct abc *c;
};

entr[y]
entr[y] func

Return the address of the first executable statement in the program or specified function. This is the first address after the function's prologue code.

lv[al] expr

Return the lvalue of the expression expr. The lvalue of an expression is the value it would have if it appeared on the left hand of an assignment statement. Roughly speaking, an lvalue is a location to which a value can be assigned. This may be an address, a stack offset, or a register.

rv[al] expr

Return the rvalue of the expression expr. The rvalue of an expression is the value it would have if it appeared on the right hand of an assignment statement. The type of the expression may be any scalar, pointer, structure, or function type.

siz[eof] name

Return the size, in bytes, of the variable type name.

type expr

Return the type of the expression. The expression may contain structure reference operators (. , and -> ), dereference (*), and array index ([ ] ) expressions. For example, given declarations shown previously, the commands:

type I
type iar
type val
type val.a
type val.abc->b[2]

produce the following output:

	int
	int [10]
	struct abc
	int
	char

whatis
whatis name

With no arguments, print the decalration for the current function. With argument name, print the declaration for the symbol name.

15.2.1.6 Scope

The following commands deal with program scope. See section 15.1.4.3 for a discussion of scope meaning and conventions.

decls
decls func
decls "sourcefile"
decls {global}

Print the declarations of all identifiers defined in the indicated scope. If no scope is given, print the declarations for global scope.

down [number]

Enter scope of function down one level or number levels on the call stack.

en[ter]
en[ter] func
en[ter] "sourcefile"
en[ter] {global}

Set the search scope to be the indicated symbol, which may be a function, source file or global. If no scope is specified use the search scope. The default enter with no argument is enter global.

files

Return the list of the files that make up the object file.

glob[al]

Return a symbol representing global scope. This command can also be used with the scope operator @ to specify symbols at global scope.

names
names func
names "sourcefile"
names {global}

Print the names of all identifiers defined in the indicated scope. If no scope is specified use the search scope.

sco[pe]

Return a symbol for the search scope. The search scope is set to the current function each time program execution stops. It may also be set using the enter command. The search scope is always searched first for symbols.

up [number]

Enter scope of function up one level or number levels on the call stack.

whereis name

Print all declarations for name.

which name

Print full scope qualification of symbol name.

15.2.1.7 Register Access

System registers can be accessed by name. See section 15.3.2 for the complete set of registers. A few commands exist to access common registers.

fp

Return the current value of the frame pointer.

pc

Return the current program address.

regs

Print a formatted display of the names and values of the integer, float, and double registers.

ret[addr]

Return the current return address.

sp

Return the current value of the stack pointer.

15.2.1.8 Memory Access

The following commands display the contents of arbitrary memory locations.

cr[ead]addr

Fetch and return an 8-bit signed integer (character) from the specified address.

dr[ead]addr

Fetch and return a 64 bit double from the specified address.

du[mp] address, count, "format-string"

This command dumps a region of memory according to a printf-like format descriptor. Starting at the indicated address, values are fetched from memory and displayed according to the format descriptor. This process is repeated count times.

Interpretation of the format descriptor is similar to printf. Format specifiers are preceded by %.

The meaning of the recognized format descriptors are as follows:

%d, %D, %o, %O, %x, %X, %u, %U
Fetch and print integral values as decimal, octal, hex, or unsigned. Default size is 32 bits. The size of the item read can be modified by either inserting 'h', or 'l' before the format character to indicate half (16) bits or long (32 bits). Alternatively, a 1, 2, or 4 after the format character can be used to specify the number of bytes to read.

%c
Fetch and print a character.

%f, %F, %e, %E, %g, %G
Fetch and print a float (lower case) or double (upper case) value using printf f, e, or g format.

%s
Fetch and print a null terminated string.

%p<format-chars>
Interpret the next four bytes as a pointer to an item specified by the following format characters. The pointed-to item is fetched and displayed. Examples:

%px
pointer to hex int.

%ps
pointer to string.

%pps
pointer to pointer to string.

%i
Fetch an instruction and disassemble it.

%w, %W
Display address about to be dumped.

%z<n>, %Z<n>, %z<-n>, %Z<-n>
Display nothing but advance or decrement current address by n bytes.

%a<n>, %A<n>
Display nothing but advance current address as needed to align modulo n.

fr[ead]addr

Fetch and return a 32 bit float from the specified address.

ir[ead] addr

Fetch and return a 32-bit signed integer from the specified address.

sr[ead]addr

Fetch and return a 16-bit signed integer from the specified address.

15.2.1.9 Conversions

The commands in this section are useful for converting between different kinds of values. These commands accept a variety of kinds of arguments, and return a value of particular kind.

ad[dr]
ad[dr] n
ad[dr] line
ad[dr] func
ad[dr] var
ad[dr] arg

Create an address conversion. If an integer is given return an address with the same value. If a line is given, return the address corresponding to the start of that line. If a function is given, return the first address of the function. If a variable or argument is given, return the address where that variable or argument is stored.

For example:

breaki {line {addr 0x22f0}}

func[tion]
func[tion] addr
func[tion] line

Return a function symbol. If no argument is specified, return the current function. If an address is given, return the function containing that address. An integer argument is interpreted as an address. If a line is given, return the function containing that line.

lin[e]
lin[e] n
lin[e] func
lin[e] addr

Create a source line conversion. If no argument is given, return the current source line. If an integer n is given, return it as a line number. If a function func is given, return the first line of the function. If an address addr is given, return the line containing that address.

For example, the following command returns the line number of the specified address:

line {addr 0x22f0}

15.2.1.10 Miscellaneous

The following commands make using the debugger easier.

al[ias]
al[ias] name
al[ias] name string

Create or print aliases. If no arguments are given print all the currently defined aliases. If just a name is given, print the alias for that name. If a name and string, are given, make name an alias for string. Subsequently, whenever name is encountered it will be replaced by string. Although string may be an arbitrary string, name must not contain any blanks.

For example:

	alias xyz print "x= ",x,"y= ",y,"z= ",z; cont

creates an alias for xyz. Now whenever xyz is typed, PGDBG will respond as though the following command was typed:

	print "x= ",x,"y= ",y,"z= ",z; cont

dir[ectory] [pathname]

Add the directory pathname to the search path for source files. If no argument is specified, the currently defined directories are printed. This command exists so that users can debug programs even when some or all of the program source files are in a directory other than the user's current directory. For example:

	dir morestuff

adds the directory morestuff to the list of directories to be searched. Now source files stored in morestuff are accessible to PGDBG.

If the first charcter in pathname is ~, it will be substituted by $HOME.

help [command]

If no argument is specified, print a brief summary of all the commands. If a command name is specified, print more detailed information about the use of that command.

history [num]

List the most recently executed commands. With the num argument, resize the history list to hold num commands. History allows several characters for command substitution:

The history modifiers may be:

:s/old/new/	Substitute the value new for the value old.
:p		Print but do not execute the command.

The command pgienv history off tells the debugger not to display the history record number. The command pgienv history on tells the debugger to display the history record number.

language

Print the name of the language of the current file.

log filename

Keep a log of all commands entered by the user and store it in the named file. This command may be used in conjunction with the script command to record and replay debug sessions.

nop[rint] exp

Evaluate the expression but do not print the result.

pgienv [command]

Define the debugger environment. With no arguments, display the debugger settings.

rep[eat] [first, last]
rep[eat] [first,:last:n]
rep[eat] [num ]
rep[eat] [-num ]

Repeat the execution of one or more previous history list commands. With the num argument, re-execute the command number num, or with -num, the last num commands. With the first and last arguments, reexeucte commands number first to last (optionally n times).

scr[ipt] filename

Open the indicated file and execute the contents as though they were entered as commands. If you use ~ before the filename, this is expanded to the value of $HOME.

setenv name
setenv name value

Print value of environment variable name. With a specified value, set name to value.

shell [arg0, arg1,... argn]

Fork a shell (defined by $SHELL) and give it the indicated arguments (the default shell is sh). If no arguments are specified, an interactive shell is invoked, and executes until a "^D" is entered.

sle[ep] [time]

Pause for time seconds or one second if no time is specified.

sou[rce] filename

Open the indicated file and execute the contents as though they were entered as commands. If you use ~ before the filename, this is expanded to the value of $HOME.

unal[ias] name

Remove the alias definition for name, if one exists.

use [dir]

Print the current list of directories or add dir to the list of directories to search. If the first character in pathname is ~, it will be substituted by $HOME.

15.3 Commands and Registers

This section contains a brief summary of PGDBG commands along with a list of register symbols.

15.3.1 Command Summary

15.3.2 IA-32 Register Symbols

This section describes the register symbols defined for IA-32 processors.

Table 15-2 - General Registers

Table 15-3 - Floating-Point Registers

Table 15-4 - Segment Registers

Table 15-5 - Special Purpose Registers

On Pentium III and compatible processors, an additional set of 8 SSE (streaming SIMD enhancements) registers and a SIMD floating-poing control and status register are available.

Table 15-6 - SSE Registers

Each SSE register contains four IEEE 745 compliant 32-bit single-precision floating-point values. The PGDBG regs command reports these values individually in both hexadecimal and floating-point format. PGDBG provides syntax to refer to these values individually, as members of a range, or all together.

The component values of each SSE register can be accessed using the same syntax that is used for array subscripting. Pictorially, the SSE registers can be thought of as follows:

Bits: 127 96 95 65 63 32 31 0

...

Figure 15-1 SSE register format

To access a $xmm0(3), the 32-bit single-precision floating point value that occupies bits 96 - 127 of SSE register 0, use the following PGDBG command:

      pgdbg> print $xmm0(3)

To set $xmm2(0) to the value of $xmm3(2), use the following PGDBG command:

      pgdbg> set $xmm2(3) = $xmm3(2)

You can also subscript SSE registers with range expressions to specify runs of consecutive component values, and access an SSE register as a whole. For example, the following are legal PGDBG commands:

      pgdbg> set $xmm0(0:1) = $xmm1(2:3)
      pgdbg> set $xmm6 = 1.0/3.0

The first command above initializes elements 0 and 1 of $xmm0 to the values in elements 2 and 3 respectively in $xmm1. The second command above initializes all four elements of $xmm6 to the constant 1.0/3.0 evaluated as a 32-bit floating-point constant.

15.4 X-Windows Graphical User Interface

The PGDBG X-Windows Graphical User Interface (GUI) is invoked on UNIX systems using the command Xpgdbg, which runs as a separate process that communicates with pgdbg. This section describes how to use the GUI on systems where it's supported. There may be minor variations in the GUI from host to host, depending on the type of monitor available, the settings for various defaults and the window manager used. The basic interface across all systems remains the same with the exception of the differences tied to the display characteristics and the window manager used.

15.4.1 Startup

Start PGDBG from a UNIX command prompt as follows:

% Xpgdbg [options] program args

where program and args specify the name and arguments of the program to be debugged and options may be any of the following:

-dbgcwd directory
Specifies the name of the directory to be used by PGDBG as its current working directory. This is the directory where pgdbg will look for the executable program and source files. The default is the current working directory from which Xpgdbg is invoked.

-GUIcwd directory
Specifies the name of the directory to be used by the PGDBG GUI as its current working directory. This is the directory where Xpgdbg will look for source files. The default is the current working directory from which Xpgdbg is invoked.

-dbgrname pathname
Specifies the pathname of the debugger with which Xpgdbg is to communicate. The default is $PGI/<target>/bin/pgdbg.

For each option, an environment variable may be defined to specify the default value of the option. The environment variables corresponding to the options above are DBGCWD, GUICWD, and DBGRNAME.

15.4.2 Main Window

Figure 15-1 below shows the main window of Xpgdbg. This window appears when Xpgdbg starts and remains throughout the session:

Figure 15-1

The components of the main window are:

Dialog Window - This window supports a dialog with the debugger. Commands entered in this window are executed, and the results are displayed.

Button Panel - This window displays buttons that can be clicked with the mouse as an alternative to typing commands. Many buttons, such as the print button, will pass selected text to the debugger as an argument to the command.

Source Window - This window displays the source code for the current location. The current location is marked by a footprint icon. Breakpoints may be set at any source line by clicking the left mouse button in the margin to the left of the source line. The breakpoints are marked by stop sign icons. An existing breakpoint may be cleared by clicking the left mouse button on the stop sign icon.

15.4.3 Disassembly Window

The figure below shows the disassembly window of Xpgdbg. It is useful for debugging code at the assembly code level. It is invoked by selecting DISASM in the main window's Window pulldown menu. By default, the current function is disassembled, and the current position is always displayed and marked with the footprint icon.

Figure 15-2

The components of the disassembly window are:

Control Panel - The items in the control panel allow selection of what memory is to be disassembled, and whether the display is to be updated automatically or on demand. A region other than the current function can be displayed by placing a function name or address range in the request field and clicking the SHOW button. The mode selection controls whether the display is updated for each new location, or whether the display is only updated on demand.

Disassembled Memory - This window displays a range of memory in disassembly format. Each instruction is preceded by its address. Breakpoints may be set at any instruction by clicking the left mouse button in the margin to the left of the instruction. If a function is being disassembled, the source code for the function is interleaved with the disassembled instructions.

15.4.4 Register Window

The register window displays the value of the processor's registers. It is invoked by selecting REGISTER in the main window's Window pulldown menu.

Figure 15-3

Control Panel - The display is updated each time the SHOW button is clicked. The mode item controls whether the display is updated automatically for each new location or on demand. The default is on demand.

15.4.5 Memory Window

The memory window displays a region of memory in a printf-like format descriptor. It is essentially a graphical interface to the pgdbg dump command (see section 15.2.1.8). It is invoked by selecting MEMORY in the main window's Window pulldown menu.

Figure 15-4

Control Panel - The Address, Count, and Format fields correspond to the 3 arguments to the pgdbg dump command. They specify the start address, repeat count, and dump format. The display is updated each time the SHOW button is clicked. The mode item controls whether the display is updated automatically for each new location or on demand. The default is on demand.

Memory Display - The display is simply the result of the pgdbg dump command. Starting at Address, Count data items are read from memory according to the descriptor in the Format field. Each line of output begins with the address being displayed in hexadecimal format This windows is scrollable so that large regions of memory may be examined.

15.4.6 Custom Window

The custom window is useful for repeatedly executing a sequence of debugger commands. The commands, entered in the control panel, can be executed at the click of a button or automatically at each new location.

Figure 15-5

Control Panel - Each time the SHOW button is clicked, the text string in the command field is executed and the results are displayed. If the MODE is set to "on new location", then the command is executed at each new location.

Results Display - This display shows the results of the executed command. The display is cleared prior to executing the command field. This window is scrollable so that all the results can be viewed.

<< " border=0>

> " border=0>