Chapter 3. Examining Source Files
Prev   Next

Chapter 3. Examining Source Files

This chapter explains how to examine source files under dbx. It describes:

Specifying Source Directories

Based on the information contained in an object file's symbol table, dbx determines from which source files the program was compiled and prints portions of these files as appropriate.

Object files compiled with –g record the absolute path names to the source files. Each time dbx needs a source file, it first searches the absolute path for the source file. If the source file is not present (or if the object file was not compiled with –g), dbx checks its own list of directories for source files.

By default, the dbx directory list contains only the current directory (from which you invoked dbx) and the object file's directory (if it is different from the current directory). Each time dbx searches this list, it searches all directories in the list in the order in which they appear until it finds the file with the specified name.

Specifying Source Directories With Arguments

You can specify additional source directories when you invoke dbx with the –I option. To specify multiple directories, use a separate –I for each.

For example, consider debugging a program called look in /usr/local/bin, the source for which resides in /usr/local/src/look.c. To debug this program, you can invoke dbx from the /usr/local/bin directory by entering:

% dbx -I /usr/local/src look

Specifying Source Directories With dbx Commands

The dir and use commands allow you to specify a source directory list while dbx is running.

dir [dir ...] 

If you provide one or more directories, dbx adds those directories to the end of the source directory list.

If you do not provide any directories, dbx displays the current source directory list.

use [dir ...] 

If you provide one or more directories, dbx replaces the source directory list with the directories that you provide.

If you do not provide any options, dbx displays the current source directory list.

Note: Both the dir and use commands recognize absolute and relative pathnames (for example, ../src); however, they do not recognize C shell tilde (~) syntax (for example, ~kim/src) or environment variables (for example, $HOME/src).

Examples of dir and use

Let's debug the look program in /usr/local/bin. Recall that the source resides in /usr/local/src/look.c. If you invoke dbx from the /usr/local/bin directory without specifying /usr/local/src as a source directory, it will not initially appear in the directory list:

(dbx) dir
.

However, you can add /usr/local/src with the dir command by entering:

(dbx) dir /usr/local/src
(dbx) dir
. /usr/local/src

If you use the use command instead, the current directory is no longer contained in the source directory list:

(dbx) use /usr/local/src
(dbx) use
/usr/local/src

Path Remapping

The debugging information for programs compiled with –g includes the full pathnames for source files. By default, dbx uses these pathnames to search for source files. However, if you are debugging a program that was compiled somewhere else and you want to specify a new path to the sources, you can use path remapping. You can substitute one pattern for another to remap the path so dbx can find the source file.

dir pattern1:pattern2 


The dir (or use) command allows you to remap directories and specify a new path to the source. dbx substitutes pattern2 for pattern1.

For example, a compiled program's source is /x/y/z/kk.c and the source was moved to /x/y/zzz/kk/kk.c. Specify the dir (or use) command to remap the path:

(dbx) dir /z/:/zzz/kk/

The new path is /x/y/zzz/kk/kk.c, where /z/ has been remapped to the string following the colon.

Controlling use of Path Remappings and Your Source-Directory List

The dbx variable $sourcepathrule controls how, in a source-file search, dbx uses path remappings and the source-directory list created by the dir and use commands. Table 3-1 summarizes the effects of $sourcepathrule.

Table 3-1. (continued) Effect of $sourcepathrule on Use of Path Remapping and Source Directory List

Value

Effect

0 (default)

Search for a source file by:
a) using the pathname in the object file's debugging information; if the file is not found, then
b) examine pathnames remapped by the dir or use command;
if the file is still not found, then
c) reduce full pathnames to base file names and search the list of directories created by the dir or use command.

1

Permute the default source-file search sequence to: step b, step c, then step a.

2

Use only steps b and c of the default source-file search sequence.

$sourcepathrule = 1 is useful when, for example, you move source files after you compile your program. You can direct dbx to the correct files.

$sourcepathrule = 2 is useful when, for example, your network is slow and you have full pathnames in your debugging information that point to files on other machines. The debugger ignores all pathnames in the debugging information and, hence, will not attempt access over the network.

Changing Source Files

The file command changes the current source file to a file that you specify. The new file becomes the current source file, on which you can search, list, and perform other operations. For example, to set the current source file to "Examining the Stack" on page 54procedure.c, enter:

(dbx) file procedure.c

Note: If your program is large, typically you store the source code in multiple files. dbx automatically selects the proper source file for the section of code that you are examining. Thus, many dbx commands reset the current source file as a side effect. For example, when you move up and down activation levels in the stack using the up and down commands, dbx changes the current source file to whatever file contains the source for the procedure (see "Examining the Stack" for more information on activation levels).

