Sun Studio 12: Debugging a Program With dbx

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 would use if you give that name in an expression (see which 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``table
function: `Blocks``table::table(char*, int, int, const point&)
class: `Blocks``table
class: `Blocks``table
variable:       ``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 (see Debugging Information in Object Files and Executables).

For more information, see whereis Command.

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) in an expression. For example:

(dbx) func
wedge::wedge(char*, int, int, const point&, load_bearing_block*)
(dbx) which draw
``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. For more information on the which command, see which Command.

Scope Resolution Search Path

When you issue a debugging command that contains an expression, the symbols in the expression are looked up in the following order. dbx resolves the symbols as the compiler would at the current visiting scope.

  1. Within the scope of the current function using the current visiting scope (see Visiting Scope). If the program is stopped in a nested block, dbx searches within that block, then in the scope of all enclosing blocks.

  2. For C++ only: class members of the current function's class and its base class.

  3. For C++ only: the current name space.

  4. The parameters of the current function.

  5. The immediately enclosing module, generally, the file containing the current function.

  6. Symbols that were made private to this shared library or executable. These symbols can be created using linker scoping.

  7. Global symbols for the main program, and then for shared libraries.

  8. If none of the above searches are successful, dbx assumes you are referencing a private, or file static, variable or function in another file. 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 the symbol, it reports an error.

Relaxing the Scope Lookup Rules

To relax the scope lookup rules for static symbols and C++ member functions, set the dbx environment variable scope_look_aside to on:

dbxenv scope_look_aside on

or use the “double backquote” prefix:

stop in ``func4            func4 may be static and not in scope

If the dbx environment variable scope_look_aside is set to on, dbx looks for:

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.