Using the dbx debug program

This section contains information on how to use the dbx debug program.

Starting the dbx debug program

The dbx program can be started with a variety of flags. The three most common ways to start a debug session with the dbx program are:

• Running the dbx command on a specified object file
• Using the -r flag to run the dbx command on a program that ends abnormally
• Using the -a flag to run the dbx command on a process that is already in progress

When the dbx command is started, it checks for a .dbxinit file in the user's current directory and in the user's $HOME directory. If a .dbxinit file exists, its subcommands run at the beginning of the debug session. If a .dbxinit file exists in both the home and current directories, then both are read in that order. Because the current directory .dbxinit file is read last, its subcommands can supercede those in the home directory.

If no object file is specified, then the dbx program asks for the name of the object file to be examined. The default is a.out. If the core file exists in the current directory or a CoreFile parameter is specified, then the dbx program reports the location where the program faulted. Variables, registers, and memory held in the core image may be examined until execution of the object file begins. At that point the dbx debug program prompts for commands.

Debugging a core image with missing dependent modules

Beginning with AIX® 5.3, the dbx program has the ability to examine a core image even if one or more dependent modules are inaccessible. During initialization, notification messages are displayed for each missing dependent module.

The user always has the option of directing the dbx program to accessible dependent modules using the -p flag. For more information, see the dbx command in the Commands Reference, Volume 2

Debugging a core image with mismatched dependent modules

Beginning with AIX 5.3, the dbx program detects if any dependent modules referenced in the core file are different than at core file creation. During initialization, notification messages are displayed for each mismatched dependent module.

The user should be aware that any information displayed by the dbx program that is based on the contents of a mismatched dependent module might be unreliable. In an effort to alert the user to information that should not be trusted, the dbx program sends notification messages whenever questionable information is displayed.

To disable this function and force the dbx program to treat mismatched dependent modules as missing dependent modules, the user can export the DBX_MISMATCH_MODULE environment variable with a value of DISCARD. With this variable exported, the dbx program still notifies the user of the mismatch, but proceeds as if mismatched dependent modules were inaccessible.

The user always has the option of directing the dbx program to matching dependent modules using the -p flag. For more information, see the dbx command in the Commands Reference, Volume 2

Running shell commands from dbx

You can run shell commands without exiting from the debug program using the sh subcommand.

If sh is entered without any commands specified, the shell is entered for use until it is exited, at which time control returns to the dbx program.

Command line editing in dbx

The dbx command provides command line editing features similar to those provided by Korn Shell. vi mode provides vi-like editing features, while emacs mode gives you controls similar to emacs.

You can turn these features on by using dbx subcommand set -o or set edit. So, to turn on vi-style command line editing, you would type the subcommand set edit vi or set -o vi.

You can also use the EDITOR environment variable to set the editing mode.

The dbx command saves commands entered to history file .dbxhistory. If the DBXHISTFILE environment variable is not set, then the history file used is $HOME/.dbxhistory.

By default, the dbx command saves the text of the last 128 commands entered. The DBXHISTSIZE environment variable can be used to increase this limit.

Using program control

The dbx debug program allows you to set breakpoints (stopping places) in the program. After entering the dbx program you can specify which lines or addresses are to be breakpoints and then run the program you want to debug with the dbx program. The program halts and reports when it reaches a breakpoint. You can then use dbx commands to examine the state of your program.

An alternative to setting breakpoints is to run your program one line or instruction at a time, a procedure known as single-stepping.

Setting and deleting breakpoints

Use the stop subcommand to set breakpoints in the dbx program. The stop subcommand halts the application program when certain conditions are fulfilled:

• The Variable is changed when the Variable parameter is specified.
• The Condition is true when the if Condition flag is used.
• The Procedure is called when the in Procedure flag is used.
• The SourceLine line number is reached when the at SourceLine flag is used.

  Note: The SourceLine variable can be specified as an integer or as a file name string followed by a : (colon) and an integer.

After any of these commands, the dbx program responds with a message reporting the event ID associated with your breakpoint along with an interpretation of your command. You can associate dbx subcommands to the specified event ID by using the addcmd subcommand. These associated dbx subcommands are issued when the breakpoint, tracepoint, or watchpoint corresponding to this event is hit. Use the delcmd subcommand to delete the associated dbx subcommands from the specified event ID.

Running a program

The run subcommand starts your program. It tells the dbx program to begin running the object file, reading any arguments just as if they were typed on the shell command line. The rerun subcommand has the same form as run; the difference is that if no arguments are passed, the argument list from the previous execution is used. After your program begins, it continues until one of the following events occurs:

• The program reaches a breakpoint.
• A signal occurs that is not ignored, such as INTERRUPT or QUIT.
• A multiprocess event occurs while multiprocess debugging is enabled.
• The program performs a load, unload, or loadbind subroutine.

  Note: The dbx program ignores this condition if the $ignoreload debug variable is set. This is the default. For more information see the set subcommand.

• The program completes.

In each case, the dbx debug program receives control and displays a message explaining why the program stopped.

There are several ways to continue the program once it stops:

A common method of debugging is to step through your program one line at a time. The step and next subcommands serve that purpose. The distinction between these two commands is apparent only when the next source line to be run involves a call to a subprogram. In this case, the step subcommand stops in the subprogram; the next subcommand runs until the subprogram has finished and then stops at the next instruction after the call.

The $stepignore debug variable can be used to modify the behavior of the step subcommand. See the dbx command in Commands Reference, Volume 2 for more information.

There is no event number associated with these stops because there is no permanent event associated with stopping a program.

If your program has multiple threads, they all run normally during the cont, next, nexti, and step subcommands. These commands act on the running thread (the thread which stopped execution by hitting a breakpoint), so even if another thread runs the code which is being stepped, the cont, next, nexti, or step operation continues until the running thread has also executed that code.

If you want these subcommands to execute the running thread only, you can set the dbx debug program variable $hold_next; this causes the dbx debug program to hold all other user threads during cont, next, nexti, and step subcommands.

Note: If you use this feature, remember that a held thread will not be able to release any locks which it has acquired; another thread which requires one of these locks could deadlock your program.

Separating dbx output from program output

Use the screen subcommand for debugging programs that are screen-oriented, such as text editors or graphics programs. This subcommand opens an Xwindow for dbx command interaction. The program continues to operate in the window in which it originated. If screen is not used, dbx program output is intermixed with the screen-oriented program output.

Tracing execution

The trace subcommand tells the dbx program to print information about the state of the program being debugged while that program is running. The trace subcommand can slow a program considerably, depending on how much work the dbx program has to do. There are five forms of program tracing:

• You can single-step the program, printing out each source line that is executed. The $stepignore debug variable can be used to modify the behavior of the trace subcommand. See the set subcommand for more information.
• You can restrict the printing of source lines to when the specified procedure is active. You can also specify an optional condition to control when trace information is produced.
• You can display a message each time a procedure is called or returned.
• You can print the specified source line when the program reaches that line.
• You can print the value of an expression when the program reaches the specified source line.

Deleting trace events is the same as deleting stop events. When the trace subcommand is executed, the event ID associated is displayed along with the internal representation of the event.