Chapter 2. Running dbx
Prev |  | Next

## Chapter 2. Running `dbx`

This chapter explains the basics of how to run `dbx`. It contains the following topics:

- “Compiling a Program for Debugging under dbx”

- “Compiling and Linking Programs with Dynamic Shared Objects”

- “Invoking dbx”

- “Running Your Program (run, rerun, and sort)”

- “Automatically Executing Commands on Startup”

- “Using Online Help”

- “Entering Multiple Commands on a Single Line”

- “Spanning a Command Across Multiple Lines”

- “Invoking a Shell”

- “Quitting dbx”

## Compiling a Program for Debugging under `dbx`

Before using `dbx` to debug a program, compile the program with the compiler's `-g` option (for example, `cc -g`). The `-g` option includes additional debugging information in your program object so that `dbx` can list local variables and find source lines.

If you use `dbx` to debug code that was not compiled using the `-g` option, local variables are invisible to `dbx`, and source lines may appear to jump around oddly as a result of various optimizations. It is more difficult to debug code without reliable references to lines of source code.

## Compiling and Linking Programs with Dynamic Shared Objects

This section summarizes some hings you need to know if you compile and link your program with Dynamic Shared Objects (DSOs). A DSO is a relocatable shared library. By linking with a DSO, you keep your program size small and also use memory efficiently.

If you compile and link with DSOs, `dbx` automatically notices their use in the program and picks up the relevant debugging information. The `dbx` `listobj` command shows any DSOs in a process. The `dbx` `whichobj` command lists all DSOs in which a specified variable is present. The `dbx` `listregions` command identifies DSO addresses at run time.

The `dbx` help section on `hint_dso` has more information on `dbx` and DSOs. For more information on DSOs, refer to the MIPSpro N32/64 Compiling and Performance Tuning Guide.

## Invoking `dbx`

This section describes how to invoke `dbx` and includes the following topics:

- “Specifying Object and Core Files”

- “Specifying Files with dbx Commands”

To invoke `dbx` from the shell command line, use the following `dbx` syntax:

    dbx [options] [
    object_file [corefile]]

After `dbx` starts, it displays the following prompt:

    (dbx)

To change this prompt, change the value of the `dbx` $prompt variable. “Setting dbx Variables” in Chapter 4, describes how to set `dbx` variables.

The following list describes options that you can give to the `dbx` command. These options are described in detail later in this chapter.

- `-c file`: selects a command file other than `.dbxinit` to execute on starting `dbx`. For information about `.dbxinit`, see “Automatically Executing Commands on Startup”.

- `-d`: provides startup information to the shell when a program is started with the `run` command.

- `-e` num: chooses as large an evaluation stack size as you want. The default stack size is 20,000 bytes, where num is equal to the number of bytes. If you see the message `too large to evaluate`, rerun `dbx` while suppling a value greater than 20,000.

- `-i`: uses interactive mode. This option prompts for source even when it reads from a file and treats data in a file as if it comes from a terminal (`stdin`). This option does not treat `#` characters as comments in a file.

