Subversion Repositories planix.SVN

.TH DB 1

.SH NAME

db \- debugger

.SH SYNOPSIS

.B db

[

.I option ...

]

[

.I textfile

]

[

.I pid

]

.SH DESCRIPTION

.I 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.

.PP

A

.I textfile

is a file containing the text and initialized

data of an executable program.

A

.I memfile

is the memory image of an executing process.  It is

usually accessed via the process id

.RI ( pid )

of the process in

.BI /proc/ pid /mem\f1.

A

.I memfile

contains the text, data, and saved registers and

process state.  A

.I map

associated with each

.I textfile

or

.I memfile

supports accesses to instructions and data in the file;

see `Addresses'.

.PP

An argument consisting entirely of digits is assumed

to be a process id; otherwise, it is the name of a

.IR textfile .

When a

.I textfile

is given, the textfile map

is associated with it.

If only a

.I pid

is given, the textfile map is

associated with

.BI /proc/ pid /text\f1.

When a

.I pid

is given, the memfile map is associated with

.BI /proc/ pid /mem\f1;

otherwise it is undefined and accesses to the

.I memfile

are not permitted.

.PP

Commands to

.I db

are read from the standard input and

responses are to the standard output.

The options are

.TP

.BI -k

Use the kernel stack of process

.IR pid 

to debug the executing kernel process.

If

.I textfile

is not specified, file

.BI / $cputype /9 type

is used, where

.I type

is the second word in

.BR $terminal .

.TP

.B -w

Create

.I textfile

and

.I memfile

if they don't exist; open them for writing

as well as reading.

.TP

.BI -I path

Directory in which to look for relative path names in

.B $<

and

.B $<<

commands.

.TP

.BI -m machine

Assume instructions are for the given CPU type

(any standard architecture name, such as

.B amd64

or

.BR 386 ,

plus

.B mipsco

and

.BR sunsparc ,

which cause disassembly to the manufacturer's syntax)

instead of using the magic number to select

the CPU type.

.PP

Most

.I db

commands have the following form:

.IP

.RI [ address ]

.RB [ ,

.IR count ]

.RI [ command ]

.PP

If

.I address

is present then the current position, called `dot',

is set to

.IR address .

Initially dot

is set to 0.

Most commands are repeated

.I count

times with

dot advancing between repetitions.

The default

.I count

is 1.

.I Address

and

.I count

are expressions.

Multiple commands on one line must be separated by

.LR ; .

.SS Expressions

Expressions are evaluated as long

.IR ints .

.TP 7.2n

.B .

The value of dot.

.TP 7.2n

.B +

The value of dot

incremented by the current increment.

.TP 7.2n

.B ^

The value of dot

decremented by the current increment.

.TP 7.2n

.B \&"

The last

.I address

typed.

.TP 7.2n

.I integer

A number, in decimal radix by default.

The prefixes

.L 0

and

.L 0o

and

.L 0O

(zero oh) force interpretation

in octal radix; the prefixes

.L 0t

and

.L 0T

force interpretation in

decimal radix; the prefixes

.LR 0x ,

.LR 0X ,

and

.L #

force interpretation in

hexadecimal radix.

Thus

.LR 020 ,

.LR 0o20 ,

.LR 0t16 ,

and

.L #10 

all represent sixteen.

.TP 7.2n

.IB integer . fraction

A single-precision floating point number.

.TP 7.2n

.BI \' c\| \'

The

16-bit

value of a character.

.L \e

may be used to escape a

.LR \' .

.TP 7.2n

.BI < name

The value of

.IR name ,

which is a register name.

The register names are

those printed by the

.B $r

command.

.TP 7.2n

.I symbol

A

.I symbol

is a sequence

of upper or lower case letters, underscores or

digits, not starting with a digit.

.L \e

may be used to escape other characters.

The location of the

.I symbol

is calculated from the symbol table

in

.IR textfile .

.TP 7.2n

.IB routine . name

The address of the variable

.I name

in the specified

C routine.

Both

.I routine

and

.I name

are

.IR symbols .

If

