commit 6e18e03e63942f7b0912bb91d0da02fd493af0af
from: rsc <devnull@localhost>
date: Sun Apr 11 04:22:00 2004 UTC

Modified db man page.

commit - bf8a59fa013f5c705369fbe14e23ca78c4d09cb8
commit + 6e18e03e63942f7b0912bb91d0da02fd493af0af
blob - /dev/null
blob + a0ed941cd511c155a24fe5261d7f891c610f5e0d (mode 644)
--- /dev/null
+++ man/man1/db.1
@@ -0,0 +1,976 @@
+.TH DB 1
+.SH NAME
+db \- debugger
+.SH SYNOPSIS
+.B db
+[
+.I option ...
+]
+[
+.I textfile
+]
+[
+.I pid
+|
+.I corefile
+]
+.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 programs.
+.PP
+A
+.I textfile
+is a file containing the text and initialized
+data of an executable program.
+A
+.I pid
+or
+.I corefile
+specifies the memory image of a process.
+A 
+.I pid
+gives the id of an executing process to be accessed via
+.IR ptrace (2)
+or
+.IR proc (5).
+A
+.I corefile
+specifies the name of a core dump (see
+.IR core (5)
+on your system of choice) containing the
+memory image of a terminated process.
+This manual refers to the memory image specified by
+.I pid
+or
+.I corefile
+as a
+.IR memfile .
+.PP
+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
+.I textfile
+or
+.IR corefile .
+When a
+.I textfile
+is given, the textfile map
+is associated with it.
+If only a
+.I memfile
+is given, the textfile map is
+derived from the corresponding
+.IR textfile ,
+if it can be determined
+(this varies from system to system).
+When a
+.I memfile
+is given, the memfile map is associated with it;
+otherwise the map is undefined and accesses to it
+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
+.B -w
+Open
+.I textfile
+and
+.I memfile
+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
+(possible names include
+.B 386
+and
+.BR powerpc ;
+adding
+the suffix
+.B -co
+as in
+.B 386-co
+and
+.B powerpc-co
+selects disassembly in the manufacturer's syntax, if
+available,
+rather than the default Plan 9 syntax).
+.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.
+.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, f, b, e, o" ),
+defining a segment named
+.I t
+(usually, 
+.IR text ,
+.IR data ,
+or
+.IR core )
+in file
+.I f
+mapping addresses in the range
+.I b
+through
+.IR e
+to the part of the file
+beginning at
+offset
+.IR o .
+If segments overlap, later segments obscure earlier ones.
+An address
+.I a
+is translated
+to a file address
+by finding the last segment in the list
+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 
+.IR text ,
+.IR data ,
+and
+.IR bss .
+Since a program file does not contain stack data,
+this data is
+not mapped.
+The text segment is mapped similarly in
+a normal (i.e., non-kernel)
+.IR memfile .
+However, one or more segments called 
+.I data
+provide access to process memory.
+This region contains the program's static data, the bss, the
+heap and the stack.
+.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 an entire file to be examined
+without address translation.
+.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
+.de EX
+.RS
+.ft B
+.nf
+..
+.de EE
+.RE
+..
+.EX
+% db 27
+:h
+write:b
+: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.
+.SH "SEE ALSO"
+.IR 9nm (1),
+.IR acid (1)
+.SH SOURCE
+.B /sys/src/cmd/db
+.SH DIAGNOSTICS
+Exit status is 0, unless the last command failed or
+returned non-zero status.
+.SH BUGS
+Examining a local variable with
+.I 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.
+.PP
+Variables and parameters that have been
+optimized away do not appear in the
+symbol table, returning the error 
+.IR "bad local variable"
+when accessed by
+.IR db .
+.PP
+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.