Chapter 2. Running dbx
Prev |  | Next

## Chapter 2. Running `dbx`

This chapter explains how to run `dbx`—specifically, it covers:

- “Compiling a Program for Debugging Under dbx”

- “Compiling and Linking Programs With Dynamic Shared Objects”

- “Invoking dbx” from a shell

- “Running Your Program”

- “Automatically Executing Commands on Startup”

- “Using Online Help”

- “Entering Multiple Commands on a Single Line”

- “Spanning a Command Across Multiple Lines”

- “Invoking a Shell” from `dbx`

- “Quitting dbx”

## Compiling a Program for Debugging Under `dbx`

Before using `dbx` to debug a program, compile the program using the `–` `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 a few things 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 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` command ```listobj` shows any DSOs in a process. The `dbx` command ```whichobj` lists all DSOs in which the named variable is present.

See “Running Your Program” for more description of the differences between programs compiled and linked with DSOs and programs compiled and linked with non-shared libraries. See also the dbx help section on hint_dso for more information on dbx and DSOs. For more information on DSOs, see “Using Dynamic Shared Objects” in the Compiling and Performance Tuning Guide.

## Invoking `dbx`

This section describes how to invoke dbx and includes:

- “dbx Options”

- “Specifying Object and Core Files”

- “The dbx Prompt”

- “Specifying Files with dbx Commands”

To invoke `dbx` from the shell command line, type `dbx`. The syntax is:

    dbx [options] [object_file [corefile]]

### `dbx` Options

Table 2-1 lists options you can give to `dbx`. These options are described in detail later in this chapter.

Table 2-1. `(continued) dbx Command-Line Options`

Option | Description
--- | ---
`–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` for each. 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.
`–c` `file` | Selects a command file other than ```.dbxinit` to execute on starting `dbx`. For information on .`dbxinit`, see “Automatically Executing Commands on Startup.”
`–e` num | Chooses a large size for the evaluation stack (as large as you want). The default stack size is 20,000 bytes. num = number of bytes. If you see the message `too` `large` `to` `evaluate`, rerun `dbx` suppling a value greater than 20,000.
`–k` | Turns on kernel debugging. When debugging a running system, specify ```/dev/kmem` as the core file.
`–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.
`–p` pid | Debugs the process specified by the pid number.
`–P` name | Debugs the running process with the specified name (name as described in the `ps`(1) reference page).
`–r` program [arg] | Runs the named program upon entering `dbx`, using the specified arguments. The `.dbxinit` file (if any) is read and executed after executing the `object_file`. You cannot specify a core file with `–r`.

### 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 don't 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.

### The `dbx` Prompt

Once `dbx` starts, it displays the prompt:

    (dbx)

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

### Specifying Files with `dbx` Commands

The ```givenfile` and ```corefile` `dbx` 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 currently running processes 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

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

`run` `run-arguments` |  | The `run` command starts your program and passes to it any arguments that you provide. The`run` command uses your shell (the program named in the SHELL environment variable or `/bin/sh` if an environment variable does not exist) to process a `run` command. The shell 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. In other words, the `run` command does exactly what typing `target run-arguments` at the shell prompt does. 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. A `run` command must appear on a line by itself and cannot be followed by another `dbx` command separated by a semi-colon (;). Terminate the command line with a return (new-line). Note that you cannot include a `run` command in the command list of a `when` command.
`rerun` [run-arguments] |  | The `rerun` command, without any arguments, repeats the last `run` command if applicable. Otherwise `rerun` is equivalent to the `run` command without any arguments.

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 the 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 file using the command name given by 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”) as 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”).

For example:

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

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

## Invoking a Shell

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

The syntax for the `sh` command is:

`sh` |  | Invoke a subshell.
`sh` command |  | Execute the specified shell 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