Debugging a Program With dbx HomeContentsPreviousNextIndex

Chapter 1

Starting dbx

dbx is an interactive, source-level, command-line debugging tool. You can use it to run a program in a controlled manner and to inspect the state of a stopped program. dbx gives you complete control of the dynamic execution of a program, including the collection of performance data.

This chapter contains the following sections:

Starting a Debugging Session

How you start dbx depends on what you are debugging, where you are, what you need dbx to do, how familiar you are with dbx, and whether or not you have set up any dbx environment variables.

The simplest way to start a dbx session is to type the dbx command at a shell prompt.

$ dbx

To start dbx from a shell and load a program to be debugged, type:

$ dbx program_name

For more information on the dbx command and start-up options, see "dbx Command" and "Invoking dbx" in the Using dbx Commands section of the Sun WorkShopTM online help, and the dbx(1) man page.

dbx is started automatically when you start debugging a program using the Sun WorkShop Debugging window (see "Debugging the Current Program" and "Debugging a Program New to Sun WorkShop" in the Using the Debugging Window section of the Sun WorkShop online help).

Debugging an Existing Core File

If the program that dumped core was dynamically linked with any shared libraries, it is important to debug the core file in the same operating environment in which it was created.

To debug a core file, type:

$ dbx program_name core

Use the where command to determine where the program was executing when it dumped core.

When you debug a core file, you can also evaluate variables and expressions to see the values they had at the time the program crashed, but you cannot evaluate expressions that make function calls.

For more information, see "Core File Debugging with dbx" in the Using dbx Commands section of the Sun WorkShop online help.

Using the Process ID

You can attach a running process to dbx using the process_ID (pid) as an argument to the dbx command. 

$ dbx your_program_name process_ID

You can also attach to a process using its process ID number without knowing the name of the program.

$ dbx - process_ID

Because the program name remains unknown to dbx, you cannot pass arguments to the process in a run type command.

To attach dbx to a running process in the Sun WorkShop Debugging window, choose Debug Attach Process. For more information, see "Attaching to a Running Process" in the Using the Debugging Window section of the Sun WorkShop online help.

The dbx Startup Sequence

Upon invocation, dbx looks for and reads the installation startup file, .dbxrc in the directory install-directory/SUNWspro/lib, where the default install-directory is /opt.

Next, dbx searches for the startup file .dbxrc in the current directory, then in $HOME. If the file is not found, it searches for the startup file .dbxinit in the current directory, then in $HOME.

Generally, the contents of .dbxrc and .dbxinit files are the same with one major exception. In the .dbxinit file, the alias command is defined as dalias and not the normal default, which is kalias, the alias command for the Korn shell. A different startup file may be specified explicitly using the -s command-line option. For more information, see Using the .dbxrc File and "Creating a .dbxrc File" in the Using dbx Commands section of the Sun WorkShop online help.

A startup file may contain any dbx command, and commonly contains alias, dbxenv, pathmap, and Korn shell function definitions. However, certain commands require that a program has been loaded or a process has been attached to. All startup files are loaded before the program or process is loaded. The startup file may also source other files using the source or .(period) command. You can also use the startup file to set other dbx options.

As dbx loads program information, it prints a series of messages, such as Reading filename.

Once the program is finished loading, dbx is in a ready state, visiting the "main" block of the program (for C, C++, or Fortran 95: main(); for FORTRAN 77: MAIN()). Typically, you set a breakpoint and then issue a run command, such as stop in main and run for a C program.

Setting Startup Properties

You can use the pathmap, dbxenv, and alias commands to set startup properties for your dbx sessions.

Mapping With the pathmap Command

By default, dbx looks in the directory in which the program was compiled for the source files associated with the program being debugged. If the source or object files are not there or the machine you are using does not use the same path name, you must inform dbx of their location.

If you move the source or object files, you can add their new location to the search path. The pathmap command creates a mapping from your current view of the file system to the name in the executable image. The mapping is applied to source paths and object file paths.

Add common pathmaps to your .dbxrc file.

To establish a new mapping from the directory from to the directory to, type:

(dbx) pathmap [ -c ] from to

