DB(1) DB(1)
NAME
db, dbfmt - debugger
SYNOPSIS
db [ option ... ] [ textfile [ memfile ] ]
db [ -k ] pid
dbfmt
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.
Textfile is normally an executable program file or
/proc/pid/text. Memfile is the memory image of a process,
usually obtained from /proc/pid/mem. If there is exactly
one argument, and it is numeric, then it is used as a pid to
find the text and mem files in /proc/pid.
Requests to db are read from the standard input and
responses are to the standard output. The options are
-k pid
Use the kernel for the textfile and memfile, with the
kernel stack of process pid.
-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 (one of
386, 68020, 960, hobbit, mips, mipsco, sparc, or
sunsparc) instead of using the magic number in the text
file to select the CPU type.
In general requests to db have the following form. Multiple
requests on one line must be separated by `;'.
[address] [, count] [command]
If address is present then the current position, called
`dot', is set to address. Initially dot is set to 0. In
general commands are repeated count times. Dot advances
between repetitions. The default count is 1. Address and
DB(1) DB(1)
count are expressions.
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 Unicode value of a character. `\' may be used to
escape a `''.
<name The value of name, which is either a variable name or
a register name. db maintains a number of variables
named by single letters or digits. 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
recently activated C stack frame corresponding to
routine; if routine is omitted, the active procedure
is assumed.
file:integer
The address of the instruction corresponding to the C
source statement at the indicated line number of the
DB(1) DB(1)
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 If exp is used as an address, it is in register
space; 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 consist of a verb followed by a modifier or
list of modifiers. The following verbs are available. (The
commands `?' and `/' may be followed by `*'; see
`Addresses' for further details.)
?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.
DB(1) DB(1)
=f The value of address itself is printed in the styles
indicated by 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 in signed octal.
Q Print four-byte in signed octal.
d Print two-byte in decimal.
D Print four-byte in decimal.
x Print two-byte in hexadecimal.
X Print four-byte in hexadecimal.
u Print two-byte in unsigned decimal.
U Print four-byte 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 the addressed two-byte integer as a rune.
R Print the addressed two-byte integers as runes
until a zero rune is reached. Advance dot by the
length of the string, including the zero termina-
tor.
Y Print a four-byte integer in date format (see
ctime(2)).
i Print as machine instructions. This style of
printing causes variables 0, (1, ...) to be set
to the offset parts of the first (second, ...)
operand 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
DB(1) DB(1)
machine dependent hexadecimal form.
a Print the value of dot in symbolic form. 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.
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 map entry named s are
recorded. Valid map entry names are text, data,
ublock, or regs. If less than three address expressions
are given then the remaining map parameters are left
unchanged. The address type (instruction or data) is
unchanged in any case. If the list is terminated by
`?' or `/' then the file (textfile or memfile respec-
tively) is used for subsequent requests. For example,
`/m?' causes `/' to refer to textfile.
>name
Dot is assigned to the variable or register named.
! Tem rest of the line is passed to the rc(1) for execu-
tion.
DB(1) DB(1)
$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. The value of the
count is placed in variable 9 before the first
command in f is executed. A common use for this
command is to print the fields of a structure.
The dbfmt program takes a structure description on
standard input and produces a file on standard
output suitable for use in a addr$<f command. The
-sname option of 2c(1) produces a structure
description for structure or union name.
<<f Similar to < except it can be used in a file of
commands without causing the file to be closed.
Variable 9 is saved during the execution of this
command, and restored when it completes. 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, as well as the registers.
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 registers such
as the kernel stack pointer 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.
c C stack backtrace. If address is given then it is
taken as the address of the current frame; other-
wise, the current C frame pointer is used. If C
is used then the names and (long) values of all
parameters, automatic and static variables are
printed for each active function. If count is
given then only the first count frames are
printed.
a Set the maximum number of arguments printed by $c
or $C to address. The default is 20.
e The names and values of all external variables are
printed.
w Set the page width for output to address (default
DB(1) DB(1)
80).
s Set the limit for symbol matches, used in printing
addresses, to address (default 255).
q Exit from db.
v Print all non zero variables.
m Print the address maps.
k Simulate kernel memory management.
p Use kernel data and stack maps for the specified
process.
$k and $p are used for system debugging (see the
Examples section).
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
DB(1) DB(1)
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.
Variables
db provides a number of variables. Named variables are set
initially by db but are not used subsequently. Numbered
variables are reserved for communication as follows.
0, 1, ...
The offset parts of the first, second, ... operands of
the last instruction printed. Meaningless if the
operand was a register.
9 The count on the last $< or $<< command.
On entry the following are set from the system header in the
memfile. If memfile does not appear to be a memory image
then these values are set from textfile.
b The base address of the data segment.
d The data segment size.
e The entry point.
m The `magic' number (see a.out(6)).
s The stack segment size.
t The text segment size.
Addresses
The address in a file associated with a written address is
determined by a mapping associated with that file. Each
mapping is represented by one or more quadruples (t, b, e,
f), mapping an address of type t (text, data, user block, or
registers) in the range b through e to the part of the file
beginning at address f. An address a of type t is mapped to
a file address by finding a quadruple of type t, for which
b≦a<e; the file address is address+f-b. As a special case,
if a text space address is not found, a second search is
made for the same address in data space.
Typically, the text segment of a program is mapped as text
space, the data and bss segments as data space. If textfile
is an executable file or if memfile is a memory image, maps
are set accordingly. Otherwise, a single `data space' map
is set up, with b and f set to zero, and e set to a huge
number; thus the entire file can be examined without address
translation.
The ? and / commands attempt to examine text and data space
respectively. ?* tries for data space (in textfile); /*
DB(1) DB(1)
accesses text space (in memfile).
Registers in process and core images are a special case;
they live in a special `register' address space starting at
%0; the layout of this space is machine-dependent. %
addresses are mapped to the registers for the `current
frame,' set by local variable references, and reset to the
outermost frame (the `real' registers) whenever a process
runs or a stack trace is requested.
Simulated memory management translations (the $k and $p com-
mands) are done before the mapping described above.
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
Similar, but using a kernel test:
db test /proc/27/mem
27$p
$C
To print the fields of the Dir structure at address #20000,
assuming main.c includes a declaration of that structure:
!2c -sDir -o /dev/null main.c | dbfmt > Dir.dbfmt
#20000$<Dir.dbfmt
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.
FILES
/proc/*/text
/proc/*/mem
DB(1) DB(1)
/proc/*/ctl
/proc/*/note
SEE ALSO
nm(1), proc(3)
J. F. Maranzano and S. R. Bourne, `A Tutorial Introduction
to ADB' in Bell Laboratories, UNIX Programmer's Manual, Vol-
ume 2, Holt, Rinehart and Winston (1984)
DIAGNOSTICS
Exit status is null, unless the last command failed or
returned non-null status.
BUGS
The alternate sparc disassembly format, sunsparc, reverses
the order of the first two registers relative to the SUN
assembler.
Examining a local variable with routine.name returns the
contents of the memory allocated for the variable. This
might return the wrong value: optimization may move the
variable into a register, especially in the current stack
frame. Compiling with the -N flag may help.
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.
In some cases, the stack frame is not completely set when a
breakpoint or single step stops a process in the first cou-
ple of instructions of a function. As a result, the $c and
$C produce inaccurate stack traces. Stepping a couple of
instructions into the function sets the stack frame and pro-
duces accurate traces.