- `-I` dir: tells `dbx` to look in the specified directory (in addition to the current directory and the object file's directory) for source files. To specify multiple directories, use a separate `-I` option for each directory. If no directory is specified when you invoke `dbx`, it looks for source files in the current directory and in the object file's directory. From `dbx`, changes the directories searched for source files with the `use` and `dir` commands.

- `-k`: turns on kernel debugging. When debugging a running system, specify `/dev/kmem` as the core file.

- `-N`: sets the `dbx $nonstop` variable to 1 on startup. Attaching to a process does not stop the process. This affects only the `dbx -p` and `dbx -P` options and the `addproc` command.

- `-P` name: debugs the running process with the specified name ( name as described in the `ps(1)` man page).

- `-p` pid: debugs the process specified by the pid number.

- `-R`: allows breakpoints in the runtime linker (`rld`).

- `-r` program [ args]: runs the named program upon entering `dbx` by using the arguments specified by args. The `.dbxinit` file (if any) is read and executed after executing the object file. You cannot specify a core file with `-r` option.

### Specifying Object and Core Files

The object_file is the name of the executable object file that you want to debug. It provides both the code that `dbx` executes and the symbol table that provides variable and procedure names and maps executable code to its corresponding source code in source files.

A corefile is produced when a program exits abnormally and produces a core dump. `dbx` allows you to provide the name of a core file that it uses as “the contents of memory” for the program that you specify. If you provide a core file, `dbx` lists the point of program failure. You can then perform stack traces and examine variable values to determine why a program crashed. However, you cannot force the program to execute past the line that caused it to crash.

If you do not specify a corefile, `dbx` examines the current directory for a file named `core` . If it finds `core`, and if `core` seems (based on data in the core file) to be a core dump of the program you specified, `dbx` acts as if you had specified `core` as the core file.

You can specify object and core files either as arguments when you invoke `dbx` or as commands that you enter at the `dbx` prompt.

### Specifying Files with `dbx` Commands

The `dbx` `givenfile` and `corefile` commands allow you to set the object file and the core file, respectively, while `dbx` is running.

- `givenfile file`: if you provide a filename, `dbx` kills the processes that currently are running and loads the executable code and debugging information found in file.

  If you do not provide a filename, `dbx` displays the name of the program that it is currently debugging without changing it.

- `corefile file`: if you provide a filename, `dbx` uses the program data stored in the core dump file.

  If you do not provide a filename, `dbx` displays the name of the current core file without changing it.

## Running Your Program (`run`, `rerun`, and `sort`)

You can start your program under `dbx` by using the `run` or the `rerun` command.

To verify exactly how your application is being started by the `run` or the `rerun` command, start `dbx` with the `-d` option.

- `run run-arguments`: the `run` command starts your program and passes any arguments to it that you provide. The command uses your shell (the program named in the `SHELL` environment variable or in `/bin/sh` if an environment variable does not exist) to process a `run` command. The same syntax allowed in your shell is allowed on the `run` command line. All shell processing is accepted, such as expansion and substitution of `*` and `?` in filenames. Redirection of the program's standard input and standard output, and/or standard error is also done by the shell.

  Therefore, the `dbx run` command does exactly the same thing as typing `target run-arguments` at the shell prompt. You can specify `target` either on `dbx` invocation or in a prior `givenfile` command. `dbx` passes `./target` as `argv[0]` to `target` when you specify it as a relative pathname.

  The `run` command must appear on a line by itself and cannot be followed by another `dbx` command separated by a semicolon (`;`). Terminate the command line with a return. Note that you cannot include a `run` command in the command list of a `when` command.

  The `run` command does not invoke the initialization files of the Bourne, C, and Korn shells before it starts a program. If you use a non-standard shell, before you run a program you should set the `dbx` variable called `$shellparameters` to a string that will instruct the shell to not load the initialization file. For example, for the C shell you would enter the following command:

      % set $shellparameters = "-f"

  If the `SHELL` environment variable is set to a C shell and your program has file-descriptors other than the default values (0,1,2), switch to the Bourne shell before you invoke the `run` command. This means you can use only `sh`-style redirections, because `csh` closes the extra file-descriptors. To switch shells for the purpose of running your program, use the following `dbx` command:

      % setenv SHELL /bin/sh

- `rerun`: the `rerun` command, without any arguments, repeats the last `run` command. `rerun` is equivalent to the `run` command without any arguments.

- `sort`: the `sort` command takes an input file and produces a sorted output file; you can specify input and output files either through command-line arguments or file redirection. For example, from the command line you can enter:

      % sort -i input -o output
      % sort < input2 > output2

If you are debugging the `sort` program, the equivalent `dbx` commands are:

    (dbx) run -i input -o output
    (dbx) run < input2 > output2

If you execute these `run` commands in the order presented, you can repeat the last run command by using the `rerun` command:

    (dbx) rerun

## Automatically Executing Commands on Startup

You can use an editor to create a `.dbxinit` command file. This file contains various `dbx` commands that automatically execute when you invoke `dbx`. You can put any `dbx` command in the `.dbxinit` file. If a command requires input, the system prompts you for it when you invoke `dbx` .

On invocation, `dbx` looks for a `.dbxinit` file in the current directory. If the current directory does not contain a `.dbxinit` file, `dbx` looks for one in your home directory. (This assumes that you have set the IRIX system `HOME` environment variable.)

## Using Online Help

The `dbx` command `help` has several options:

- `help`: shows the supported `dbx` commands.

- `help keyword`: shows information pertaining to a given keyword, such as `alias`, `help`, `most_used` , `quit`, `playback`, `record`, and so on.

- `help all`: shows the entire `dbx` help file.

When you type `help all`, `dbx` displays the help file by using the command name specified in the `dbx` `$pager` variable. The `dbx` help file is large and can be difficult to read even if you use a simple paging program like `more(1)`. You can set the `$pager` variable to a text editor like `vi (1)` or to your favorite editor.

For example, just add the following command in your `.dbxinit` file:

    % set $pager = "vi"

When the above entry is in your `.dbxinit` file, `dbx` displays the help file in `vi`. You can then use the editor's search commands to look through the help file quickly. Quit the editor to return to `dbx`.

## Entering Multiple Commands on a Single Line

You can use a semicolon (`;`) as a separator to include multiple commands on the same command line. This is useful with commands such as `when` (described in “Writing Conditional Commands” in Chapter 6) because it allows you to include multiple commands in the command block.

For example:

    (dbx)when at "myfile.c":37 {print a ; where ; print b}

## Spanning a Command Across Multiple Lines

You can use a backslash (\) at the end of a line of input to indicate that the command is continued on the next line. This can be convenient when entering complex commands such as an alias definition (aliases are discussed in “Creating and Removing dbx Aliases” in Chapter 4).

For example:

    (dbx) alias foll "print *(struct list *)$p ; \
    set $p = (int)((struct list *)($p))->next"

| Note: You can also use the `hed` command for creating and modifying commands. “The History Editor” in Chapter 4, has details on this command.

## Invoking a Shell

To invoke a subshell, enter the `sh` command at the `dbx` prompt, or enter the `sh` command and a shell command at the `dbx` prompt. After invoking a subshell, type the `exit` or `Ctrl-d` to return to `dbx`.

The syntax for the `sh` command is:

    sh command

The `sh` command alone invokes a subshell. The `sh command` syntax executes the specified command. `dbx` interprets the rest of the line as a command to pass to the spawned shell process, unless you enclose the command in double quotes or you terminate your shell command with a semicolon (`;`).

For example, to spawn a subshell, enter:

    (dbx) sh
    %

To display the end of the file `datafile`, enter:

    (dbx) sh tail datafile

## Quitting `dbx`

To end a `dbx` debugging session, enter the `quit` command at the `dbx` prompt:

    (dbx) quit

Prev | Table of Contents | Next
Chapter 1. Getting Started with dbx |  | Chapter 3. Examining Source Files