If you enter the file command without any arguments, dbx prints the current source file:

(dbx) file
procedure.c

You can also change the current source file by typing:

(dbx) funcprocedure

You can use the tag command to search the tag file for procedure:

(dbx) tag procedure

The tag command finds C preprocessor macros if they have arguments
(funcprocedure cannot). For more information about the tag file, see ctags(1).

Listing Source Code

The list command displays lines of source code. The dbx variable $listwindow defines the number of lines dbx lists by default. The list command uses the active frame and line of the current source file unless overridden by a file command. Any execution of the program overrides the file command by establishing a new current source file.

The syntax for the list command is:

list 

Lists $listwindow lines beginning at the current line (or list the line of the current pc if the current line is unknown or not set).

list exp 

Lists $listwindow lines starting with the line number given by the expression exp. The expression can be any valid expression that evaluates to an integer value as described in "Using Expressions".

list exp1:exp2 

Lists exp2 lines, beginning at line exp1.

list exp1,exp2 

Lists all source between line exp1 and line exp2 inclusive.

list func 

Lists $listwindow lines starting at procedure func.

list func,exp 

Lists all source between func and exp, inclusive.

list func:exp 

Lists exp lines, beginning at func.

A > symbol prints to the left of the line that is the current line. A * symbol prints to the left of the line of the current pc location.

For example, to list lines 20–35 of a file, enter:

(dbx) list 20,35

In response to this command, dbx displays lines 20 through 35 and sets the current line to 36.

To list 15 lines starting with line 75, enter:

(dbx) list 75:15

In response to this command, dbx displays lines 75 through 89 and sets the current line to 90.

Listing Inlines and Clones

The compiler may inline routines, replacing a call with quotes of code from the called routine, either as a result of optimization or C++ inline directives. Clones are specialized versions of routines that you can use to get faster-running code. The source for cloned routines is called a root.

In special cases, you may want to find inlined routines or clones. The commands listinlines and listclones find the routines, if enough debugging information is available. Compilations with the -32 option or with IRIX 6.2 and earlier base compilers do not have the necessary information; listinlines and listclones will show nothing.

The syntax for the listinlines command is:

listinlines  

Lists all inlined routines with their start and end addresses.

listinlines func 


Lists all the inlined instances of func with their start and end addresses.

For example, ::MultPoints is a C++ routine and you enter:

(dbx) listinlines ::MultPoints

The dbx output lists the address ranges of all the instances where ::MultPoints is inlined.

The syntax for the listclones command is similar:

listclones  

Lists all the root functions and their derived clones.

listclones func 


Lists the root and all derived clones for func.

Searching Through Source Code

Use the forward slash (/) and question mark (?) commands to search through the current file for regular expressions in source code. For a description of regular expressions, see the ed(1) reference page.

The search commands have the following syntax:

/[reg_exp] 

Search forward through the current file from the current line for the regular expression reg_exp. If dbx reaches the end of the file without finding the regular expression, it wraps around to the beginning of the file. dbx prints the first source line containing a match of the search expression.

If you don't supply a regular expression, dbx searches forward based on the last regular expression searched.

?[reg_exp] 

Search backward through the current file from the current line for the regular expression reg_exp. If dbx reaches the beginning of the file without finding the regular expression, it wraps around to the end of the file. dbx prints the first source line containing a match of the search expression.

If you don't supply a regular expression, dbx searches backward based on the last regular expression searched.

For example, to search forward for the next occurrence of the string "errno," enter:

(dbx) /errno

To search backward for the previous occurrence of either "img" or "Img," enter:

(dbx) ?[iI]mg

Calling an Editor

The edit command lets you edit files from within dbx:

edit 

The edit command invokes an editor (vi by default) on the current source file. If you set the dbx variable $editor to the name of an editor, the edit command invokes that editor. If you do not set the $editor, dbx checks the environment variable EDITOR and, if set, invokes that editor. When you exit the editor, you return to the dbx prompt.

edit file 

Invokes the editor on the given file.

edit procedure 

Invokes the editor on the file that contains the source for the specified procedure. dbx extended naming does not work. You may only name procedures that dbx can find with a simple name: procedures in the current activation stack and global procedures.

For example, to edit a file named soar.c from within dbx, type:

(dbx) edit soar.c

The edit command is also useful for editing dbx script files. See "Executing dbx Scripts" for more information on script files.

Prev Table of Contents Next
Chapter 2. Running dbx  Chapter 4. Controlling dbx