term% cat index.txt DB(1) General Commands Manual 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 ex‐
ecutable 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 unde‐
fined 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 executing ker‐
nel 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 ar‐
chitecture name, such as amd64 or 386, plus mipsco and sunsparc,
which cause disassembly to the manufacturer's syntax) instead of
using the magic number to select the CPU type.
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 separated by
Expressions
Expressions are evaluated as long ints.
. The value of dot.
+ The value of dot incremented by the current increment.
^ The value of dot decremented by the current increment.
" The last address typed.
integer
A number, in decimal radix by default. The prefixes and and
(zero oh) force interpretation in octal radix; the prefixes and
force interpretation in decimal radix; the prefixes and force
interpretation in hexadecimal radix. Thus and 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 letters, under‐
scores or digits, not starting with a digit. may be used to es‐
cape 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 corre‐
sponding 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 seg‐
ment 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 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. Printable 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 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 un‐
til 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 al‐
ternate form if possible: sunsparc and mipsco reproduce
the manufacturers' syntax.
M Print the addressed machine instruction in a machine-de‐
pendent hexadecimal form.
a Print the value of dot in symbolic form. Dot is unaf‐
fected.
A Print the value of dot in hexadecimal. Dot is unaf‐
fected.
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 ad‐
vanced 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 previous com‐
mand 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 loca‐
tion. 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 subsequent
requests. For example, 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 exe‐
cuted in a file, further commands in the file are not
seen. If f is omitted, the current input stream is ter‐
minated. 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 stopping 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 control reg‐
isters 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 specifies the
address of a pair of 32-bit values containing 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, au‐
tomatic and static variables are printed for each active
function. If count is given, only the first count frames
are printed.
a Attach to the running process whose pid is contained 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 break‐
pointing. Unnecessary for processes created under db,
e.g. by :r.
bc Set breakpoint at address. The breakpoint is executed
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 breakpoint 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 break‐
points are to be ignored before stopping. Arguments to
the subprocess may be supplied on the same line as the
command. An argument starting with < or > causes the
standard input or output to be established for the com‐
mand.
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 cor‐
respondence between C source and the machine instructions
is approximate at best.
x The current subprocess, if any, is released by db and al‐
lowed to continue executing normally.
k The current subprocess, if any, is terminated.
nc Display the pending notes for the process. If c is spec‐
ified, 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, 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 overlap. An address a is translated
to a file address by finding 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 seg‐
ments 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 re‐
gion 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 translation.
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 com‐
mands 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, respec‐
tively.
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 named test:
% db -k test 27
$C
To set a breakpoint at the entry of function parse when the local vari‐
able 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 (sup‐
pressed 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 processor of a different type.
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.
DB(1)