Viewing and Visiting Code

Debugging a Program With dbx

Chapter 3

Viewing and Visiting Code

Each time the program you are debugging 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.

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

Mapping to the Location of the Code
Visiting Code
Qualifying Symbols With Scope Resolution Operators
Locating Symbols
Viewing Variables, Members, Types, and Classes
Using the Auto-Read Facility

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 directory the files 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 or 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 the directory from to the directory to:
(dbx) 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.

For more information, see "pathmap Command" in the Using dbx Commands section of the Sun WorkShop online help.

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:
(dbx) file filename
Using the file command by itself echoes the file you are currently visiting.
(dbx) file
dbx displays the file from its first line unless you specify a line number.
(dbx) 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. For example:
(dbx)func adjust_speed
The func command by itself echoes the currently visited function.

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 belongs to, you can type:
(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 C::foo

More than one identifier 'foo'.

Select one of the following:

0) Cancel

1) `a.out`t.cc`C::foo(int)

2) `a.out`t.cc`C::foo()

>1

`a.out`t.cc`C::foo(int)
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 echoes the name.

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

For more information, see "func Command" in the Using dbx commands section of the Sun WorkShop online help.

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.
(dbx) list [-i | -instr] [+] [-] number [ function | filename]
For more information on the list command, see "list Command" in the Using dbx Commands section of the Sun WorkShop online help.

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. Use the down command to move toward the current frame.

For more information on walking the call stack, see Walking the Stack and Returning Home.

Qualifying Symbols With Scope Resolution Operators

When using the func or file command, you might 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

Use the backquote character (`) to find a variable of global scope:
(dbx) print `item
A program can 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 registers which function you will visit. To qualify a function name with respect to its file name, use the general purpose backquote (`) scope resolution operator.
(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 might want to qualify an overloaded function name. If you do not qualify it, dbx displays an overload list so you can choose which function you will 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, type:
(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 `animate.o`change_glyph:230`item
Linker Names

dbx provides a special syntax for looking up symbols by their linker names (mangled names in C++). 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 `foo.c`#staticvar
Scope Resolution Search Path

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

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.
For C++ only: class members of the current function`s class and its base class.
For C++ only: the current name space.
The immediately enclosing "compilation unit," generally, the file containing the current function.
The LoadObject scope.
The global scope.
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_look_aside.

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 might 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 whereis symbol, where symbol can be any user-defined identifier. For example:
(dbx) whereis table

forward: `Blocks`block_draw.cc`table

function: `Blocks`block.cc`table::table(char*, int, int, const point&)

class: `Blocks`block.cc`table

class: `Blocks`main.cc`table

variable: `libc.so.1`hsearch.c`table
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 registers only occurrences of a symbol that are already loaded. As a debugging session gets longer, the list of occurrences can grow.

For more information, see "whereis Command" in the Using dbx Commands section of the Sun WorkShop online help.

Determining Which Symbol dbx Uses

The which command tells you which symbol with a given name dbx 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

`block_draw.cc`wedge::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

More than one identifier 'fid'.

Select one of the following:

0) Cancel

1) `example`file1.c`fid

2) `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 echoes the name.

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 register 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

The 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.

For more information, see "whatis Command" and "whatis Command Used With C++" in the Using dbx Commands section of the Sun WorkShop online help.

Looking Up Definitions of Variables, Members, and Functions

To print out the declaration of an identifier, type:
(dbx) whatis identifier
Qualify the identifier name with file and function information as needed.

For C++, whatis identifier lists function template instantiations. Template definitions are displayed with whatis -t identifier. See Looking Up Definitions of Types and Classes.

To print out the member function, type
(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, type:
(dbx) whatis block::movable

int movable;
On a variable, whatis tells you the variable`s type
(dbx) whatis the_table

class table *the_table;
.

On a field, whatis gives the field`s type.
(dbx) whatis the_table->draw

void table::draw(unsigned long pw);
When you are stopped in a member function, you can look up 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;
Looking Up Definitions of Types and Classes

The -t option of the whatis command displays a type. For C++, the list displayed by whatis -t includes template definitions and class template instantiations.

To print the declaration of a type or C++ class, type:
(dbx) whatis -t type_or_class_name
To see inherited members, the whatis command takes an -r option (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. The inserted comment lines separate 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 example protected:

    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,const class point &pos, class load_bearing_block *blk);

    virtual int load_bearing_block::is_load_bearing();

    virtual class list *load_bearing_block::supported_blocks();

    void load_bearing_block::add_supported_block(class block &b);

    void load_bearing_block::remove_supported_block(class block &b);
    virtual void load_bearing_block::print_supported_blocks();

    virtual void load_bearing_block::clear_top();

    virtual void load_bearing_block::put_on(class block &object);

    class point load_bearing_block::get_space(class block &object);

    class point load_bearing_block::find_space(class block &object);

    class point load_bearing_block::make_space(class block &object);

protected:

    class list *support_for;

    /* from class table */

public:

    table::table(char *name, int w, int h, const class point &pos);

    virtual char *table::type();

    virtual void table::draw(unsigned long pw);

};
Using the Auto-Read Facility

In general, 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, 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 yau are 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 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, using the absolute path recorded at compile time. 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. The debugging information is read the same way as for applications compiled with the -xs option. See "Debugging Without the Presence of .o Files" next.

Debugging Without the Presence of .o Files

Programs compiled with -g -c store debugging information for each module in the module's .o file. Auto-Read requires the continued presence of the program and shared library .o files.

When it is not feasible to keep program .o files or shared library .o files for modules that you want to debug, compile the program using the compiler -xs option (in addition to -g). You can have some modules compiled with -xs and some without. The -xs option instructs the compiler to have the linker place all the debugging information in the program executable; therefore the .o files do not have to be present to debug those modules.

In dbx 4.0, the debugging information for modules compiled with the -xs option is loaded during dbx startup. For a large program compiled with -xs, this might cause dbx to start slowly.

In dbx 5.0, the loading of debugging information for modules compiled with -xs is also delayed in the same way as the debugging information stored in .o files. However, you can instruct dbx to load the debugging information for modules compiled with -xs during startup. The dbx environment variable delay_xs lets you turn off the delayed loading of debugging information for modules compiled with -xs. To set the environment variable, add this line to your .dbxrc file:
dbxenv delay_xs off
You can also set this variable using the Debugging Options dialog box in Sun WorkShop Debugging. See "Delaying Loading of Modules Compiled with -xs" in the Using the Debugging Window section of the Sun WorkShop online help.

Listing Debugging Information for Modules

The module command and its options help you to keep track of program modules during the course of a debugging session. Use the module command to read in debugging information for one or all modules. Normally, dbx automatically and "lazily" reads in debugging information for modules as needed.

To read in debugging information for a module name, type:
(dbx) module [-f] [-q] name
To read in debugging information for all modules, type:
(dbx)module [-f] [-q] -a
where:

-f Forces reading of debugging information, even if the file is newer than the executable.

-q Specifies quiet mode.

-v Specifies verbose mode, which prints language, file names, and so on.

To print the name of the current module, type:
(dbx) module
Listing Modules

The modules command helps you keep track of modules by listing module names.

To list the names of modules containing debugging information that have already been read into dbx, type:
(dbx)modules [-v] -read
To list names of all program modules (whether or not they contain debugging information), type:
(dbx)modules [-v]
To list all program modules that contain debugging information, type:
(dbx)modules [-v] -debug
where:

-v Specifies verbose mode, which prints language, file names, and so on.

`(dbx)` `pathmap [-c]` from to

`(dbx)` `file` filename

`(dbx)` `file`

`(dbx)` `file` filename ; `list` line_number

`(dbx)func adjust_speed`

`(dbx)` `func block::block`

`(dbx)` `func main` `(dbx)` `which C::foo` More than one identifier 'foo'. Select one of the following: 0) Cancel 1) `a.out`t.cc`C::foo(int) 2) `a.out`t.cc`C::foo() >1 `a.out`t.cc`C::foo(int)