.I name

is omitted the value is the address of the

most recently activated stack frame

corresponding to

.IR routine ;

if

.I routine

is omitted,

the active procedure

is assumed.

.TP 7.2n

.IB 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.

.TP 7.2n

.BI ( exp )

The value of the expression

.IR exp .

.LP

.I  Monadic operators

.RS

.TP 7.2n

.BI * exp

The contents of the location addressed

by

.I exp

in

.IR memfile .

.TP 7.2n

.BI @ exp

The contents of the location addressed by

.I exp

in

.IR textfile .

.TP 7.2n

.BI - exp

Integer negation.

.TP 7.2n

.BI ~ exp

Bitwise complement.

.TP 7.2n

.BI % exp

When used as an

.IR address ,

.I exp

is an offset into the segment named

.IR ublock ;

see `Addresses'.

.RE

.LP

.I "Dyadic\ operators"

are left-associative

and are less binding than monadic operators.

.RS

.TP 7.2n

.IB e1 + e2

Integer addition.

.TP 7.2n

.IB e1 - e2

Integer subtraction.

.TP 7.2n

.IB e1 * e2

Integer multiplication.

.TP 7.2n

.IB e1 % e2

Integer division.

.TP 7.2n

.IB e1 & e2

Bitwise conjunction.

.TP 7.2n

.IB e1 | e2

Bitwise disjunction.

.TP 7.2n

.IB e1 # e2

.I E1

rounded up to the next multiple of

.IR e2 .

.RE

.DT

.SS Commands

Most commands have the following syntax:

.TP .5i

.BI ? f

Locations starting at

.I address

in

.I  textfile

are printed according to the format

.IR f .

.TP

.BI / f

Locations starting at

.I address

in

.I  memfile

are printed according to the format

.IR f .

.TP

.BI = f

The value of

.I address

itself is printed according to the format

.IR f .

.PP

A

.I 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.

.PP

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

.IR "current increment" .

.ta 2.5n .5i

.RS

.TP

.PD 0

.B o

Print two-byte integer in octal.

.TP

.B O

Print four-byte integer in octal.

.TP

.B q

Print two-byte integer in signed octal.

.TP

.B Q

Print four-byte integer in signed octal.

.TP

.B d

Print two-byte integer in decimal.

.TP

.B D

Print four-byte integer in decimal.

.TP

.B V

Print eight-byte integer in decimal.

.TP

.B Z

Print eight-byte integer in unsigned decimal.

.TP

.B x

Print two-byte integer in hexadecimal.

.TP

.B X

Print four-byte integer in hexadecimal.

.TP

.B Y

Print eight-byte integer in hexadecimal.

.TP

.B u

Print two-byte integer in unsigned decimal.

.TP

.B U

Print four-byte integer in unsigned decimal.

.TP

.B f

Print

as a single-precision floating point number.

.TP

.B F

Print double-precision floating point.

.TP

.B b

Print the addressed byte in hexadecimal.

.TP

.B c

Print the addressed byte as an

.SM ASCII

character.

.TP

.B C

Print the addressed byte as a character.

Printable

.SM ASCII

characters

are represented normally; others

are printed in the form

.BR \exnn .

.TP

.B s

Print the addressed characters, as a

.SM UTF

string, until a zero byte

is reached.

Advance dot

by the length of the string,

including the zero terminator.

.TP

.B S

Print a string using 

the escape convention (see

.B C

above).

.TP

.B r

Print as

.SM UTF

the addressed two-byte integer (rune).

.TP

.B R

Print as

.SM 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.

.TP

.B i

Print as machine instructions.  Dot is

incremented by the size of the instruction.

.TP

.B I

As

.B i

above, but print the machine instructions in

an alternate form if possible:

.B sunsparc

and

.B mipsco

reproduce the manufacturers' syntax.

.TP

.B M

Print the addressed machine instruction in a

machine-dependent hexadecimal form.

.TP

.B a

Print the value of dot

in symbolic form.

Dot is unaffected.

.TP

.B A

Print the value of dot

in hexadecimal.

Dot is unaffected.

.TP

.B z

Print the function name, source file, and line number

corresponding to dot (textfile only). Dot is unaffected.

.TP

.B p

Print the addressed value in symbolic form.

Dot is advanced by the size of a machine address.

.TP

.B t

When preceded by an integer, tabs to the next

appropriate tab stop.

For example,

.B 8t 

moves to the next 8-space tab stop.

Dot is unaffected.

.TP

.B n

Print a newline.

Dot is unaffected.

.tr '"

.TP

.BR ' ... '

Print the enclosed string.

Dot is unaffected.

.br

.tr ''

.TP

.B ^

Dot is decremented by the current increment.

Nothing is printed.

.TP

.B +

Dot is incremented by 1.

Nothing is printed.

.TP

.B -

Dot is decremented by 1.

Nothing is printed.

.RE

.PD

.LP

Other commands include:

.TP

newline

Update dot by the current increment.

Repeat the previous command with a

.I count

of 1.

.TP

.RB [ ?/ ] l "\fI value mask\fR"

Words starting at dot

are masked with

.I mask

and compared with

.I value

until

a match is found.

If

.B l

is used,

the match is for a two-byte integer;

.B L

matches four bytes.

If no match is found then dot

is unchanged; otherwise dot

is set to the matched location.

If

.I mask

is omitted then ~0 is used.

.TP

.RB [ ?/ ] w "\fI value ...\fR"

Write the two-byte

.I value

into the addressed

location.

If the command is

.BR W ,

write four bytes.

.TP

.RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]

.br

New values for

.RI ( b,\ e,\ f )

in the segment named

.I s

are recorded.  Valid segment names are

.IR text ,

.IR data ,

or 

.IR ublock .

If less than three address expressions are given,

the remaining parameters are left unchanged.

If the list is terminated by

.L ?

or

.L /

then the file

.RI ( textfile

or

.I memfile

respectively) is used

for subsequent requests.

For example,

.L /m?

causes

.L /

to refer to

.IR textfile .

.TP

.BI > name

Dot is assigned to the variable or register named.

.TP

.B !

The rest of the line is passed to

.IR rc (1)

for execution.

.TP

.BI $ modifier

Miscellaneous commands.

The available 

.I modifiers 

are:

.RS

.TP

.PD 0

.BI < f

Read commands from the file

.IR f .

If this command is executed in a file, further commands

in the file are not seen.

If

.I f

is omitted, the current input stream is terminated.

If a

.I count

is given, and is zero, the command is ignored.

.TP

.BI << f

Similar to

.B <

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

.B <<

files that can be open at once.

.br

.ns

.TP

.BI > f

Append output to the file

.IR f ,

which is created if it does not exist.

If

.I f

is omitted, output is returned to the terminal.

.TP

.B ?

Print process id, the condition which caused stopping or termination,

the registers and the instruction addressed by

.BR pc .

This is the default if

.I modifier

is omitted.

.TP

.B r

Print the general registers and

the instruction addressed by

.BR pc .

Dot is set to

.BR pc .

.TP

.B R

Like

.BR $r ,

but include miscellaneous processor control registers

and floating point registers.

.TP

.B f

Print floating-point register values as

single-precision floating point numbers.

.TP

.B F

Print floating-point register values as

double-precision floating point numbers.

.TP

.B b

Print all breakpoints

and their associated counts and commands.  `B' produces the same results.

