DB(1) DB(1)
NAME
db - debugger
SYNOPSIS
db [ option ... ] [ textfile ] [ pid ]
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 Plan 9 programs.
A textfile is a file containing the text and initialized
data of an executable program. A memfile is the memory
image of an executing process. It is usually accessed via
the process id (pid) of the process in /proc/pid/mem. A
memfile contains the text, data, and saved registers and
process state. 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. When a
textfile is given, the textfile map is associated with it.
If only a pid is given, the textfile map is associated with
/proc/pid/text. When a pid is given, the memfile map is
associated with /proc/pid/mem; otherwise it is undefined and
accesses to the memfile are not permitted.
Commands to db are read from the standard input and
responses are to the standard output. The options are
-k Use the kernel stack of process pid to debug the exe-
cuting kernel process. If textfile is not specified,
file /$cputype/9type is used, where type is the second
word in $terminal.
-w Create textfile and memfile if they don't exist; open
them for writing as well as reading.
-Ipath
Directory in which to look for relative path names in
$< and $<< commands.
-mmachine
Assume instructions are for the given CPU type (any
standard architecture name, such as amd64 or 386, plus
mipsco and sunsparc, which cause disassembly to the
manufacturer's syntax) instead of using the magic num-
ber to select the CPU type.
Page 1 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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.
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
Page 2 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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.
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
Page 3 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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 current
increment.
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 termina-
tor.
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
Page 4 Plan 9 (printed 12/22/24)
DB(1) DB(1)
by the size of the instruction.
I As i above, but print the machine instructions in
an alternate form if possible: sunsparc and mipsco
reproduce the manufacturers' syntax.
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.
[?/]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
Page 5 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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
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.
Page 6 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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
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
Page 7 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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, b, e, f),
defining a segment named t (usually, text, data, or ublock)
mapping addresses in the range b through e to the part of
the file beginning at offset f. The memory model of a Plan 9
process assumes that segments are disjoint. There can be
more than one segment of a given type (e.g., a process may
have more than one text segment) but segments may not over-
lap. An address a is translated to a file address by find-
ing a segment 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 and data. Since a program
file does not contain bss, stack or ublock data, these data
are not mapped by the data segment. The text segment is
mapped similarly in a normal (i.e., non-kernel) memfile.
However, the segment called data maps memory from the begin-
ning of the program's data space to the base of the ublock.
This region contains the program's static data, the bss, the
heap and the stack. A segment called ublock maps the page
containing its registers and process state.
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 the entire file to be examined without address trans-
lation.
Registers are saved at a machine-dependent offset in the
ublock. It is usually not necessary to know this offset;
the $r, $R, $f, and $F commands calculate it and display the
register contents.
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 examine the Plan 9 kernel stack for process 27:
% db -k 27
$C
Page 8 Plan 9 (printed 12/22/24)
DB(1) DB(1)
Similar, but using a kernel named test:
% db -k test 27
$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
dot; when argc is one the breakpoint will fire. Beware that
local variables may be stored in registers; see the BUGS
section.
Debug process 127 on remote machine kremvax:
% import kremvax /proc
% db 127
$C
FILES
/proc/*/text
/proc/*/mem
/proc/*/ctl
/proc/*/note
SEE ALSO
acid(1), nm(1), proc(3)
SOURCE
/sys/src/cmd/db
DIAGNOSTICS
Exit status is null, unless the last command failed or
returned non-null status.
BUGS
Examining a local variable with routine.name returns the
contents of the memory allocated for the variable, but with
optimization (suppressed by the -N compiler flag) 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.
Because of alignment incompatibilities, Motorola 68000
series machines can not be debugged remotely from a proces-
sor of a different type.
Page 9 Plan 9 (printed 12/22/24)
DB(1) DB(1)
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 10 Plan 9 (printed 12/22/24)