`(dbx)` `list [-i \| -instr] [+] [-]` number `[` function `\|` filename`]`

`(dbx)` print `item

`(dbx)` func `file_name`function_name

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

`(dbx)` `func` hand::draw

`(dbx)` stop in `animate.o`change_glyph:230`item

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

`(dbx)` `whereis table` forward: `Blocks`block_draw.cc`table function: `Blocks`block.cc`table::table(char*, int, int, const point&) class: `Blocks`block.cc`table class: `Blocks`main.cc`table variable: `libc.so.1`hsearch.c`table

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

`(dbx)` `which fid` More than one identifier 'fid'. Select one of the following: 0) Cancel 1) `example`file1.c`fid 2) `example`file2.c`fid

`(dbx)` `whatis` identifier

`(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();

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

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

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

`(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)` `whatis -t` type_or_class_name

`(dbx)` `whatis -t -r` class_name

`(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); };

`(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 example protected: 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,const class point &pos, class load_bearing_block blk); virtual int load_bearing_block::is_load_bearing(); virtual class list load_bearing_block::supported_blocks(); void load_bearing_block::add_supported_block(class block &b); void load_bearing_block::remove_supported_block(class block &b);

virtual void load_bearing_block::print_supported_blocks(); virtual void load_bearing_block::clear_top(); virtual void load_bearing_block::put_on(class block &object); class point load_bearing_block::get_space(class block &object); class point load_bearing_block::find_space(class block &object); class point load_bearing_block::make_space(class block &object); protected: class list support_for; / from class table / public: table::table(char name, int w, int h, const class point &pos); virtual char *table::type(); virtual void table::draw(unsigned long pw); };

