Viewing and Visiting Code

3

This chapter describes how dbx navigates through code, and locates functions and symbols. It also covers how to use commands to visit code or look up declarations for identifiers, types, and classes.

This chapter is organized into the following sections

Basic Concepts

page 17

Mapping to the Location of the Code

page 18

Visiting Code

page 18

Qualifying Symbols with Scope Resolution Operators

page 21

Locating Symbols

page 23

Viewing Variables, Members, Types, and Classes

page 25

Using the Auto-Read Facility

page 29

Command Reference

page 31

Basic Concepts	page 17
Mapping to the Location of the Code	page 18
Visiting Code	page 18
Qualifying Symbols with Scope Resolution Operators	page 21
Locating Symbols	page 23
Viewing Variables, Members, Types, and Classes	page 25
Using the Auto-Read Facility	page 29
Command Reference	page 31

Basic Concepts

Each time the program stops, dbx prints the source line associated with the stop location. At each program stop, dbx resets the value of the current function to the function in which the program is stopped. Before the program starts running and when it is stopped, you can move to, or visit, functions and files elsewhere in the program.

Mapping to the Location of the Code

dbx must know the location of the source and object code files associated with a program. The default directory for the object files is the one they were in when the program was last linked. The default directory for the source files is the one they were in when last compiled. If you move the source or object files, or copy them to a new location, you must either relink the program or change to the new location before debugging.

If you move the source/object files, you can add their new location to the search path. The pathmap command creates a mapping from your current view of the file system to the name in the executable image. The mapping is applied to source paths and object file paths.

To establish a new mapping from directory from to directory to type:

pathmap [-c] from to

`pathmap [-c]` from to

If -c is used, the mapping is applied to the current working directory as well.

The pathmap command is also useful for dealing with automounted and explicit NFS-mounted file systems with different base paths on differing hosts. Use -c when you try to correct problems due to the automounter because current working directories are inaccurate on automounted file systems.

The mapping of /tmp_mnt to / exists by default.

Visiting Code

You can visit code elsewhere in the program any time the program is not running. You can visit any function or file that is part of the program.

Visiting a File

You can visit any file dbx recognizes as part of the program (even if a module or file was not compiled with the -g option.) Visiting a file does not change the current function. To visit a file:


`file` filename

Using the file command by itself echoes the file you are currently visiting:

file

`file`

dbx displays the file from its first line unless you specify a line number:

file filename ; list line_number

`file` filename ; list line_number

Visiting Functions

You can use the func command to visit a function. To visit a function, type the command func followed by the function name. The func command by itself echoes the currently visited function. For example:


`(dbx)` `func adjust_speed`

Selecting from a List of C++ Ambiguous Function Names

If you try to visit a C++ member function with an ambiguous name or an overloaded function name, a list is displayed, showing all functions with the overloaded name.

If the specified function is ambiguous, type the number of the function you want to visit. If you know which specific class a function belong to, you can type:

(dbx)func block::block

`(dbx)func block::block`

Choosing Among Multiple Occurrences

If multiple symbols are accessible from the same scope level, dbx prints a message reporting the ambiguity:


(dbx) func main (dbx) which block::block Class block has more than one function member named block.

In the context of the which command, choosing from the list of occurrences does not affect the state of dbx or the program. Whichever occurrence you choose, dbx merely echoes the name.

Remember that the which command tells you which symbol dbx would pick. In the case of ambiguous names, the overload display list indicates that dbx does not yet know which occurrence of two or more names it would use. dbx lists the possibilities and waits for you to choose one.

Printing a Source Listing

Use the list command to print the source listing for a file or function. Once you visit a file, list prints number lines from the top. Once you visit a function, list prints its lines.


list [-i \| -instr] [+] [-] number [ function \| filename ]

Walking the Call Stack to Visit Code

Another way to visit code when a live process exists is to "walk the call stack," using the stack commands to view functions currently on the stack.

Walking the stack causes the current function and file to change each time you display a stack function. The stop location is considered to be at the "bottom" of the stack; so to move away from it, use the up command, that is, move toward the main or begin function.

Qualifying Symbols with Scope Resolution Operators

When using func or file, you may need to use scope resolution operators to qualify the names of the functions that you give as targets.

dbx provides three scope resolution operators with which to qualify symbols: the backquote operator (`), the C++ double colon operator (::), and the block local operator (:<lineno>). You use them separately, or in some cases, together.

In addition to qualifying file and function names when visiting code, symbol name qualifying is also necessary for printing and displaying out-of-scope variables and expressions, and for displaying type and class declarations (whatis command). The symbol qualifying rules are the same in all cases; this section covers the rules for all types of symbol name qualifying.

Backquote Operator

The backquote character(`) can be used to find a variable of global scope:


(dbx) print `item

A program may use the same function name in two different files (or compilation modules). In this case, you must also qualify the function name to dbx so that it knows which function you mean to visit. To qualify a function name with respect to its filename, use the general purpose backquote (`) scope resolution operator:

