Content-type: text/html
Man page of dbx
dbx
Section: User Commands (1)
Index
Return to Main Contents
NAME
dbx - source level debugger
SYNOPSIS
dbx [-I dir] [-c file] [-k] [-i] [-r] [-pixie] [-pid xxx] [object [core]]
OPTIONS
The
dbx
debugger accepts the following options:
Selects a command file other than
.dbxinit.
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.
(Refer to
Kernel Debugging
for information on kernel debugging.)
Reads in output from the
pixie
code profiler
utility. For this option to work, you must have executable
pixie
output and the nonpixie executable file in the same directory.
The
pixie
output must be named
filename.pixie, where
filename
is the name of
the executable file.
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
Kernel Debugging
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.
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:
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
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
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
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 shared libraries. The
lib_path
argument specifies the absolute or relative pathname of the shared library.
dbx
reads in the shared library's symbol table.
-
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.
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
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
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
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
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
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,
A-acute-accent and a-acute-accent are always treated as different characters.
Caches information from the data space so that
dbx
must access the data space only once. If this variable is set to
zero, the debugger does not cache data space. If your program 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.
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.
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.
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.
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.
Arguments
On the command line, the
object
argument
names 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
translated by the compiler to create the object file. This information allows
you to look at all of the source code that went into creating an object file
during your debugging session. (The extended symbol table also contains other
information.)
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 the
object
argument,
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.
The
core
argument names a core dump file.
You can examine the core dump file to determine the state of the program
when it failed.
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:
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.
RESTRICTIONS
The
printf
debugger command does not support the
%s
conversion specification.
FILES
Object file
Core dump file
Initialization file
SEE ALSO
Commands:
as(1),
cc(1),
ctags(1),
pixie(5),
vi(1)
Routines:
printf(3),
signal(4),
kdbx(8)
Kernel Debugging
Programmer's Guide
Index
- NAME
-
- SYNOPSIS
-
- OPTIONS
-
- dbx Commands
-
- Controlling the Monitor
-
- Controlling dbx
-
- Examining Source Code
-
- Preparing for Program Execution
-
- Initiating Program Execution
-
- Examining Program State
-
- Attaching to a Running Process
-
- Debugging at the Machine Code Level
-
- Predefined dbx Variables
-
- DESCRIPTION
-
- Arguments
-
- Initialization File
-
- Debugger Expressions
-
- Debugger Name Resolution
-
- Command Line Editing
-
- RESTRICTIONS
-
- FILES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 02:42:57 GMT, October 02, 2010