The following sections contain information on how to use 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:
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.
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.
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.
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.
Use the stop subcommand to set breakpoints in the dbx program. The stop subcommand halts the application program when certain conditions are fulfilled. The program is stopped when:
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.
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:
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.
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:
| cont | Continues the program from where it stopped. |
| detach | Continues the program from where it stopped, exiting the debug program. This is useful after you have patched the program and want to continue without the debug program. |
| return | Continues execution until a return to Procedure is encountered, or until the current procedure returns if Procedure is not specified. |
| skip | Continues execution until the end of the program or until Number + 1 breakpoints execute. |
| step | Runs one or a specified Number of source lines. |
| next | Runs up to the next source line, or runs a specified Number of source lines. |
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 set subcommand 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 executes 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. 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.
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.
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:
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.
dbx Symbolic Debug Program Overview.
Displaying and Manipulating the Source File with the dbx debug Program.
Debugging at the Machine Level with dbx.
Customizing the dbx Debugging Environment.