Debugging a Program With dbx |
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 toIf
-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
filenameUsing 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_numberVisiting Functions
You can use the
func
command to visit a function. To visit a function, type the commandfunc
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) Cancel1) `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 ofdbx
or the program. Whichever occurrence you choose,dbx
echoes the name.The
which
command tells you which symboldbx
would choose. In the case of ambiguous names, the overload display list indicates thatdbx
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 themain
orbegin
function. Use thedown
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
orfile
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 anddraw
is the function name, type:
(dbx)
func
hand::drawBlock 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 thedbxenv
settingscope_look_aside
.
dbx
uses whichever occurrence of the symbol it first finds along this search path. Ifdbx
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. Thedbx
which
command tells you which occurrence of a symboldbx
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:
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, thewhereis
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
UsesThe
which
command tells you which symbol with a given namedbx
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. Ifwhich
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) Cancel1) `example`file1.c`fid2) `example`file2.c`fid
dbx
shows the overload display, listing the ambiguous symbols names. In the context of thewhich
command, choosing from the list of occurrences does not affect the state ofdbx
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, adbx
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
identifierQualify the identifier name with file and function information as needed.
For C++,
whatis
identifier lists function template instantiations. Template definitions are displayed withwhatis -t
identifier. See Looking Up Definitions of Types and Classes.To print out the member function, type
:
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 thewhatis
shows that the compiler automatically allocated this variable to a register.
Looking Up Definitions of Types and Classes
The
-t
option of thewhatis
command displays a type. For C++, the list displayed bywhatis -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_nameTo 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_nameThe 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 classload_bearing_block
, which is, in turn, a child class ofblock
.Without
-r
,whatis
reports the members declared in classtable
:
Here are results when
whatis -r
is used on a child class to see members it inherits:
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 fordbx
.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 todbx
.
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 thepathmap
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
FilesPrograms 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 duringdbx
startup. For a large program compiled with-xs
, this might causedbx
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 instructdbx
to load the debugging information for modules compiled with-xs
during startup. Thedbx
environment variabledelay_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 themodule
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]
nameTo 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.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |