dbx - source level debugger
dbx [-I dir] [-c file] [-k] [-i] [-r] [-pid xxx] [objectfile
[corefile]]
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 location.
Using this option 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 DBX_MODULE_PATH environment variable.
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 displays 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.
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 contain 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
command line, dbx identifies where the program
failed or the snapshot 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 Programmer's Guide for information about
enabling core-file naming at the system or application
level.
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 separating them with a semicolon (;).
You can repeat dbx commands by pressing carriage return.
Pressing carriage 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 [Toc] [Back]
Use the following commands to control the dbx monitor:
Executes a command 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 topics 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 [Toc] [Back]
Use the following commands to control the operation of the
dbx debugger. 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 command:
(dbx) alias halt(x) "stop at x"
Once you issue this command, dbx interprets the
following commands 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 variable 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 program. See the section
Preparing for Program Execution for information 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 variable, 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
associated 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 specified alias.
Removes the setting of a specified debugger variable.
Examining Source Code [Toc] [Back]
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 editor.
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 procedure 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 current 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 displays 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 instructions 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 $tagfile 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 consisting of the complete source path used
when the file was compiled 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 [Toc] [Back]
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 specify 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 modules. For complete
information on kernel debugging, see the Kernel
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
signals 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 procedure 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 procedure, 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 tracing information during
program execution. The dbx debugger associates 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 routine. 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 keyword, it must be enclosed within parentheses.)
Initiating Program Execution [Toc] [Back]
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 procedures 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 specify signal, the process continues as
though it received the signal.
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 command stops at the first line of
the procedure or function. (The debugger does not
stop at the first line of a procedure or function
if you compiled your program without using the -g
option.)
If you specify integer, the debugger performs the
specified number of step commands.
Predefined alias for step command: s
Examining Program State [Toc] [Back]
Use the following commands to determine the state of your
program: Displays 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
expression. (If a specified expression contains the name
of a variable that is also a dbx keyword, the variable
name must be enclosed within parentheses.)
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 values: The specified expression or variable
in decimal. The specified 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 [Toc] [Back]
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 filesystem 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 command 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 [Toc] [Back]
You can use machine level commands to debug any program,
regardless of whether the program object file contains
extended symbol table information.
You can specify symbolic addresses by preceding the name
with an ampersand (&). 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 contents of address or disassembles
the code for the instruction address. The count
argument specifies the number of items that the debugger
displays at the specified address. The mode determines how
dbx displays memory; if you omit it, the debugger uses the
previous mode. The initial 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 double 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 debugger 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 procedures 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 instructions 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 function 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 specified 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 parentheses.)
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 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 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 [Toc] [Back] 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 commands.
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, Aacute-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 contains 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 format. When set to
zero, causes the debugger to display strings in character
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 procedure 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 variable.
For information on kernel debugging, see the Kernel
Debugging manual. When set to a nonzero value, changes
the default input constants to octal. When set, the
$hexin variable overrides this variable. 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_routine()).
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 $printcplusparams 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 display 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 debugger to display the
contents of registers next to each instruction 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 references to
tags. For more information on using tag files, see
ctags(1). Specifies the number of times dbx can
ignore a SIGTRAP 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.
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 debugging.
You can use command options to modify some steps that dbx
performs during startup. (For information on the available
options, see the OPTIONS section.) Unless you specify the
-r option, dbx prompts you for a command 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 [Toc] [Back]
During its startup, dbx reads and executes the commands in
an initialization file (if present). By default, dbx
searches for the initialization file in the current directory.
If no file exists in the current 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 initialization file.)
Debugger Expressions [Toc] [Back]
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 registers by $rN where N is the number of the register.
The debugger supports symbol names and string literals
containing displayable characters in the eight-bit ISO
Latin-1 character set.
Debugger Name Resolution [Toc] [Back]
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
identifiers 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 without the suffix.
Command Line Editing [Toc] [Back]
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 recognized: 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 cursor ahead one
character. Delete the character immediately preceding the
cursor. Execute the line. (When enabled by LINEEDIT)
Delete characters 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 position. 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.
The printf debugger command does not support the %s conversion
specification.
ENVIRONMENT VARIABLES [Toc] [Back] 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 environment 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.
Object file Core dump file Initialization file
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)
[ Back ] |