.TP

.B c

Stack backtrace.

If

.I address

is given, it specifies the address of a pair of 32-bit

values containing the

.B sp

and

.B pc

of an active process.  This allows selecting

among various contexts of a multi-threaded

process.

If

.B C

is used, the names and (long) values of all

parameters,

automatic

and static variables are printed for each active function.

If

.I count

is given, only the first

.I count

frames are printed.

.TP

.B a

Attach to the running process whose pid

is contained in

.IR address .

.TP

.B e

The names and values of all

external variables are printed.

.TP

.B w

Set the page width for output to

.I address

(default 80).

.TP

.B q

Exit from

.IR db .

.TP

.B m

Print the address maps.

.TP

.B k

Simulate kernel memory management.

.TP

.BI M machine

Set the

.I machine

type used for disassembling instructions.

.PD

.RE

.TP

.BI : modifier

Manage a subprocess.

Available modifiers are:

.RS

.TP

.PD 0

.BI h

Halt

an asynchronously running process to allow breakpointing.

Unnecessary for processes created under

.IR db ,

e.g. by

.BR :r .

.TP

.BI b c

Set breakpoint at

.IR address .

The breakpoint is executed

.IR count \-1

times before

causing a stop.

Also, if a command

.I c

is given it is executed at each

breakpoint and if it sets dot to zero

