 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dbx(1)
NAME
dbx - source level debugger
SYNOPSIS
dbx [-I dir] [-c file] [-k] [-i] [-r] [-pid xxx] [objectfile [corefile]]
OPTIONS
The dbx debugger accepts the following options:
-c file
Selects a command file other than .dbxinit.
-i Invokes dbx in interactive mode. This option causes the debugger to
not treat source lines beginning with number signs (#) as comments.
-I dir
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.
-k Maps memory addresses. This option is useful for kernel debugging. For
information on kernel debugging, see the Kernel Debugging manual.
-module_path path
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.
-module_verbose
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.
-r 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.
-remote
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).)
-emacs
Outputs file and line number information in a format compatible with
the emacs function gdb.
-pid xxx
Attaches dbx to a currently running process specified by process id
xxx.
OPERANDS
objectfile
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.
corefile
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.
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 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
Use the following commands to control the dbx monitor:
!string or !integer or !-integer
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.
help [topic]
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.
history
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
quit
Exit dbx. Predefined alias for quit command: q
Controlling dbx
Use the following commands to control the operation of the dbx debugger.
alias [name[(arg1,arg2,...)]string]
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
delete event-number, ... or delete all or delete *
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
listobj
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.
playback input [file]
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.
playback output [file]
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
record input [file]
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
record output [file]
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
source file
Executes the dbx commands from the specified file. This command is an
alias for the playback input command.
status
Lists current breakpoints, record events, and trace events.
Predefined alias for status command: j
set [variable = expression]
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.)
setenv name string
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 ""
sh [shell command]
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.
tagvalue (tagname)
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.
unalias name
Removes the specified alias.
unset variable
Removes the setting of a specified debugger variable.
Examining Source Code
The following commands allow you to examine your source files during a
debugging session:
regular expression or ?regular expression
Searches forward or backward in the source code for the regular
expression.
edit [file]
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.
file [file]
Changes the current file to file, or, if you omit file, displays the
name of the current file.
Predefined alias for file command: e
func [expression]
func [procedure]
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
list [source-line-number[:integer]]
list [source-line-number[, source-line-number]]
list [procedure]
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:
l The next 10 lines of source code.
li The next 10 machine instructions after the current machine
instruction.
u The previous 10 lines of source code.
w The five lines before and after the current line.
W The 10 lines before and after the current line.
wi The five machine instructions before and after the current one.
tag tagname
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.
use [directory ...]
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
whatis variable or whatis struct name
Displays the type declaration for variable. (If variable is a dbx
keyword, it must be enclosed within parentheses.)
whereis variable
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.)
which variable
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:
addobj path|file
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.
assign variable = expression
assign expression1 = expression2
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
catch [signal]
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.
ignore [signal]
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.
patch variable = expression patch expression1 = expression2
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
stop variable
stop [variable] at source-line [if condition]
stop [variable] in procedure [if condition]
stop [variable] if condition
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:
b Sets a breakpoint at a specified line.
bp Stops in a specified procedure.
trace [at] source-line
trace procedure
trace variable [at source-line] [if condition]
trace variable [in procedure] [if condition]
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
when [variable] [at line] {command_list}
when [variable] [in procedure] {command_list}
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
The following commands allow you to control program execution:
call procedure ([parameters])
print procedure ([parameters])
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.
[n] cont [signal]
cont [signal] to source-line
cont [signal] in procedure
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
goto source-line
Branches to the specified source line. Execution continues from that
point when you issue a cont command.
Predefined alias for goto command: g
next [integer]
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
rerun [arg1, arg2,...] [<file1][>file2]
rerun [arg1, arg2,...] [<file1][>&file2]
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
run [arg1,arg2,...] [<file1] [>file2]
run [arg1,arg2,...] [<file1] [>&file2]
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.
return [procedure]
Executes until a return to procedure is executed or until the current
procedure or function returns if you omit procedure.
step [integer]
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
Use the following commands to determine the state of your program:
dump [procedure] [.]
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.
down [expression]
Moves the current function down in the stack (based on the number of
activation levels that you specify). The default is one level.
up [expression]
Moves the current function up in the stack (based on the number of
activation levels that you specify). The default is one level.
print expression1,expression2,...
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
printf format, arg1,arg2,...
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:
pd The specified expression or variable in decimal.
po The specified expression or variable in octal.
px The specified expression or variable in hexadecimal.
printregs
Displays all register values.
Predefined alias for printregs command: pr
where [n]
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 filesystem must
be mounted. The following commands are available to attach to, and detach
from, a running process:
attach xxx
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.
detach [xxx]
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.
switch xxx
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.
plist
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 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:
address/count mode
address?count mode
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:
b Displays a byte in octal.
c Displays a byte as a character.
d Displays a 16-bit value in decimal.
dd Displays a 32-bit value in decimal.
D Displays a 64-bit value in decimal.
f Displays a single precision real number.
g Displays a double precision real number.
i Displays machine instructions.
n Displays data in typed format.
o Displays a 16-bit value in octal.
oo Displays a 32-bit value in octal.
O Displays a 64-bit value in octal.
s Displays a string of characters that ends in a null.
x Displays a 16-bit value in hexadecimal.
xx Displays a 32-bit value in hexadecimal.
X 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.
address/countM value mask
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.
[n] conti [signal]
conti [signal] to address
conti [signal] in procedure
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.
nexti [integer]
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
stepi [integer]
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
stopi variable
stopi [variable] [at address] [if condition]
stopi [variable] [in procedure] [if condition]
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.
tracei variable [at address] [if expression]
tracei variable [in procedure] [at address] [if expression]
tracei address [if condition]
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.
wheni [variable] [at address] {command_list}
wheni [variable] [in procedure] {command_list}
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
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:
$addrfmt
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.
$asynch_interface
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.
$casesense
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.
$datacache
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.
$dispix
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.
$hexchars
When set to a nonzero value, causes the debugger to display characters
in hexadecimal format.
$hexin
When set to a nonzero value, causes the debugger to interpret input
constants as hexadecimal. When set, this variable overrides the $octin
variable.
$hexints
When set to a nonzero value, changes the default output constants to
hexadecimal. When set, this variable overrides the $octints variable.
$hexstrings
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.
$historyevent
Stores the current history line.
$lines
Determines how many lines the debugger stores in its history list. The
default is 20 lines.
$listwindow
Specifies how many lines the list command displays. The default is 10
lines.
$main
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.
$maxstrlen
Specifies how many characters of a string dbx displays for pointers to
strings. The default is 128 characters.
$module_path
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.
$module_verbose
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.
$octin
When set to a nonzero value, changes the default input constants to
octal. When set, the $hexin variable overrides this variable.
$octints
When set to a nonzero value, causes dbx to display integers in octal
format. When set, the $hexints variable overrides this variable.
$page
Specifies whether to page long information. A nonzero value turns on
paging; a zero turns it off. The default is one.
$pagewindow
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.
$printcplusparams
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.
$printwhilestep
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.
$pimode
Displays input when used with the playback input command. The default
is zero.
$printdata
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.
$printwide
When set to a nonzero value, causes the debugger to display the
contents of variables in a horizontal format. The default is zero.
$prompt
Sets the prompt for dbx.
$readtextfile
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.
$regstyle
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.
$repeatmode
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.
$rimode
When set to a nonzero value, causes the debugger to record input while
recording output. The default is zero.
$sigvec
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.
$stop_all_forks
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.
$stop_on_exec
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.
$stop_on_fork
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.
$tagfile
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).
$traploops
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.
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 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
During its startup, dbx reads and executes the commands in an
initialization file (if present). By default, dbx searches for the
initialization file .dbxinit in the current directory. If no .dbxinit 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
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
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 .c
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 recognized:
^A Move the cursor to the beginning of the command line.
^B Move the cursor back one character.
^C Clear the line.
^D Delete the character at the cursor.
^E Move the cursor to the end of the line.
^F Move the cursor ahead one character.
^H Delete the character immediately preceding the cursor.
^J Execute the line.
^K<char>
(When enabled by LINEEDIT) Delete characters until the cursor rests on
the next occurrence of char.
^K (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.
^L Redisplay the current line.
^M Execute the line.
^N Move to the next line in the history list.
^P Move to the previous line in the history list.
^R<char>
Search back in the current line for the specified character.
^T Interchange the two characters immediately preceding the cursor.
^U Repeat the next character four times.
^W Delete the entire line.
^Y Insert immediately before the cursor any text cut with ^K.
^Z Try to complete a file or symbol name.
Escape
Try to complete a file or symbol name.
Down Arrow
Move to the next line in the history list.
Up Arrow
Move to the previous line in the history list.
Left Arrow
Move the cursor back one character.
Right Arrow
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
specification.
ENVIRONMENT VARIABLES
DBX_MODULE_PATH
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.
DBX_MODULE_VERBOSE
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.
FILES
a.out
Object file
core
Core dump file
.dbxinit
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
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|