`dbxenv delay_xs off`

`(dbx)` `module [-f] [-q]` name

`(dbx)module [-f] [-q] -a`

`-f`	Forces reading of debugging information, even if the file is newer than the executable.
`-q`	Specifies quiet mode.
`-v`	Specifies verbose mode, which prints language, file names, and so on.

(dbx) `module`

`(dbx)modules [-v] -read`

`(dbx)modules [-v]`

`(dbx)modules [-v] -debug`

-v	Specifies verbose mode, which prints language, file names, and so on.

Library | Contents | Previous | Next | Index

Chapter 3

Viewing and Visiting Code

Mapping to the Location of the Code

Visiting Code

Visiting a File

Visiting Functions

Selecting From a List of C++ Ambiguous Function Names

Choosing Among Multiple Occurrences

Printing a Source Listing

Walking the Call Stack to Visit Code

Qualifying Symbols With Scope Resolution Operators

Backquote Operator

C++ Double Colon Scope Resolution Operator

Block Local Operator

Linker Names

Scope Resolution Search Path

Locating Symbols

Printing a List of Occurrences of a Symbol

Determining Which Symbol `dbx` Uses

Viewing Variables, Members, Types, and Classes

Looking Up Definitions of Variables, Members, and Functions

Looking Up Definitions of Types and Classes

Using the Auto-Read Facility

Debugging Without the Presence of `.o` Files

Listing Debugging Information for Modules

Listing Modules

Chapter 3

Viewing and Visiting Code

Mapping to the Location of the Code

Visiting Code

Visiting a File

Visiting Functions

Selecting From a List of C++ Ambiguous Function Names

Choosing Among Multiple Occurrences

Printing a Source Listing

Walking the Call Stack to Visit Code

Qualifying Symbols With Scope Resolution Operators

Backquote Operator

C++ Double Colon Scope Resolution Operator

Block Local Operator

Linker Names

Scope Resolution Search Path

Locating Symbols

Printing a List of Occurrences of a Symbol

Determining Which Symbol dbx Uses

Viewing Variables, Members, Types, and Classes

Looking Up Definitions of Variables, Members, and Functions

Looking Up Definitions of Types and Classes

Using the Auto-Read Facility

Debugging Without the Presence of .o Files

Listing Debugging Information for Modules

Listing Modules

Determining Which Symbol `dbx` Uses

Debugging Without the Presence of `.o` Files