dbx(1)dbx(1)NAMEdbx - source level debugger
SYNOPSISdbx [-I dir] [-c file] [-k] [-i] [-r] [-pid xxx] [objectfile [core‐
file]]
OPTIONS
The dbx debugger accepts the following options: Selects a command file
other than Invokes dbx in interactive mode. This option causes the
debugger to not treat source lines beginning with number signs (#) as
comments. Adds dir to the list of directories that dbx searches for
source files. By default, dbx searches the current directory and the
directory where object is located. You can specify multiple directories
by using multiple -I options. Maps memory addresses. This option is
useful for kernel debugging. For information on kernel debugging, see
the Kernel Debugging manual. Specifies the directory path where dbx
should search for shared libraries (or loadable kernel modules). This
option is useful if, for example, you are debugging a core dump (or a
kernel crash dump) and the version of a shared library (or module) that
was running when the dump occurred has been moved to a different loca‐
tion. Using this option automatically sets the $module_path dbx vari‐
able to the specified path. If dbx cannot find a file in the specified
directory, it looks in the directory where that file was originally, as
recorded in the dump. See also the DBX_MODULE_PATH environment vari‐
able. For information on kernel debugging, see the Kernel Debugging
manual. Causes dbx to print the path of shared libraries (or loadable
kernel modules, if debugging a kernel) as they are being loaded. By
default, dbx does not print the path. Using this option automatically
sets the $module_verbose dbx variable to the value 1. See also the
DBX_MODULE_VERBOSE environment variable. For information on kernel
debugging, see the Kernel Debugging manual. Executes the object file
immediately. If program execution terminates with an error, dbx dis‐
plays the message that describes the error. You can then either invoke
the debugger or let the program continue exiting. The dbx debugger
reads from /dev/tty when you specify the -r option and standard input
is not a terminal. If the program executes successfully, dbx prompts
you for input. For use in debugging kernels. (Refer to the Kernel
Debugging manual for information on kernel debugging. For information
on debugging a running kernel using breakpoints, refer to kdbx(8).)
Outputs file and line number information in a format compatible with
the emacs function gdb. Attaches dbx to a currently running process
specified by process id xxx.
OPERANDS
Specifies the object file that you want dbx to read as input.
For complete dbx support, the object file must contain extended
symbol table information. The supported compilers each have a -g
option that produces the symbol table information in the object
file. The extended symbol table contains the names of all the
source files processed by the compiler as well as any symbolic
information in those files (for example, routine names, variable
names, and line numbers). This information allows you to look at
all of the source code that went into creating an object file
during your debugging session. If your object file does not con‐
tain the extended symbol table information, use the commands
described in the Debugging at the Machine Code Level section to
debug your program.
If you omit objectfile, dbx prompts you for the name of an
object file. If you press the Return key, dbx attempts to read a
file named a.out from the current directory. If no a.out file
exists, dbx exits. Specifies a core dump file, created if a
program failed during execution or if the coredump(1) command
was used to take a core snapshot of a running process. The dump
file holds an image of memory at the time the program failed or
the snapshot was taken. If you specify a core file on the com‐
mand line, dbx identifies where the program failed or the snap‐
shot was taken, and you can then use dbx commands to determine
the state of the program at that time.
Core dump files are all named core by default. See the Program‐
mer's Guide for information about enabling core-file naming at
the system or application level.
DBX COMMANDS
The debugger supplies a number of commands that you can issue at the
dbx prompt.
Multiple commands can be specified on the same command line by separat‐
ing them with a semicolon (;).
You can repeat dbx commands by pressing carriage return. Pressing car‐
riage return repeats the last command issued to dbx. (This feature can
be turned off by setting the $repeatmode variable to 0.)
The following sections describe the commands supported by dbx.
Controlling the Monitor
Use the following commands to control the dbx monitor: Executes a com‐
mand from the history list. You can specify the command name in the
string argument. If you specify an integer, dbx executes the command
having that number in the history list. If you specify -integer, the
debugger executes the command that you issued integer commands ago.
For example, if you specify -3, the debugger issues the command you
issued three commands ago. The debugger echoes the command on standard
output before executing it. With no argument, displays a list of top‐
ics for which help information is available. If you name a topic, the
debugger displays help information on that topic. Displays a list of
the previous commands you issued. By default, the debugger displays the
previous 20 commands. You can change the number of commands dbx keeps
in the history list by using the set command to modify the $lines
debugger variable.
Predefined alias for history command: h Exit dbx. Predefined
alias for quit command: q
Controlling dbx
Use the following commands to control the operation of the dbx debug‐
ger. Lists all existing aliases or defines an alias. If you omit all
arguments to the alias command, dbx displays a list of the existing
aliases.
You can supply arguments to define a new alias. If you specify a
dbx command for string, the debugger assigns name as an alias
for that command. For example, to define an alias rr for the
command rerun, issue the following command:
(dbx) alias rr "rerun"
If you specify parameters in the alias command, the debugger
substitutes the values you supply on the command line when it
executes the command. For example, to define halt as an alias
that sets a stop at a particular line, issue the following com‐
mand:
(dbx) alias halt(x) "stop at x"
Once you issue this command, dbx interprets the following com‐
mands as the same:
(dbx) halt(12) (dbx) stop at 12
Both commands set a breakpoint at source line 12.
To remove an alias, use the unalias command, as shown:
(dbx) unalias halt Deletes the specified breakpoint, trace
event, or record event from the status list. The argument all
and the argument * delete all events from the status list.
Predefined alias for delete command: d Displays the names of the
objects that have been loaded by dbx. These objects include the
main program and all of the shared libraries that are used in
the application. Replays commands that were saved with the
record input command in a text file. If you omit file, the
debugger reads commands from the temporary file it creates by
default when you issue the record input command.
Predefined alias for playback input command: pi or source.
Replays debugger output that was saved with the record output
command. If you omit file, the debugger displays output stored
in a temporary file it creates by default when you issue the
record output command.
Predefined alias for playback output command: po Records all
commands you enter at the dbx prompt. If you omit file, the
debugger creates a temporary file that it deletes when you exit
from the debugger.
The debugger associates an event number with each record command
you issue. You use the event number to turn off recording, as
described with the delete command.
Predefined alias for record input command: ri Records all dbx
output. If you omit file, the debugger creates a temporary file
that it deletes when you exit from the debugger. To record input
and output to the same file, set the $rimode debugger variable.
The debugger associates an event number with each record command
you issue. You use the event number to turn off recording, as
described with the delete command.
Predefined alias for record output command: ro Executes the dbx
commands from the specified file. This command is an alias for
the playback input command. Lists current breakpoints, record
events, and trace events.
Predefined alias for status command: j Lists existing debugger
variables and their values or defines a value for the named
debugger variable.
Some debugger variables contain either a zero or nonzero value
that controls dbx behavior. For example, when set to a nonzero
value, the $hexstrings variable causes the debugger to display
all strings in hexadecimal format. When set to zero, this vari‐
able causes the debugger to display strings in character format.
You can set a variable like $hexstrings to a nonzero value as
shown:
(dbx) set $hexstrings = 1
You can disable the variable using the unset command, as shown:
(dbx) unset $hexstrings
You can create a debugger variable using a name of your own. A
debugger variable name you create must not conflict with the
name of any variable in the program you are debugging, and it
must not begin with a dollar sign ($). For information on
existing debugger variables, see PREDEFINED DBX VARIABLES. (Use
the assign command to change the value of variables in your pro‐
gram. See the section Preparing for Program Execution for infor‐
mation on the assign command.) Sets the environment variable
name to string by changing the value of an existing environment
variable or creating a new one. To reset the environment vari‐
able, specify a null string. The following example shows how to
reset the EDITOR environment variable:
(dbx) setenv EDITOR "" Calls a shell from dbx or executes the
specified shell command. The sh command cannot be used in the
action list of the when and wheni dbx commands. Returns the
value of tagname, where tagname is a tag that marks a function
or type definition in your program. If the tag extends to more
than one line or if it contains arguments, the debugger issues
an error message. You can use tagvalue in commands where you
specify a procedure or function name.
For example, if a tag getline is associated with a function, the
following command is valid:
(dbx) call tagvalue(getline) ()
This command causes execution to begin at the location associ‐
ated with the getline tag.
You create tags using the ctags command. See ctags(1) for
information. The debugger uses the file named in the $tagfile
variable when resolving references to tags. Removes the speci‐
fied alias. Removes the setting of a specified debugger vari‐
able.
Examining Source Code
The following commands allow you to examine your source files during a
debugging session: Searches forward or backward in the source code for
the regular expression. Invokes an editor on file or the current
source file if none is specified. By default, dbx invokes the vi edi‐
tor. You can override the default setting by modifying the EDITOR
environment variable. Changes the current file to file, or, if you
omit file, displays the name of the current file.
Predefined alias for file command: e Changes the current proce‐
dure or function to the one you specify. If you omit expression
and procedure, the debugger displays the name of the current
procedure or function.
Changing the current function implicitly changes the current
source file to the one that contains the procedure or function;
it also changes the current scope used for name resolution.
Predefined alias for func command: f Lists the lines in the cur‐
rent source file.
If you specify a source line number and an integer, dbx lists
beginning from source-line-number and continuing for integer
number of lines. If you omit integer, the debugger displays 10
lines by default.
If you specify two source line numbers separated by a comma, the
debugger begins the display at the first source line number and
continues through the second source line number. If you omit
the second source line number, the debugger displays 10 lines by
default.
If you specify a procedure or function name, the debugger dis‐
plays lines in that procedure or function. The debugger displays
10 lines by default.
If you omit all arguments, the debugger begins the display at
the current line and displays 10 lines by default.
The $listwindow debugger variable controls how many lines the
debugger displays. The default value for $listwindow is 10.
Predefined aliases for list command: The next 10 lines of source
code. The next 10 machine instructions after the current
machine instruction. The previous 10 lines of source code. The
five lines before and after the current line. The 10 lines
before and after the current line. The five machine instruc‐
tions before and after the current one. Sets the current source
file or source line to the location specified by tagname.
You create tags using the ctags command. See ctags(1) for more
information. The debugger uses the tag file named in the $tag‐
file debugger variable to resolve references to tags. Displays
or sets the list of directories that dbx uses when searching for
source files. If you issue the use command without arguments,
the debugger displays the list of directories it searches for
source files. To change the directory list, specify the names
of the directories you want on the list as arguments to the use
command. The directories you specify replace any existing
directory list. Give absolute or relative pathnames; ~ is not
supported.
The use command looks first for source files in the path con‐
sisting of the complete source path used when the file was com‐
piled appended to the directory specified in the use command.
If the use command cannot find the source file with that path,
it takes the directory specified by the use command and only the
filename part of the compilation source path.
For example, when you built the program, the sources were in
/usr/src/project. For some reason, perhaps because of different
NFS mounting, when you run it, the sources are in /project. You
enter:
(dbx) use /project
The use command looks for /project/../../src/project/filename.c
and cannot find it. If you enter the following command, the use
command can find the source file:
(dbx) use /project/filename.c Displays the type declaration for
variable. (If variable is a dbx keyword, it must be enclosed
within parentheses.) Displays the fully qualified name of each
occurrence of variable. The order in which the debugger displays
the qualified names is not meaningful. (If variable is a dbx
keyword, it must be enclosed within parentheses.) Displays the
fully qualified name of variable. (If variable is a dbx keyword,
it must be enclosed within parentheses.)
Preparing for Program Execution
Before you execute your program under dbx control, you might want to
perform setup tasks, such as changing the value of debugger variables,
specifying what signals your program should recognize or ignore, and
setting breakpoints. The following commands allow you to perform these
tasks: Loads a shared library and reads in the library's symbol table.
If you specify an absolute or relative path (path) for the
library, dbx looks only in the specified location. If you spec‐
ify only the library file name (file), dbx first looks for that
file in the directory specified by the $module_path variable, if
set. If $module_path is not set or if dbx cannot find the file
in the specified directory, it looks in the directory where that
file was originally, as recorded in the object (or in the dump,
if debugging a core dump).
Use this command only for debugging applications that load in
their own shared libraries instead of using the dynamic loader.
For applications that do not load their own shared libraries,
dbx will obtain the names of the shared libraries from the
dynamic loader.
Limitation: dbx will not work correctly when a shared library is
added with the addobj command and the library is loaded at an
address that differs from the address at which it was linked.
You can also use the addobj command to load loadable modules
when debugging a kernel. In general, the basic considerations
described above for shared libraries also apply to loadable mod‐
ules. For complete information on kernel debugging, see the Ker‐
nel Debugging manual. Assigns the value of the specified
expression to the specified program variable. The program must
be running for the assign command to work. (If variable is a
dbx keyword, it must be enclosed within parentheses.)
Use the set command to set the value of debugger variables.
Predefined alias for assign command: a Lists all signals that
dbx catches or, if you supply an argument, causes dbx to catch
that signal. The signal you specify is added to the list of
signals dbx catches, so the debugger continues to catch any sig‐
nals that were already on its list. Some signals cannot be
caught by any process. For a list of signals and information on
which signals can be caught, see signal(4) for more information.
Lists all signals that dbx ignores. If you specify a signal,
this command adds the signal to the list of signals the debugger
ignores. Some signals cannot be ignored by any process. For a
list of signals and information on which signals can be ignored,
see signal(4) for more information. Patches executable disk
files to correct bad data or instructions. The text, initialized
data, or read-only data areas can be patched. The bss segment
cannot be patched because it does not exist in disk files.
Examples:
patch &main = 0 patch foo = 20 or patch &foo = 20 patch 0xnnnnn
= 0xnnnnn Stops execution when the specified variable changes
value, the specified source line is reached, the specified pro‐
cedure or function is called, or the specified condition is
true. The condition must be a Boolean expression. (If variable
is a dbx keyword, it must be enclosed within parentheses.)
If you specify variable with a source line number, the debugger
stops execution when the source line number is reached and the
variable changes value. If you specify variable with in proce‐
dure, the debugger stops execution when it is executing in the
named procedure or function and the named variable changes
value. With if condition, the debugger stops execution when the
condition is met and the variable changes value.
If you specify a condition with at source-line or in procedure,
the debugger stops only if the condition is true.
The debugger associates an event number with each stop command
you issue. You use the event number to remove the breakpoint,
as described with the delete command.
Predefined aliases for stop command: Sets a breakpoint at a
specified line. Stops in a specified procedure. Displays trac‐
ing information during program execution. The dbx debugger as‐
sociates an event number with each trace command you issue. You
use the event number to turn off tracing, as described with the
delete command. (If variable is a dbx keyword, it must be
enclosed within parentheses.)
The first argument to the trace command specifies what the
debugger is to trace. You can specify a source line number, a
procedure name, or a variable name.
If you specify a source line number, dbx displays the source
line immediately prior to executing it. You can specify a
source line number in a source file that is not the current one.
To do so, precede the source line number with the source file
name in quotation marks (" ") followed by a colon (:), as shown
in the following example:
(dbx) trace at "source_file.c":17
The example specifies tracing line 17 in source_file.c.
Specifying a procedure or function name causes dbx to display
the name of the calling routine, the source line that contains
the call, and the parameters that are passed to the called rou‐
tine. In addition, dbx notes the return of the named procedure
or function and displays the return value, if any. The debugger
displays this information each time the procedure or function is
called.
Specifying a variable name causes dbx to display the name and
value of the variable each time it changes. Program execution is
substantially slower during this form of tracing.
If you specify the in procedure clause, dbx displays tracing
information only while executing the specified procedure or
function.
The condition is a Boolean expression that dbx evaluates prior
to displaying any tracing information. The debugger displays
tracing information only if the condition is true.
Predefined alias for trace command: tr Executes the specified
dbx command list. You can separate the commands by commas (,)
or semi-colons (;).
If you specify variable, the debugger executes the command list
when the value of the variable changes. Specify at line or in
procedure to control which occurrence of the variable causes the
debugger to execute the command list. (If variable is a dbx key‐
word, it must be enclosed within parentheses.)
Initiating Program Execution
The following commands allow you to control program execution: Executes
the object code associated with the named procedure or function. This
command passes the specified parameters to the procedure or function.
The print and call commands treat values returned by called pro‐
cedures differently: the print command displays them and the
call command does not. Continues execution from where it
stopped. If you specify an integer n, the debugger ignores that
number of stops after it resumes program execution. If you spec‐
ify signal, the process continues as though it received the sig‐
nal.
If you specify to source-line, the debugger continues execution
until it reaches the specified source line.
If you specify in procedure, the debugger continues until the
specified procedure after receiving the specified signal.
Predefined alias for cont command: c Branches to the specified
source line. Execution continues from that point when you issue
a cont command.
Predefined alias for goto command: g Executes up to the next
source line.
The next command does not step into procedures of functions;
execution stops at the source line that follows the call. If you
specify integer, the debugger performs the specified number of
next commands.
Predefined alias for next command: n Reruns the program, using
the same arguments that were specified with the run command. If
you specify new arguments, rerun uses those arguments.
You can use angle brackets (< or >) to redirect input or output
in the usual manner.
Predefined alias for rerun command: r Runs the program, passing
it the specified arguments. Arguments containing brackets ([]),
asterisks (*), or other special characters must be enclosed in
quotes or escaped to avoid parsing errors.
You can use angle brackets (< or >) to redirect input or output
in the usual manner. Executes until a return to procedure is
executed or until the current procedure or function returns if
you omit procedure. Executes one source line. If the source
line contains a call to a procedure or function, the step com‐
mand stops at the first line of the procedure or function. (The
debugger does not stop at the first line of a procedure or func‐
tion if you compiled your program without using the -g option.)
If you specify integer, the debugger performs the specified num‐
ber of step commands.
Predefined alias for step command: s
Examining Program State
Use the following commands to determine the state of your program: Dis‐
plays variable information about the named procedure or function, or
the current procedure or function if you do not specify one. If you
specify dot (.), the debugger displays information on all procedures or
functions in the stack and their variables. Moves the current function
down in the stack (based on the number of activation levels that you
specify). The default is one level. Moves the current function up in
the stack (based on the number of activation levels that you specify).
The default is one level. Displays the value of the specified expres‐
sion. (If a specified expression contains the name of a variable that
is also a dbx keyword, the variable name must be enclosed within paren‐
theses.)
Predefined alias for print command: p Formats an expression as
specified. You use the same format specifiers for this command
as for the printf subroutine. For information on specifying the
format, see printf(3). (The %s conversion specification is not
supported.)
Predefined aliases for printf command print the following val‐
ues: The specified expression or variable in decimal. The spec‐
ified expression or variable in octal. The specified expression
or variable in hexadecimal. Displays all register values.
Predefined alias for printregs command: pr Displays a list of
the active procedures and functions. If you specify n, the
debugger displays only procedures and functions in the top n
levels of the stack.
Predefined alias for where command: t
Attaching to a Running Process
The dbx debugger supports /proc debugging. The major advantage of this
is that it allows attaching to a running process and this can be used
to attach to a child process. In order to do this, the /proc filesys‐
tem must be mounted. The following commands are available to attach to,
and detach from, a running process: Use this command to attach to a
running process, where xxx is the proc id of the process you want to
attach to. This command checks to see if /proc is mounted. If it is
mounted, dbx will then look for the proc id in /proc. If the proc id
is present, dbx will attempt to open the process, issue a stop command,
report the current position, and issue the dbx> prompt. Use this com‐
mand to detach from a running process, where the optional xxx is the
proc id of the process you want to detach from. Use this command to
switch from one process to another, where xxx is the proc id of the
process you want to switch to. You must already have attached to the
target process using the attach command. Use this command to display a
list of active processes and their status. The debugger indicates the
current process with a marker: -->
Debugging at the Machine Code Level
You can use machine level commands to debug any program, regardless of
whether the program object file contains extended symbol table informa‐
tion.
You can specify symbolic addresses by preceding the name with an amper‐
sand (&). You denote registers by $rN, where N is the number of the
register. Addresses may be expressions made up of other addresses and
the operators plus (+), minus (-), and indirection (unary asterisk, *).
Use the following commands to debug programs at the machine code level:
Searches forward (or backward, if you specify ?) and displays the con‐
tents of address or disassembles the code for the instruction address.
The count argument specifies the number of items that the debugger dis‐
plays at the specified address. The mode determines how dbx displays
memory; if you omit it, the debugger uses the previous mode. The ini‐
tial mode is X. You can specify the following modes: Displays a byte
in octal. Displays a byte as a character. Displays a 16-bit value in
decimal. Displays a 32-bit value in decimal. Displays a 64-bit value
in decimal. Displays a single precision real number. Displays a dou‐
ble precision real number. Displays machine instructions. Displays
data in typed format. Displays a 16-bit value in octal. Displays a
32-bit value in octal. Displays a 64-bit value in octal. Displays a
string of characters that ends in a null. Displays a 16-bit value in
hexadecimal. Displays a 32-bit value in hexadecimal. Displays a
64-bit value in hexadecimal.
The debugger maintains the next address to be displayed in dot
(.). To display the next address, you can use the following
command:
(dbx) ./
The debugger will display the next count locations in the mode
specified in the previous command. Searches for a 64-bit word
that satisfies the mask. The debugger starts searching at the
specified address. The count argument specifies the number of
words the debugger processes during the search. You type the M
to specify a match.
The debugger masks the word stored at address using the value
specified in mask. If the masked value equals value, the debug‐
ger displays the address of the masked value. Otherwise, the
debugger increments address and continues to search. Continues
execution of assembly code from where it stopped. If you specify
an integer n, the debugger ignores that number of stops after it
resumes program execution. If you specify signal, the process
continues as though it received the signal.
If you specify to address, the debugger continues execution
until it reaches the specified address.
If you specify in procedure, the debugger resumes execution in
the named procedure or function. Executes up to the next
machine instruction. The nexti command does not step into proce‐
dures or functions; execution stops at the machine instruction
that follows the call.
If you specify an integer, the debugger performs integer nexti
instructions.
Predefined alias for nexti command: ni Executes the specified
number of machine instructions. If one of the machine instruc‐
tions contains a call to a procedure or function, the debugger
stops at the first instruction of the procedure or function.
The default is to execute one instruction.
Predefined alias for stepi command: si Stops when the specified
variable changes value, the specified address is reached, the
specified condition is true, or the specified procedure or func‐
tion is reached. (If variable is a dbx keyword, it must be
enclosed within parentheses.)
By combining the arguments, you can cause the debugger to stop,
for example, only when the occurrence of variable at the speci‐
fied address changes value and condition is true. Traces the
value of variable or the execution of a particular address. (If
variable is a dbx keyword, it must be enclosed within parenthe‐
ses.)
When you trace the value of a variable, you can use at address,
in procedure, and if condition to control the specific variable
that is traced.
You can specify a condition when you trace the execution of an
address. The debugger displays tracing information only when
the condition is true. Executes the specified dbx machine com‐
mand list. You can separate the commands by commas (,) or semi-
colons (;).
If you specify variable, the debugger executes the command list
when the value of the variable changes. Specify at address or
in procedure to control which occurrence of the variable causes
the debugger to execute the command list. (If variable is a dbx
keyword, it must be enclosed within parentheses.)
PREDEFINED DBX VARIABLES
The debugger contains variables that control certain aspects of its
operations. Some debugger variables are used internally by dbx. You
must not change the value of those variables. The debugger allows you
to change the values of other variables using the set and unset com‐
mands. The following list describes the debugger variables you can
control: Specifies the format for addresses. You can set this variable
to any format that you can use with the printf function, except %s
because the %s conversion specification is not supported by dbx. See
printf(3) reference page for information on valid formats. By default,
this variable is set to 0x%x, which specifies hexadecimal format. When
set to a positive nonzero value, indicates that dbx is in asynchronous
mode. When 0 (zero) or negative, indicates that asynchronous debugging
is disabled. Incremented by 1 when a new process is attached and
decremented by 1 when a process terminates or is detached. The default
value is 0. To prevent dbx from entering asynchronous mode, set
$asynch_interface to a negative value. When set to a nonzero value,
specifies that uppercase and lowercase letters be treated as different
characters during a search. When $casesense is set to zero, dbx
ignores the case of letters. The default is zero. The $casesense
variable has no effect on the interpretation of eight-bit characters;
thus, for example, A-acute-accent and a-acute-accent are always treated
as different characters. Caches information from the data space so
that dbx must access the data space only once. If this variable is set
to zero, the debugger does not cache data space. If your program con‐
tains any data declared as volatile, you may want to set this variable
to zero. To debug the operating system, set this variable to zero;
otherwise, set it to a nonzero value. The default is a nonzero value.
Causes the debugger to be in the correct mode to debug pixie code. When
set to zero, the debugger displays machine code while debugging. When
set to a nonzero value, the debugger displays pixie code. The default
is zero. When set to a nonzero value, causes the debugger to display
characters in hexadecimal format. When set to a nonzero value, causes
the debugger to interpret input constants as hexadecimal. When set,
this variable overrides the $octin variable. When set to a nonzero
value, changes the default output constants to hexadecimal. When set,
this variable overrides the $octints variable. When set to a nonzero
value, causes the debugger to display all strings in hexadecimal for‐
mat. When set to zero, causes the debugger to display strings in char‐
acter format. Stores the current history line. Determines how many
lines the debugger stores in its history list. The default is 20 lines.
Specifies how many lines the list command displays. The default is 10
lines. Specifies the name of the procedure or function that dbx begins
when running the process. The debugger can begin a process at any pro‐
cedure or function. By default, the debugger begins a process at a
procedure named main. Specifies how many characters of a string dbx
displays for pointers to strings. The default is 128 characters.
Specifies the directory path where dbx should search for shared
libraries (or loadable kernel modules). This variable is useful if, for
example, you are debugging a core dump (or a kernel crash dump) and the
version of a shared library (or module) that was running when the dump
occurred has been moved to a different location. Setting this variable
with the set command affects only any files that are loaded after the
variable is set. To affect files that are loaded at dbx startup, use
the -module_path option or the DBX_MODULE_PATH environment variable.
See also the addobj command. For information on kernel debugging see
the Kernel Debugging manual. When set to a nonzero value, causes dbx
to print the location of shared libraries (or loadable kernel modules,
if debugging a kernel) as they are being loaded. By default, or when
this variable is set to zero, dbx does not print the location. See also
the -module_verbose option and the DBX_MODULE_VERBOSE environment vari‐
able. For information on kernel debugging, see the Kernel Debugging
manual. When set to a nonzero value, changes the default input con‐
stants to octal. When set, the $hexin variable overrides this vari‐
able. When set to a nonzero value, causes dbx to display integers in
octal format. When set, the $hexints variable overrides this variable.
Specifies whether to page long information. A nonzero value turns on
paging; a zero turns it off. The default is one. Specifies how many
lines the debugger displays when information runs longer than one
screen. You can change this variable to match the number of lines on
any terminal. If set to zero, this variable assumes one line. The
default is 65. This variable affects only C++ modules. It specifies
whether to print function parameters from C++ modules when displaying a
stack trace (as from a where command). A nonzero value enables this
feature. A value of zero (the default) disables it -- that is, a C++
parameter list is shown empty in the stack trace (for example, my_rou‐
tine()).
The default was chosen because dbx does not support complex C++
types beyond those supported for C, and a segmentation fault
will occur if dbx tries to print function parameters of complex
C++ types in a stack trace. (However, dbx then regains control
and displays its prompt.) If you are debugging C++ modules that
have only simple (C) function-parameter types, setting $printc‐
plusparams to 1 will enable dbx to print these parameters in a
stack trace. Determines whether the debugger displays source
lines or instructions when executing the step[n] and stepi[n]
commands. When set to a nonzero value, causes dbx to display all
n lines or instructions. When set to zero, causes dbx to dis‐
play only the last line or instruction. The default is zero.
Displays input when used with the playback input command. The
default is zero. When set to a nonzero value, causes the debug‐
ger to display the contents of registers next to each instruc‐
tion it displays. The debugger displays the registers used by
the instruction. The default is zero. When set to a nonzero
value, causes the debugger to display the contents of variables
in a horizontal format. The default is zero. Sets the prompt
for dbx. When set to a nonzero value, causes dbx to read
instructions from the object file rather than the process. This
variable should always be set to zero when the process being
debugged copies in code during the debugging process. The
default is a nonzero value. When set to a nonzero value, causes
the debugger to display registers during disassembly in their
normal r format (r0,r1,...,r31). When set to zero, causes the
debugger to display registers in a special format (zero, at, v0,
v1,...), which is commonly used in debugging programs written in
assembly language. The default is a nonzero value.
Setting this variable does not affect how the debugger displays
the names of registers when you issue the printregs command.
This variable affects the debugger's machine level commands.
When set to a nonzero value, causes dbx to repeat the previous
command if you press the Return key at the dbx prompt. The
default is a nonzero value. When set to a nonzero value, causes
the debugger to record input while recording output. The
default is zero. Tells dbx the name of the code called by the
system to invoke user signal handlers. This variable is set to
sigaction on Tru64 UNIX systems. Meaningful only when
$stop_on_fork is set. If set to 1, dbx stops every time a new
image is forked. If set to 0, dbx ignores most forks arising
from system and library calls. The default is 0. When set to
1, *Ldbx detects calls to execl and execv and stops the newly
executed images at the first line of executable code. The
default is 1. If set to 1, specifies that dbx should stop when
a new image is forked. If set to 0, instructs dbx to continue
into the new image without stopping. The default is 1. Names
the file that contains tags for the current program. The tag
and tagvalue commands search the named file to resolve refer‐
ences to tags. For more information on using tag files, see
ctags(1). Specifies the number of times dbx can ignore a SIG‐
TRAP without being interrupted by another signal or breakpoint
type. This variable helps avoid the infinite loop that can
occur when you set a breakpoint in a SIGTRAP signal handler
function. The default number for this variable is 3.
DESCRIPTION
The dbx command invokes a source-level debugger. You can use dbx to
debug programs written in C, Fortran, Pascal, assembly language, and
machine code. Languages other than these are not supported by dbx.
After invoking the dbx debugger, you issue dbx commands that allow you
to examine source files, control program execution, display the state
of the program, and debug at the machine level.
The OPERANDS section describes the objectfile and corefile operands. Be
sure to compile your program with the -g option so that the object file
contains the symbol table information needed for source-level debug‐
ging.
You can use command options to modify some steps that dbx performs dur‐
ing startup. (For information on the available options, see the OPTIONS
section.) Unless you specify the -r option, dbx prompts you for a com‐
mand before it begins executing your program. The dbx prompt appears as
follows: (dbx)
To leave dbx, issue the quit command.
See the Guide to the POSIX Threads Library for information on how to
debug multithreaded applications.
Initialization File
During its startup, dbx reads and executes the commands in an initial‐
ization file (if present). By default, dbx searches for the initial‐
ization file in the current directory. If no file exists in the cur‐
rent directory, dbx searches your home directory for the file. You can
use the initialization file to issue setup commands automatically when
you begin a dbx session. (See the section PREDEFINED DBX VARIABLES for
information on the debugger variables that you can control in the ini‐
tialization file.)
Debugger Expressions
You specify dbx expressions using the C syntax for expressions. The
debugger supports a subset of the expression syntax. For example, you
can denote indirection using either an asterisk (*) as a prefix or a
circumflex (^) as a suffix. You can use the field reference operator
(.) with pointers as well as with records or structures, making the C
operator (->) unnecessary (although it is supported).
You must enclose array expressions in brackets ([ ]).
You can also specify a register name in an expression. You denote reg‐
isters by $rN where N is the number of the register.
The debugger supports symbol names and string literals containing dis‐
playable characters in the eight-bit ISO Latin-1 character set.
Debugger Name Resolution
The debugger resolves names by searching for the name in the static
scope of the current function. If no name is defined in the static
scope, the debugger searches the dynamic scope. If neither scope
yields a defined name, the debugger chooses an arbitrary symbol and
displays the following message: [using qualified.name]
The debugger substitutes the qualified name of the arbitrary symbol for
qualified.name in the message.
You can override this name resolution procedure by qualifying identi‐
fiers with a block name, as in module.variable. For the C language, the
debugger treats a source file as a module named from the filename with‐
out the suffix.
Command Line Editing
The dbx monitor provides commands that permit command-line editing.
These commands allow you to correct mistakes without re-entering an
entire command. There are two line-editing modes, vi mode and emacs
mode.
To enable a mode similar to the Korn shell's vi mode, set the EDITOR or
EDITMODE environment variable to a path ending in vi before starting
dbx. In vi mode, the following editing keys are recognized:
$ + - 0 A B C D E F I R S W X ^ a b c d e f h i j k l r s w x ~ Ctrl/D
Ctrl/H Ctrl/J Ctrl/L Ctrl/M Ctrl/C
See ksh(1) for more information.
To enable a mode similar to the Korn shell's emacs mode, set the
LINEEDIT environment variable to any value, or set EDITOR or EDITMODE
to a path ending in emacs, before starting dbx. The debugger treats ^K
differently depending on whether the mode is enabled by LINEEDIT or by
EDITOR or EDITMODE. In emacs mode, the following editing keys are rec‐
ognized: Move the cursor to the beginning of the command line. Move
the cursor back one character. Clear the line. Delete the character
at the cursor. Move the cursor to the end of the line. Move the cur‐
sor ahead one character. Delete the character immediately preceding
the cursor. Execute the line. (When enabled by LINEEDIT) Delete char‐
acters until the cursor rests on the next occurrence of char. (When
enabled by EDITOR or EDITMODE) Delete from the cursor to the end of
the line. If preceded by a numerical parameter whose value is less
than the current cursor position, delete from given position up to the
cursor. If preceded by a numerical parameter whose value is greater
than the current cursor position, delete from cursor up to given posi‐
tion. Redisplay the current line. Execute the line. Move to the next
line in the history list. Move to the previous line in the history
list. Search back in the current line for the specified character.
Interchange the two characters immediately preceding the cursor.
Repeat the next character four times. Delete the entire line. Insert
immediately before the cursor any text cut with ^K. Try to complete a
file or symbol name. Try to complete a file or symbol name. Move to
the next line in the history list. Move to the previous line in the
history list. Move the cursor back one character. Move the cursor
ahead one character.
Note
The notation ^ represents the CTRL key. For example, ^A indicates that
the CTRL and A keys should be pressed simultaneously.
RESTRICTIONS
The printf debugger command does not support the %s conversion specifi‐
cation.
ENVIRONMENT VARIABLES
Specifies the directory path where dbx should search for shared
libraries (or loadable kernel modules). This environment variable is
useful if, for example, you are debugging a core dump (or a kernel
crash dump) and the version of a shared library (or module) that was
running when the dump occurred has been moved to a different location.
Setting this environment variable automatically sets the $module_path
dbx variable to the specified path. If dbx cannot find a file in the
specified directory, it looks in the directory where that file was
originally, as recorded in the dump. See also the -module_path option.
For information on kernel debugging see the Kernel Debugging manual.
When set to any value, causes dbx to print the path of shared libraries
(or loadable kernel modules, if debugging a kernel) as they are being
loaded. By default, dbx does not print the path. Setting this environ‐
ment variable to any value automatically sets the $module_verbose dbx
variable to the value 1. See also the -module_verbose option. For
information on kernel debugging, see the Kernel Debugging manual.
FILES
Object file Core dump file Initialization file
SEE ALSO
Commands: as(1), cc(1), coredump(1), ctags(1), pixie(5), vi(1)
Routines: printf(3), signal(4), kdbx(8)
Kernel Debugging
Programmer's Guide
Guide to the POSIX Threads Library
dbx(1)