the breakpoint causes a stop.

.TP

.B d

Delete breakpoint at

.IR address .

.TP

.B r

Run

.I textfile

as a subprocess.

If

.I address

is given the

program is entered at that point; otherwise

the standard entry point is used.

.I Count

specifies how many breakpoints 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 command.

.TP

.BI c s

The subprocess is continued.

If

.I 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

.BR r .

.TP

.BI s s

As for

.B c

except that

the subprocess is single stepped for

.I count

machine instructions.

If a note is pending,

it is received

before the first instruction is executed.

If there is no current subprocess then

.I textfile

is run

as a subprocess as for

.BR r .

In this case no note can be sent; the remainder of the line

is treated as arguments to the subprocess.

.TP

.BI S s

Identical to

.B s

except the subprocess is single stepped for

.I count

lines of C source.  In optimized code, the correspondence

between C source and the machine instructions is

approximate at best.

.TP

.BI x

The current subprocess, if any, is released by

.I db

and allowed to continue executing normally.

.TP

.B k

The current subprocess, if any, is terminated.

.TP

.BI n c

Display the pending notes for the process.

If

.I c

is specified, first delete

.I c'th

pending note.

.PD

.RE

.SS 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

.RI ( "t, b, e, f" ),

defining a segment named

.I t

(usually, 

.IR text ,

.IR data ,

or

.IR ublock )

mapping addresses in the range

.I b

through

.I e

to the part of the file

beginning at

offset

.IR 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

.I a

is translated

to a file address

by finding a segment

for which

.IR b ≤ a < e ;

the location in the file

is then

.IR address + f \- b .

.PP

Usually,

the text and initialized data of a program

are mapped by segments called 

.I text

and

.IR 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)

.IR memfile .

However, the segment called 

.I data

maps memory from the beginning 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

.I ublock

maps the page containing its registers and process state.

.PP

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.

.PP

Registers are saved at a machine-dependent offset in the ublock.

It is usually not necessary to know this offset; the

.BR $r ,

.BR $R ,

.BR $f ,

and

.BR $F

commands calculate it and display the register contents.

.PP

The

.B $m

command dumps the currently active maps.  The

.B ?m

and

.B /m

commands modify the segment parameters in the

.I textfile

and

.I memfile

maps, respectively.

.SH EXAMPLES

To set a breakpoint at the beginning of

.B write()

in extant process 27:

.IP

.EX

% db 27

:h

write:b

:c

.EE

.PP

To examine the Plan 9 kernel stack for process 27:

.IP

.EX

% db -k 27

$C

.EE

.PP

Similar, but using a kernel named

.BR test :

.IP

.EX

% db -k test 27

$C

.EE

.PP

To set a breakpoint at the entry of function

.B parse

when the local variable

.B argc

in

.B main

is equal to 1:

.IP

.EX

parse:b *main.argc-1=X

.EE

.PP

This prints the value of

.B argc-1

which as a side effect sets dot; when

.B argc

is one the breakpoint will fire.

Beware that local variables may be stored in registers; see the

BUGS section.

.PP

Debug process 127 on remote machine

.BR kremvax :

.IP

.EX

% import kremvax /proc

% db 127

$C

.EE

.SH FILES

.B /proc/*/text

.br

.B /proc/*/mem

.br

.B /proc/*/ctl

.br

.B /proc/*/note

.SH "SEE ALSO"

.IR acid (1),