DB(1) DB(1)
NAME
db, stack - debugger
SYNOPSIS
db [ option ... ] [ pid | corefile ] [ textfile ]
stack [ pid | corefile | name ] [ textfile ]
DESCRIPTION
Db is a general purpose debugging program. It may be used
to examine files and to provide a controlled environment for
the execution of programs.
A textfile is a file containing the text and initialized
data of an executable program. A pid or corefile specifies
the memory image of a process. A pid gives the id of an
executing process to be accessed via ptrace(2). A corefile
specifies the name of a core dump (see core(5) on your sys-
tem of choice) containing the memory image of a terminated
process. This manual refers to the memory image specified
by pid or corefile as a memfile.
A map associated with each textfile or memfile supports
accesses to instructions and data in the file; see
`Addresses'.
An argument consisting entirely of digits is assumed to be a
process id; otherwise, it is the name of a textfile or
corefile. When a textfile is given, the textfile map is
associated with it. If only a memfile is given, the
textfile map is derived from the corresponding textfile, if
it can be determined (this varies from system to system).
When a memfile is given, the memfile map is associated with
it; otherwise the map is undefined and accesses to it are
not permitted.
Stack takes the same arguments as db. It prints a stack
trace (see the $c command below) and then exits. If the
first argument is a process name, then stack prints the
stack trace of every running process with the given name
that is owned by the current user.
Commands to db are read from the standard input and
responses are to the standard output. The options are
-q Quiet mode: suppress informational prints at startup.
-w Open textfile and memfile for writing as well as read-
ing.
Page 1 Plan 9 (printed 12/22/24)
DB(1) DB(1)
-Ipath
Directory in which to look for relative path names in
$< and $<< commands.
-mmachine
Assume instructions are for the given CPU type (possi-
ble names include 386 and powerpc; adding the suffix
-co as in 386-co and powerpc-co selects disassembly in
the manufacturer's syntax, if available, rather than
the default Plan 9 syntax).
Most db commands have the following form:
[address] [, count] [command]
If address is present then the current position, called
`dot', is set to address. Initially dot is set to 0. Most
commands are repeated count times with dot advancing between
repetitions. The default count is 1. Address and count are
expressions. Multiple commands on one line must be sepa-
rated by `;'.
Expressions
Expressions are evaluated as long ints.
. The value of dot.
+ The value of dot incremented by the current incre-
ment.
^ The value of dot decremented by the current incre-
ment.
" The last address typed.
integer
A number, in decimal radix by default. The prefixes
`0' and `0o' and `0O' (zero oh) force interpretation
in octal radix; the prefixes `0t' and `0T' force
interpretation in decimal radix; the prefixes `0x',
`0X', and `#' force interpretation in hexadecimal
radix. Thus `020', `0o20', `0t16', and `#10' all
represent sixteen.
integer.fraction
A single-precision floating point number.
'c' The 16-bit value of a character. `\' may be used to
escape a `''.
<name The value of name, which is a register name. The
register names are those printed by the $r command.
Page 2 Plan 9 (printed 12/22/24)
DB(1) DB(1)
symbol A symbol is a sequence of upper or lower case let-
ters, underscores or digits, not starting with a
digit. `\' may be used to escape other characters.
The location of the symbol is calculated from the
symbol table in textfile.
routine.name
The address of the variable name in the specified C
routine. Both routine and name are symbols. If name
is omitted the value is the address of the most
recently activated stack frame corresponding to
routine; if routine is omitted, the active procedure
is assumed.
file:integer
The address of the instruction corresponding to the
source statement at the indicated line number of the
file. If the source line contains no executable
statement, the address of the instruction associated
with the nearest executable source line is returned.
Files begin at line 1. If multiple files of the same
name are loaded, an expression of this form resolves
to the first file encountered in the symbol table.
(exp) The value of the expression exp.
Monadic operators
*exp The contents of the location addressed by exp in
memfile.
@exp The contents of the location addressed by exp in
textfile.
-exp Integer negation.
~exp Bitwise complement.
%exp When used as an address, exp is an offset into
the segment named ublock; see `Addresses'.
Dyadic operators are left-associative and are less binding
than monadic operators.
e1+e2 Integer addition.
e1-e2 Integer subtraction.
e1*e2 Integer multiplication.
e1%e2 Integer division.
Page 3 Plan 9 (printed 12/22/24)
DB(1) DB(1)
e1&e2 Bitwise conjunction.
e1|e2 Bitwise disjunction.
e1#e2 E1 rounded up to the next multiple of e2.
Commands
Most commands have the following syntax:
?f Locations starting at address in textfile are printed
according to the format f.
/f Locations starting at address in memfile are printed
according to the format f.
=f The value of address itself is printed according to the
format f.
A format consists of one or more characters that specify a
style of printing. Each format character may be preceded by
a decimal integer that is a repeat count for the format
character. If no format is given then the last format is
used.
Most format letters fetch some data, print it, and advance
(a local copy of) dot by the number of bytes fetched. The
total number of bytes in a format becomes the
currentincrement.
o Print two-byte integer in octal.
O Print four-byte integer in octal.
q Print two-byte integer in signed octal.
Q Print four-byte integer in signed octal.
d Print two-byte integer in decimal.
D Print four-byte integer in decimal.
V Print eight-byte integer in decimal.
Z Print eight-byte integer in unsigned decimal.
x Print two-byte integer in hexadecimal.
X Print four-byte integer in hexadecimal.
Y Print eight-byte integer in hexadecimal.
u Print two-byte integer in unsigned decimal.
U Print four-byte integer in unsigned decimal.
f Print as a single-precision floating point number.
F Print double-precision floating point.
b Print the addressed byte in hexadecimal.
c Print the addressed byte as an ASCII character.
C Print the addressed byte as a character. Print-
able ASCII characters are represented normally;
others are printed in the form \xnn.
s Print the addressed characters, as a UTF string,
until a zero byte is reached. Advance dot by the
length of the string, including the zero
Page 4 Plan 9 (printed 12/22/24)
DB(1) DB(1)
terminator.
S Print a string using the escape convention (see C
above).
r Print as UTF the addressed two-byte integer
(rune).
R Print as UTF the addressed two-byte integers as
runes until a zero rune is reached. Advance dot
by the length of the string, including the zero
terminator.
i Print as machine instructions. Dot is incremented
by the size of the instruction.
I As i above, but print the machine instructions in
an alternate form if possible.
M Print the addressed machine instruction in a
machine-dependent hexadecimal form.
a Print the value of dot in symbolic form. Dot is
unaffected.
A Print the value of dot in hexadecimal. Dot is
unaffected.
z Print the function name, source file, and line
number corresponding to dot (textfile only). Dot
is unaffected.
p Print the addressed value in symbolic form. Dot
is advanced by the size of a machine address.
t When preceded by an integer, tabs to the next
appropriate tab stop. For example, 8t moves to
the next 8-space tab stop. Dot is unaffected.
n Print a newline. Dot is unaffected.
"..."
Print the enclosed string. Dot is unaffected.
^ Dot is decremented by the current increment.
Nothing is printed.
+ Dot is incremented by 1. Nothing is printed.
- Dot is decremented by 1. Nothing is printed.
Other commands include:
newline
Update dot by the current increment. Repeat the previ-
ous command with a count of 1.
[?/]l value mask
Words starting at dot are masked with mask and compared
with value until a match is found. If l is used, the
match is for a two-byte integer; L matches four bytes.
If no match is found then dot is unchanged; otherwise
dot is set to the matched location. If mask is omitted
then ~0 is used.
[?/]w value ...
Write the two-byte value into the addressed location.
If the command is W, write four bytes.
Page 5 Plan 9 (printed 12/22/24)
DB(1) DB(1)
[?/]m s b e f [?]
New values for (b, e, f) in the segment named s are
recorded. Valid segment names are text, data, or
ublock. If less than three address expressions are
given, the remaining parameters are left unchanged. If
the list is terminated by `?' or `/' then the file
(textfile or memfile respectively) is used for subse-
quent requests. For example, `/m?' causes `/' to
refer to textfile.
>name
Dot is assigned to the variable or register named.
! The rest of the line is passed to rc(1) for execution.
$modifier
Miscellaneous commands. The available modifiers are:
<f Read commands from the file f. If this command is
executed in a file, further commands in the file
are not seen. If f is omitted, the current input
stream is terminated. If a count is given, and is
zero, the command is ignored.
<<f Similar to < except it can be used in a file of
commands without causing the file to be closed.
There is a (small) limit to the number of << files
that can be open at once.
>f Append output to the file f, which is created if
it does not exist. If f is omitted, output is
returned to the terminal.
? Print process id, the condition which caused stop-
ping or termination, the registers and the
instruction addressed by pc. This is the default
if modifier is omitted.
r Print the general registers and the instruction
addressed by pc. Dot is set to pc.
R Like $r, but include miscellaneous processor con-
trol registers and floating point registers.
f Print floating-point register values as single-
precision floating point numbers.
F Print floating-point register values as double-
precision floating point numbers.
b Print all breakpoints and their associated counts
and commands. `B' produces the same results.
c Stack backtrace. If address is given, it speci-
fies the address of a pair of 32-bit values con-
taining the sp and pc of an active process. This
allows selecting among various contexts of a
multi-threaded process. If C is used, the names
and (long) values of all parameters, automatic and
static variables are printed for each active func-
tion. If count is given, only the first count
Page 6 Plan 9 (printed 12/22/24)
DB(1) DB(1)
frames are printed.
a Attach to the running process whose pid is con-
tained in address.
e The names and values of all external variables are
printed.
w Set the page width for output to address (default
80).
q Exit from db.
m Print the address maps.
k Simulate kernel memory management.
Mmachine
Set the machine type used for disassembling
instructions.
:modifier
Manage a subprocess. Available modifiers are:
h Halt an asynchronously running process to allow
breakpointing. Unnecessary for processes created
under db, e.g. by :r.
bc Set breakpoint at address. The breakpoint is exe-
cuted count-1 times before causing a stop. Also,
if a command c is given it is executed at each
breakpoint and if it sets dot to zero the break-
point causes a stop.
d Delete breakpoint at address.
r Run textfile as a subprocess. If address is given
the program is entered at that point; otherwise
the standard entry point is used. Count specifies
how many breakpoints are to be ignored before
stopping. Arguments to the subprocess may be sup-
plied on the same line as the command. An argu-
ment starting with < or > causes the standard
input or output to be established for the command.
cs The subprocess is continued. If s is omitted or
nonzero, the subprocess is sent the note that
caused it to stop. If 0 is specified, no note is
sent. (If the stop was due to a breakpoint or
single-step, the corresponding note is elided
before continuing.) Breakpoint skipping is the
same as for r.
ss As for c except that the subprocess is single
stepped for count machine instructions. If a note
is pending, it is received before the first
instruction is executed. If there is no current
subprocess then textfile is run as a subprocess as
for r. In this case no note can be sent; the
remainder of the line is treated as arguments to
the subprocess.
Ss Identical to s except the subprocess is single
stepped for count lines of C source. In optimized
code, the correspondence between C source and the
Page 7 Plan 9 (printed 12/22/24)
DB(1) DB(1)
machine instructions is approximate at best.
x The current subprocess, if any, is released by db
and allowed to continue executing normally.
k The current subprocess, if any, is terminated.
nc Display the pending notes for the process. If c
is specified, first delete c'th pending note.
Addresses
The location in a file or memory image associated with an
address is calculated from a map associated with the file.
Each map contains one or more quadruples (t, f, b, e, o),
defining a segment named t (usually, text, data, or core) in
file f mapping addresses in the range b through e to the
part of the file beginning at offset o. If segments overlap,
later segments obscure earlier ones. An address a is trans-
lated to a file address by finding the last segment in the
list for which b≤a<e; the location in the file is then
address+f-b.
Usually, the text and initialized data of a program are
mapped by segments called text, data, and bss. Since a pro-
gram file does not contain stack data, this data is not
mapped. The text segment is mapped similarly in a normal
(i.e., non-kernel) memfile. However, one or more segments
called data provide access to process memory. This region
contains the program's static data, the bss, the heap and
the stack.
Sometimes it is useful to define a map with a single segment
mapping the region from 0 to 0xFFFFFFFF; a map of this type
allows an entire file to be examined without address trans-
lation.
The $m command dumps the currently active maps. The ?m and
/m commands modify the segment parameters in the textfile
and memfile maps, respectively.
EXAMPLES
To set a breakpoint at the beginning of write() in extant
process 27:
% db 27
:h
write:b
:c
To set a breakpoint at the entry of function parse when the
local variable argc in main is equal to 1:
parse:b *main.argc-1=X
This prints the value of argc-1 which as a side effect sets
Page 8 Plan 9 (printed 12/22/24)
DB(1) DB(1)
dot; when argc is one the breakpoint will fire. Beware that
local variables may be stored in registers; see the BUGS
section.
SEE ALSO
acid(1), core(1)
SOURCE
/usr/local/plan9/src/cmd/db
DIAGNOSTICS
Exit status is 0, unless the last command failed or returned
non-zero status.
BUGS
Examining a local variable with routine.name returns the
contents of the memory allocated for the variable, but with
optimization, variables often reside in registers. Also, on
some architectures, the first argument is always passed in a
register.
Variables and parameters that have been optimized away do
not appear in the symbol table, returning the error bad
local variable when accessed by db.
Breakpoints should not be set on instructions scheduled in
delay slots. When a program stops on such a breakpoint, it
is usually impossible to continue its execution.
Page 9 Plan 9 (printed 12/22/24)