If -c is used, the mapping is applied to the current working directory as well.

The pathmap command is useful for dealing with automounted and explicit NFS-mounted file systems with different base paths on differing hosts. Use -c when you try to correct problems due to the automounter because current working directories are inaccurate on automounted file systems.

The mapping of /tmp_mnt to / exists by default.

For more information, see "pathmap Command" in the Using dbx Commands section of the Sun WorkShop online help.

Setting Environment Variables With the dbxenv Command

You can use the dbxenv command to either list or set dbx customization variables. You can place dbxenv commands in your .dbxrc file. To list variables, type:

$ dbxenv

You can also set dbx environment variables. See Chapter 2 for more information about the .dbxrc file and about setting these variables.

For more information, see Setting dbx Environment Variables With the dbxenv Command and "dbxenv Command" in the Using dbx Commands section of the Sun WorkShop online help.

Creating Your Own dbx Commands Using the alias Command

You can create your own dbx commands using the kalias or dalias commands. For more information, see "kalias Command" and "dalias Command" in the Using dbx Commands section of the Sun WorkShop online help.

Global variables can be printed and assigned to as normal, although they might have inaccurate values if the final register-to-memory store has not yet occurred.

Parameters can only be printed if you are stopped at the very beginning of a function, since the parameter registers can be re-used by the compiler. The values of stack variables cannot be printed or manipulated in optimized programs because the stack and register locations of these variables are not recorded.

The Analyzing a Program With Sun WorkShop manual contains more information on compiler optimizations that might be helpful when using the Sun Workshop tools on an optimized program.

Compiling a Program for Debugging

You must prepare your program for debugging with dbx by compiling it with the -g or -g0 option.

The -g option instructs the compiler to generate debugging information during compilation.

For example, to compile using C++, type:

% CC -g example_source.cc

In C++, the -g option turns on debugging and turns off inlining of functions. The -g0 (zero) option turns on debugging and does not affect inlining of functions. You cannot debug inline functions with the -g0 option. The -g0 option can significantly decrease link time and dbx start-up time (depending on the use of inlined functions by the program).

To compile optimized code for use with dbx, compile the source code with both the -O (uppercase letter O) and the -g options.

Debugging Optimized Code

The dbx tool provides partial debugging support for optimized code. The extent of the support depends largely upon how you compiled the program.

When analyzing optimized code, you can:

However, with optimized code, dbx cannot:

When programs are compiled with optimization and debugging enabled at the same time (using the -O -g options), dbx operates in a restricted mode.

Source line information is available, but the code for one source line might appear in several different places for an optimized program, so stepping through a program by source line results in the "current line" jumping around in the source file, depending on how the code was scheduled by the optimizer.

Tail call optimization can result in missing stack frames when the last effective operation in a function is a call to another function.

Generally, symbolic information for parameters, locals, and globals is available for optimized programs. Type information about structs, unions, C++ classes, and the types and names of locals, globals, and parameters should be available. Complete information about the location of these items in the program is not available for optimized programs.

Code Compiled Without the -g Option

While most debugging support requires that a program be compiled with -g, dbx still provides the following level of support for code compiled without -g:

Note, however, that dbx cannot display source code unless the code was compiled with the -g option. This restriction also applies to code that has had strip -x applied to it.

Shared Libraries Require the -g Option for Full dbx Support

For full support, a shared library must also be compiled with the -g option. If you build a program with shared library modules that were not compiled with the -g option, you can still debug the program. However, full dbx support is not possible because the information was not generated for those library modules.

Completely Stripped Programs

The dbx tool can debug programs that have been completely stripped. These programs contain some information that can be used to debug your program, but only externally visible functions are available. Runtime checking cannot work on stripped programs or load objects.

Quitting Debugging

A dbx session runs from the time you start dbx until you quit dbx; you can debug any number of programs in succession during a dbx session.

To quit a dbx session, type quit at the dbx prompt.

(dbx) quit

When you start dbx and attach it to a running process using the process_id option, the process survives and continues when you quit the debugging session. dbx performs an implicit detach before quitting the session.

Stopping a Process Execution

You can stop execution of a process at any time by pressing Ctrl+C without leaving dbx.

