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”

- “Changing Source Files”

- “Listing Source Code”

- “Searching Through Source Code”

- “Calling an Editor”

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

#### Using Path Remapping

Files compiled with `–` `g` have full pathnames to source files. If you're debugging a program that was compiled somewhere else and you want to specify a new path to the sources, use path remapping. Just substitute one pattern for another pattern 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`. 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/` is replaced by the path specified after the colon.

## 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) `func` procedure

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
(`func` procedure 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.

## 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 |  | The `edit` command invokes the editor on the given file.
`edit` procedure |  | The `edit` command invokes the editor on the file that contains the source for the given procedure.

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