DBX(1) DBX(1)
NAME
dbx - a source-level debugger
SYNOPSIS
dbx dbx-options [object-file] [core-file]
dbx dbx-options -p pid
dbx dbx-options -P name
dbx dbx-options -r [object-file] [arguments . . .]
dbx-options: [-I directory ] [ -c file ] [ -e evalsizelimit ] [ -i ] [ -k ] [ -N ] [ -x ]
DESCRIPTION
dbx is a source-level debugger that allows the user to trace the
execution of a given object-file as well as a pool of arbitrary
processes. dbx works with cc(1), f77(1), pc(1) as(1), CC(1), and MIPS
machine code on 32- and 64-bit ELF object-files.
The object-file used with the debugger is produced by specifying an
appropriate option (usually -g) to the compiler (and linking the
resulting object(s), creating an executable object-file). The resulting
object-file contains debugging information, including the names of all
source files that the compiler translated to create the object-file.
These source files are accessible from the debugger.
If a core-file is specified, or if the file core exists in the current
directory, dbx can be used to look at the state of the program when it
faulted.
The file /usr/lib/dbx.help is a text file explaining features of dbx.
Read it for additional information on assembler-level debugging,
expressions in dbx, and examples.
This man page shows only some of the dbx commands: See the help file and
the appropriate reference manual for details and for information on
additional features.
Running dbx
If a .dbxinit file resides in the current directory or in the user's home
directory, the commands in it are executed when dbx is invoked.
The environment variable DBXINIT may be used to hold dbx command line
options. If present, the contents of DBXINIT are inserted before the
command line options.
When invoked, dbx recognizes these command line options:
Page 1
DBX(1) DBX(1)
-I directory
Tells dbx to look in the specified directory for source files.
Multiple directories can be specified by using multiple -I
options. dbx searches for source files in the current directory
and in the object-file's directory whether or not -I is used.
-c file Selects a command file other than .dbxinit.
-i Uses interactive mode. This option does not treat #s as comments
in a file. It prompts for source even when it reads from a file.
With this option, dbx also has extra formatting as if for a
terminal.
-p pid Debug the running process with the specified process id.
-P name Debug the running process with the specified name (name as shown
in ps(1)).
-R Turn on $debugrld at startup, so one can set breakpoints in
rld(1).
-r Runs the object-file immediately. Arguments may be placed on the
dbx command line. The .dbxinit file (if any) is read in and the
commands in it executed after the object-file is run.
-e nnnn Choose a larger size for the evaluation space. Printing a very
large structure one can exhaust the default 20,000 bytes of
evaluation space. With this option you can make the space as
large as desired. For example, to make the stack 100,000 bytes:
-e 100000
-k Debug the operating system. When debugging a running system,
/dev/kmem should be specified as the core-file.
-N Sets the dbx variable $nonstop to 1 on startup. When $nonstop is
1, any process attached to is left running rather than stopped.
So, for example dbx -N -p 12345 will start up dbx and attach to
process 12345 but will leave the process running.
The Monitor
The following commands control the dbx monitor. Multiple commands can be
specified on the same command line by separating them with a semicolon
(;).
![string] [integer] [-integer]
Specifies a command from the history list.
Page 2
DBX(1) DBX(1)
help Prints a short list of dbx help topics and suggests some uses of
the help command.
history Prints the items from the history list. The history list is
$lines lines long (20 by default).
hed int Brings the history list line into an editor in a temporary file.
Whatever commands are still in the editor temporary file when you
quit the editor are executed as ordinary dbx commands.
quit Exits dbx.
Controlling dbx
alias Lists all existing aliases.
alias name
Lists the alias string for name. The alias value is inserted in
quotes with escape characters added to show how the alias
"string" was typed. See the help file (/usr/lib/dbx.help)
EXPRESSIONS section for additional information on strings and
character escapes.
alias name name2
Defines a new alias.
unalias alias_name
Removes the alias alias_name from the alias table.
delete expression1, ...expressionN
Deletes the specified item(s) from the status list.
givenfile
Reports the name of the current givenfile (usually called an
object-file on this page).
givenfile object-file
The argument object-file is taken as the name of the file to
debug, just as if object-file had been given on the dbx command
line. Existing processes are killed and dbx looks up the symbol
table and core-file for this object-file.
corefile
Reports the current core-file name and whether data referencing
commands actually reference the core-file or not. They will not
reference the core-file if it is missing or damaged or if the
process is running.
corefile core-file
The argument core-file is taken as the name of a core-file to
debug, just as if core-file had been given on the dbx command
line. References to the process will use this core-file.
Page 3
DBX(1) DBX(1)
playback input [file]
Reads the commands in the file and executes them.
sh Calls a shell from dbx. If the environment variable SHELL is
set, its value is taken as the name of the shell to use. If
SHELL is not set, csh(1) is used.
sh shell command
Executes a shell command.
status Lists currently set stop, trace, and when commands.
set Lists existing debugger variables and their values.
set variable = expression
Assigns a new value to an existing variable or a new variable.
If the expression result is not of type ``int'' the set command
will leave the result symbolic. To get the expression fully
evaluated, cast the result to ``int'' as in set variable =
(int)expression.
unset variable
Removes the specified debugger variable and its value from the
debugger variable table.
Examining Source
/regular expression
Searches ahead in the source code for the regular expression.
?regular expression
Searches back in the source code for the regular expression.
directory
Lists source directories. Abbreviate as dir.
directory directory1 ... directoryN
Adds the new directory(s) to the previous list. Can be
abbreviated dir. See also use.
edit Calls an editor on the current file from dbx.
edit file
Calls an editor from dbx.
edit func
Calls an editor on the file in which function func is defined.
file Prints the current file name.
Page 4
DBX(1) DBX(1)
file file
Changes the current file to the specified file.
list expression
Lists $listwindow lines starting at line expression.
list expression,expression2
Lists lines expression thru expression2.
use Lists source directories.
use directory1 ... directoryN
Substitutes the new directories for the previous list. See also
directory.
whatis variable
Prints a type declaration. variable may be a variable or a type.
which variable
Finds the variable name currently being used.
whereis variable
Prints all qualifications (scopes) of the specified variable
name.
Controlling Programs
assign expression1 = expression2
Assigns the specified expression to a specified program variable.
If the incompatible types message appears when you try to assign
a value to a pointer, use casts to make the assignment work.
Example: assign x = 12
cont Resume execution and wait for a break or other event.
cont signal
Send signal signal to the process, resume execution, and wait for
a break or other event. For further information about signals
see the Execution Tracing section catch and ignore commands and
discussion.
kill pid ...
Kill the active process(es) whose process id(s) are specified.
next [integer]
Step over the specified number of lines. The default is one.
This command does not step into procedures. Breakpoints in
procedures stepped over are honored. See $nextbreak and
$stepintoall for information on modifying the behavior of next.
printenv [env-var-name]
prints the environment variable named in the environment internal
to dbx. With no environment variable named, prints the names and
Page 5
DBX(1) DBX(1)
values of the all the environment variables in the environment
internal to dbx. See setenv below.
rerun [arg1 ... argN]
Rerun the program, using the same arguments that were specified
to the run command. If new arguments are specified, rerun uses
those arguments. Any redirection or other features supported by
your shell may be used.
resume Resume execution of the program, and return immediately to the
dbx command interpreter.
resume signal
Resume execution of the process, sending it signal signal, and
return immediately to the dbx command interpreter.
run [arg1 ... argN] [< file1] [> file2]
Runs the program with the specified arguments.
return Continue execution until control returns to the next procedure up
the activation stack.
setenv env-var-name value
Sets the environment internal to dbx to have this environment
variable. Just like the csh(1) command, but does not affect the
dbx startup since dbx has already started up before one enters
this command. Primarily useful for setting environment variables
used by the application or by rld(1) before run or rerun of the
application being debugged.
step [integer]
Step the specified number of lines. The default is one line.
Breakpoints in procedures stepped over are honored.
syscall Prints the list of system calls in 4 sections. System calls may
be caught (breakpointed) at the time the call is made or when the
system call is about to return. This command prints the system
calls in the four sections: 1) caught at call 2) ignored at call
3) caught at return 4) ignored at return. The system calls are
all listed in /usr/include/sys.s
syscall catch call syscall ...
The named system calls breakpoint at the entry of the system
call.
syscall ignore call syscall ...
The named system calls not breakpoint at the entry of the system
call.
syscall catch return syscall ...
The named system calls breakpoint at the return from the system
call.
Page 6
DBX(1) DBX(1)
syscall ignore return syscall ...
The named system calls not breakpoint at the return from the
system call.
unsetenv env-var-name
Unsets (removes) the environment variable in the environment
internal to dbx. See setenv above.
Execution tracing
catch Lists all signals that dbx catches.
catch signal
Adds a new signal to the catch list. A signal is specified as a
name or as a number. For example, the interrupt signal is named
INT, SIGINT, or 2.
ignore Lists all signals that dbx does not catch.
ignore signal
Adds a signal signal to the ignore list. A signal is specified
as a name or as a number. For example, the interrupt signal is
named INT, SIGINT, or 2. A process sees this signal when
directed at it by itself or another process. The process
responds to the signal just as if dbx were not present.
stop variable
Sets up to stop execution when variable changes.
stop in procedure
Sets up to stop execution when procedure is entered.
stop at line
Sets a breakpoint at the specified source line.
trace prints information about the process when the trace conditions are
satisfied, but program execution continues.
trace variable
When variable changes, print its old and new values. (Execution
will be very slow).
trace procedure
When procedure is entered, print its arguments and its caller's
name.
when is similar to stop except that rather than stopping when the
conditions are met, the command-list (dbx commands separated by semi-
colons) is executed. If one of the commands in the list is stop (with no
Page 7
DBX(1) DBX(1)
operands) then the process will stop when the command-list is executed.
when at line { command-list }
Execute the specified command-list when the conditions are met.
when in procedure { command-list }
Execute the specified command-list when the conditions are met.
Examining Program State
dump Prints variable information about the current procedure.
dump . Prints variable information for all procedures currently active.
down Moves down one activation level in the stack.
down n Moves down the specified number of activation levels on the
stack.
up Moves up one activation level on the stack.
up n Moves up the specified number of activation levels on the stack.
listobj Lists the a.out and all active DSOs and their text regions.
listregions
Lists all active memory regions which are part of the executing
program.
print expression1,...expressionN
Prints the value(s) of the specified expression(s). printd,
printo, printx similarly print the values, but in decimal, octal,
and hex (respectively)
printregs
Prints all register values.
where Does a stack trace, showing the current activation levels.
where n Does a stack trace, showing the first n activation levels.
Debugging at the Machine Level
stopi, wheni, and tracei have the same meanings and options as stop when,
and trace except that stopi, wheni, and tracei step in units of machine
instructions rather than source lines. A few of the possibilities
follow:
conti to address
Set a breakpoint at address and continue.
Page 8
DBX(1) DBX(1)
nexti [integer]
Steps over the specified number of machine instructions. The
default is one. This command does not step into procedures.
stepi [integer]
Steps the specified number of machine instructions. This command
steps into procedures even if no source, symbols, or line numbers
are present. The default is one instruction.
stopi at address
Set a breakpoint at address.
address / count format
Prints the contents of the specified address or disassembles the
code for the instruction at the specified address. Repeated for
a total of count addresses in increasing address. This might
also be termed the ``examine forward'' command. With ? instead
of / it examines in decreasing address.
A partial list of command formats:
______________________________________________
|format data size print |
| name in bits format |
|_____________________________________________|
| D 32 signed decimal |
| dd 64 signed decimal |
| X 32 hexadecimal |
| xx 64 hexadecimal |
| V 32 unsigned decimal |
| vv 64 unsigned decimal |
| c 8 character |
| s string of characters |
| ending in null byte |
| f 32 single precision |
| real number |
| g 64 double precision |
| real number |
| i 32 instruction disassembly |
|_____________________________________________|
Example:
$curpc-20/20i
prints 20 disassembled machine instructions starting at
the current pc-20.
Complicated address expressions require parentheses around the
address expression.
Page 9
DBX(1) DBX(1)
Example:
(0x400500 + (($a1>>3) &0xfff))/11
prints 11 64-bit words in hexadecimal starting at the
calculated address.
Multiple process debugging
If desired, a number of processes can be traced in a single dbx session.
Processes can be added or subtracted from the ``process pool''. A single
process is identified as the ``active process'' and relevant commands
will be applied to this process' execution and address space.
If a process performs an execv() or an execve() system call, it will stop
itself and allow dbx to read its new symbol information.
Many commands take a 'pid <pid> clause. Using the pid pid clause means
you can apply a command to any process in the process pool even though it
is not the active process.
Example: step pid 3345
active Prints the active process's process id.
active pid
Make the process the active process.
showproc
Print the status of all processes in the pool.
$lastchild is always set to the process id of the last child forked.
$pid0 is always set to the process id of the given process, (called
object-file in the Synopsis).
Pthreads Debugging Facilities
The pthreads debugging facility allows one to see some things per thread.
The set of things one can do per thread is, as yet, limited to just the
where command.
The intent is that one can do commands with the command modifiers thread
<thread-id> or thread all to see any (appropriate) command applied to a
particular thread or to all the threads. For example, to see the stack
trace for all pthreads, type where thread all .
With IRIX6.5 and later, one can control multiple processes, each with
multiple threads. The multiple processes can be in a Process Group
(discussed below) though the threads in each process are completely
separate from the threads in any other process in the group: each
process is independently pthreaded. In IRIX6.5 the showthread commands
and the "thread" command modifier apply to the active process.
Page 10
DBX(1) DBX(1)
With IRIX6.4 and earlier one can control only one set of threads (using
multiple processes). See the dbx help file for more information on
IRIX6.4 and earlier pthreads as it will not be discussed further here.
Commands unique to threads are:
showthread
Prints basic information about the current thread.
showthread <number>
Prints basic information about the thread with that number. A
typical example is showthread 0x80001 .
showthread thread <number>
Prints basic information about the thread with that number.
showthread all
Prints basic information about all the threads.
showthread thread all
Prints basic information about all the threads.
showthread full
Prints full thread information about the current thread.
showthread full thread <number>
Prints full thread information information about the thread with
that number.
showthread full all
Prints full thread information information about all threads.
Process Group Debugging Facilities
The process group facility allows a group of processes to be operated on
simultaneously by a single dbx command. This is far more convenient to
use when dealing with sproced processes than issuing individual resume,
suspend, or breakpoint setting commands.
Whenever a process sprocs, if the child is added to the process pool the
parent and child are added to the group list as well. The group list is
simply a list of processes.
addpgrp pid ...
Adds the process ids specified to the group list. Only processes
in the process pool can be added to the group list.
delpgrp pid ...
Deletes the process ids specified from the group list.
showpgrp
Shows the group process list and the group breakpoint list.
Page 11
DBX(1) DBX(1)
waitall Wait for any process currently running to breakpoint or stop for
any reason. It waits on all running processes in the process
list, not just those in the group list. It does not make the
process that stops first the active process. Most useful after a
resume pgrp command.
HINTS
The command help help shows how to get this entire help file into your
favorite editor so you can search for topics of interest. The help file
is far too large to use conveniently with more(1).
showthread full
Process Group Debugging Facilities
The process group facility allows a group of processes to be operated on
simultaneously by a single dbx command. This is far more convenient to
use when dealing with sproced processes than issuing individual resume,
suspend, or breakpoint setting commands.
Whenever a process sprocs, if the child is added to the process pool the
parent and child are added to the group list as well. The group list is
simply a list of processes.
addpgrp pid ...
Adds the process ids specified to the group list. Only processes
in the process pool can be added to the group list.
delpgrp pid ...
Deletes the process ids specified from the group list.
showpgrp
Shows the group process list and the group breakpoint list.
waitall Wait for any process currently running to breakpoint or stop for
any reason. It waits on all running processes in the process
list, not just those in the group list. It does not make the
process that stops first the active process. Most useful after a
resume pgrp command.
HINTS
The command help help shows how to get this entire help file into your
favorite editor so you can search for topics of interest. The help file
is far too large to use conveniently with more(1).
dbx can be used as a calculator, since constant calculations can be done
without specifying or running a program. A spelling error, like typing
oxf96 instead of 0xf96, will provoke the error message ``no active
process'' since dbx presumes the oxf96 is a variable name. Example
session:
Page 12
DBX(1) DBX(1)
$ dbx
(dbx) px ( 0xa5a893a + 0xf96) << 2
0x296a6340
(dbx)q
To get emacs-style line editing on the dbx command line, set the
environment variable before starting dbx. LINEEDIT. For example: setenv
LINEEDIT ""
CAVEATS
When debugging an MP program, disable SIGTERM by doing the following:
(dbx) ignore TERM
Although debugging is possible without this command, the MP program may
not terminate gracefully after execution is complete. Disabling SIGTERM
is not necessary for non-MP programs.
For Fortran arrays (arrays defined in Fortran source) the Fortran syntax
of print x(1,2) works. dbx also allows somewhat C-like syntax (using
"[]" not "()") for Fortran array references, meaning that if x is a two-
dimension Fortran array print x[1,2] will also work. The x(1,2) notation
does not yet work in the duel command: one must use x[1,2] with the duel
command.
FILES
/usr/bin/dbx
/usr/lib/dbxpcs
/usr/lib/dbx.help
SEE ALSO
dbxhang(1)
Compiling Debugging and Performance Tuning
/usr/lib/dbx.help
DIAGNOSTICS
warning: /proc not mounted
This should not occur in normal operation. The debug "file system"
which provides dbx with the ability to trace processes has been
unmounted. To re-mount this file system, perform the following
command as superuser (as described in mntproc(1M)):
/etc/mntproc
Page 13