Detaching a Process From dbx

If you have attached dbx to a process, you can detach the process from dbx without killing it or the dbx session by using the detach command.

To detach a process from dbx without killing the process, type:

(dbx) detach

For more information, see "detach Command" in the Using dbx Commands section of the Sun WorkShop online help.

Killing a Program Without Terminating the Session

The dbx kill command terminates debugging of the current process as well as killing the process. However, kill preserves the dbx session itself leaving dbx ready to debug another program.

Killing a program is a good way of eliminating the remains of a program you were debugging without exiting dbx.

To kill a program executing in dbx, type:

(dbx) kill

For more information, see "kill Command" in the Using dbx Commands section of the Sun WorkShop online help.

Saving and Restoring a Debugging Run

The dbx tool provides three commands for saving all or part of a debugging run and replaying it later:

Using the save Command

The save command saves to a file all debugging commands issued from the last run, rerun, or debug command up to the save command. This segment of a debugging session is called a debugging run.

The save command saves more than the list of debugging commands issued. It saves debugging information associated with the state of the program at the start of the run--breakpoints, display lists, and the like. When you restore a saved run, dbx uses the information in the save-file.

You can save part of a debugging run; that is, the whole run minus a specified number of commands from the last one entered. Example A shows a complete saved run. Example B shows the same run saved, minus the last two steps.

Example A: Saving a complete run Example B: Saving a run minus the last two steps
debug debug
stop at line stop at line
run run
next next
next next
stop at line stop at line
continue continue
next next
next next
step step
next next
save save-2


If you are not sure where you want to end the run you are saving, use the history command to see a list of the debugging commands issued since the beginning of the session.

Note – By default, the save command writes information to a special save-file. If you want to save a debugging run to a file you can restore later, you can specify a file name with the save command. See Saving a Series of Debugging Runs as Checkpoints.

To save an entire debugging run up to the save command, type:

(dbx) save

To save part of a debugging run, use the save number command, where number is the number of commands back from the save command that you do not want saved.

(dbx) save number

Saving a Series of Debugging Runs as Checkpoints

If you save a debugging run without specifying a file name, dbx writes the information to a special save-file. Each time you save, dbx overwrites this save-file. However, by giving the save command a filename argument, you can save a debugging run to a file that you can restore later, even if you have saved other debugging runs since the one saved to filename.

Saving a series of runs gives you a set of checkpoints, each one starting farther back in the session. You can restore any one of these saved runs, continue, then reset dbx to the program location and state saved in an earlier run.

To save a debugging run to a file other than the default save-file:

(dbx) save filename

Restoring a Saved Run

After saving a run, you can restore the run using the restore command. dbx uses the information in the save-file. When you restore a run, dbx first resets the internal state to what it was at the start of the run, then reissues each of the debugging commands in the saved run.

Note – The source command also reissues a set of commands stored in a file, but it does not reset the state of dbx; it only reissues the list of commands from the current program location.

Prerequisites for an Exact Restoration of a Saved Run

For exact restoration of a saved debugging run, all the inputs to the run must be exactly the same: arguments to a run-type command, manual inputs, and file inputs.

Note – If you save a segment and then issue a run, rerun, or debug command before you do a restore, restore uses the arguments to the second, post-save run, rerun, or debug command. If those arguments are different, you might not get an exact restoration.

To restore a saved debugging run:, type:

(dbx) restore

To restore a debugging run saved to a file other than the default save-file:, type:

(dbx) restore filename

Saving and Restoring Using replay

The replay command is a combination command, equivalent to issuing a save -1 followed immediately by a restore. The replay command takes a negative number_of_ commands argument, which it passes to the save portion of the command. By default, the value of -number is -1, so replay works as an undo command, restoring the last run up until, but not including, the last command issued.

To replay the current debugging run, minus the last debugging command issued, type:

(dbx) replay

To replay the current debugging run and stop the run before a specific command, use the dbx replay command, where number is the number of commands back from the last debugging command.

(dbx) replay -number

Sun Microsystems, Inc.
Copyright information. All rights reserved.
Feedback
 		Library   |   Contents   |   Previous   |   Next   |   Index