(dbx) func `file_name`function_name

(dbx) func `file_name`function_name

C++ Double Colon Scope Resolution Operator

Use the double colon operator (::) to qualify a C++ member function or top level function with:

An overloaded name (same name used with different argument types)
An ambiguous name (same name used in different classes)

You may want to qualify an overloaded function name. If you do not qualify it, dbx pops up an overload display list for you to choose which function you mean to visit. If you know the function class name, you can use it with the double colon scope resolution operator to qualify the name.


(dbx) `func` class::function_name `(`args`)`

For example, if hand is the class name and draw is the function name:

(dbx) func hand::draw

(dbx) `func` hand::draw

Block Local Operator

The block local operator (:lineno) is used in conjunction with the backquote operator. It identifies the line number of an expression that references the instance you're interested in.

In the following example, :230 is the block local operator:

(dbx) stop in \Qanimate.o\Qchange_glyph:230\Qitem

(dbx) `stop in \Qanimate.o\Qchange_glyph:230\Qitem`

Linker Names

dbx provides a special syntax for looking up symbols by their linker names (mangled names in C++). You prefix the symbol name with a # (pound sign) character (use the ksh escape character \ (backslash) before any $ (dollar sign) characters), as in these examples:


(dbx) `stop in #.mul` (dbx) `whatis #\$FEcopyPc` (dbx) `print \Qfoo.c\Q#staticvar`

Scope Resolution Search Path

When you issue a debugging command with a symbol target name, the search order is as follows:

: 1. dbx first searches within the scope of the current function. If the program is stopped in a nested block, dbx searches within that block, then in the scope of all enclosing blocks.
: 2. For Pascal only: the next immediately enclosing function.
: 3. For C++ only: class members of the current function`s class and its base class.
: 4. The immediately enclosing "compilation unit": generally, the file containing the current function.
: 5. The LoadObject scope.
: 6. The global scope.
: 7. If none of the above searches are successful, dbx assumes you are referencing a private, or file static, variable or function. dbx optionally searches for a file static symbol in every compilation unit depending on the value of the dbxenv setting scope_lookaside.

dbx uses whichever occurrence of the symbol it first finds along this search path. If dbx cannot find a variable, it reports an error.

Locating Symbols

In a program, the same name may refer to different types of program entities and occur in many scopes. The dbx whereis command lists the fully qualified name--hence, the location--of all symbols of that name. The dbx which command tells you which occurrence of a symbol dbx uses if you give that name as the target of a debugging command.

Printing a List of Occurrences of a Symbol

To print a list of all the occurrences of a specified symbol, use the whereis symbol, where symbol can be any user-defined identifier. For example:

(dbx) `whereis table` forward: \QBlocks\Qblock_draw.cc\Qtable function: \QBlocks\Qblock.cc\Qtable::table(char*, int, int, const point&) class: \QBlocks\Qblock.cc\Qtable class: \QBlocks\Qmain.cc\Qtable variable: \Qlibc.so.1\Qhsearch.c\Qtable

(dbx) whereis table

forward: \QBlocks\Qblock_draw.cc\Qtable

function: \QBlocks\Qblock.cc\Qtable::table(char*, int, int, const 
point&)

class: \QBlocks\Qblock.cc\Qtable

class: \QBlocks\Qmain.cc\Qtable

variable:       \Qlibc.so.1\Qhsearch.c\Qtable

The output includes the name of the loadable object(s) where the program defines symbol, as well as the kind of entity each object is: class, function, or variable.

Because information from the dbx symbol table is read in as it is needed, the whereis command knows only about occurrences of a symbol that are already loaded. As a debugging session gets longer, the list of occurrences may grow.

Determining Which Symbol `dbx` Uses

The which command tells you which symbol with a given name it uses if you specify that name (without fully qualifying it) as the target of a debugging command. For example:


(dbx) `func` wedge::wedge(char, int, int, const point&, load_bearing_block) (dbx) `which draw` \Qblock_draw.cc\Qwedge::draw(unsigned long)

If a specified symbol name is not in a local scope, the which command searches for the first occurrence of the symbol along the scope resolution search path. If which finds the name, it reports the fully qualified name.

If, at any place along the search path the search finds multiple occurrences of symbol at the same scope level, dbx prints a message in the command pane reporting the ambiguity:

(dbx) which fid

\Qexample`file1.c`fid

`example`file2.c`fid

