glenda.party
term% ls -F
term% pwd
$home/manuals/plan9_4th/1/db
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)