(dbx) `which fid` \Qexample`file1.c`fid `example`file2.c`fid

dbx shows the overload display, listing the ambiguous symbols names. In the context of the which command, choosing from the list of occurrences does not affect the state of dbx or the program. Whichever occurrence you choose, dbx merely echoes the name.

Remember that the which command gives you a preview of what happens if you make symbol (in this example, block) an argument of a command that must operate on symbol (for example, a print command). In the case of ambiguous names, the overload display list indicates that dbx does not yet know which occurrence of two or more names it uses. dbx lists the possibilities and waits for you to choose one.

Viewing Variables, Members, Types, and Classes

dbx's whatis command prints the declarations or definitions of identifiers, structs, types and C++ classes, or the type of an expression. The identifiers you can look up include variables, functions, fields, arrays, and enumeration constants.

To print out the declaration of an identifier:

(dbx) whatis identifier

(dbx) `whatis identifier`

Qualify the identifier name with file and function information as needed.

To print out the member function

(dbx) whatis block::drawvoid block::draw(unsigned long pw);

(dbx) whatis table::drawvoid table::draw(unsigned long pw);

(dbx) whatis block::posclass point *block::pos();

Notice that table::pos is inherited from block:

(dbx) whatis table::posclass point *block::pos();

(dbx) `whatis block::draw`void block::draw(unsigned long pw); (dbx) `whatis table::draw`void table::draw(unsigned long pw); (dbx) `whatis block::pos`class point block::pos(); Notice that table::pos is inherited from block: (dbx) `whatis table::pos`class point block::pos();

To print out the data member:

(dbx) whatis block::movableint movable;

(dbx) `whatis block::movable`int movable;

On a variable, whatis tells you the variable`s type:

(dbx) whatis the_tableclass table *the_table;

(dbx) `whatis the_table`class table *the_table;

On a field, whatis tells you the field`s type:

(dbx) whatis the_table->drawvoid table::draw(unsigned long pw);

(dbx) `whatis the_table->draw`void table::draw(unsigned long pw);

When you are stopped in a member function, you can lookup the this pointer. In this example, the output from the whatis shows that the compiler automatically allocated this variable to a register.

(dbx) stop in brick::draw

(dbx) cont

// expose the blocks window (if exposed, hide then expose) to force program to hit the breakpoint.

(dbx) where 1

brick::draw(this = 0x48870, pw = 374752), line 124 in

"block_draw.cc"

(dbx)whatis this

class brick *this;

(dbx) `stop in brick::draw` (dbx) `cont` // expose the blocks window (if exposed, hide then expose) to force program to hit the breakpoint. (dbx) `where 1` brick::draw(this = 0x48870, pw = 374752), line 124 in "block_draw.cc" (dbx)`whatis this` class brick *this;

Looking Up Definitions of Types and Classes

To print the declaration of a type or C++ class:


(dbx) `whatis -t` type_or_class_name

To see inherited members the whatis command takes an option -r (for recursive) that displays the declaration of a specified class together with the members it inherits from parent classes.

(dbx) whatis -t -r class_name

The output from a whatis -r query may be long, depending on the class hierarchy and the size of the classes. The output begins with the list of members inherited from the most ancestral class. Note the inserted comment lines separating the list of members into their respective parent classes.

Here are two examples, using the class table, a child class of the parent class load_bearing_block, which is, in turn, a child class of block.

Without -r, whatis reports the members declared in class table:(dbx) whatis -t class table class table : public load_bearing_block { public: table::table(char *name, int w, int h, const class point &pos); virtual char *table::type(); virtual void table::draw(unsigned long pw); };

Here are results when whatis -r is used on a child class to see members it inherits

(dbx) whatis -t -r class table

class table : public load_bearing_block {

public:

/* from base class table::load_bearing_block::block */

block::block();

block::block(char *name, int w, int h, const class point &pos, class

load_bearing_block *blk);

virtual char *block::type();

char *block::name();

int block::is_movable();

// deleted several members from exampleprotected:

char *nm;

int movable;

int width;

int height;

class point position;

class load_bearing_block *supported_by;

Panel_item panel_item;

/* from base class table::load_bearing_block */

public:

load_bearing_block::load_bearing_block();

load_bearing_block::load_bearing_block(char *name, int w, int h,

Using the Auto-Read Facility

In general, you should compile the entire program you want to debug using the -g option. Depending on how the program was compiled, the debugging information generated for each program and shared library module is stored in either the object code file (.o file) for each program and shared library module, and/or the program executable file.

When you compile with the -g -c compiler option, debugging information for each module remains stored in its .o file. dbx then reads in debugging information for each module automatically, as it is needed, during a session. This read-on-demand facility is called Auto-Read. Auto-Read is the Default for dbx.

Auto-Read saves considerable time when loading a large program into dbx. Auto-Read depends on the continued presence of the program .o files in a location known to dbx.

Note - If you archive .o files into .a files, and then link using the archive libraries, you can then remove the associated .o files, but you must keep the .a files.

By default, dbx looks for files in the directory where they were when the program was compiled and the .o files in the location from which they were linked. If the files are not there, use the pathmap command to set the search path.

If no object file is produced, debugging information is stored in the executable. That is, for a compilation that does not produce .o files, the compiler stores all the debugging information in the executable and dbx does not use the Auto-Read facility.