DB(1)                                                       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 executable 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 undefined 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 exe-
               cuting kernel 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 (one of
               3210, 386, 68020, 960, mips, mipsco, sparc, or
               sunsparc) instead of using the magic number to select
               the CPU type.

          Most db commands have the following form:

     Page 1                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

               [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 sepa-
          rated by `;'.

        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 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 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
                 or ALEF routine.  Both routine and name are symbols.
                 If name is omitted the value is the address of the
                 most recently activated stack frame corresponding to
                 routine; if routine is omitted, the active procedure

     Page 2                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

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

     Page 3                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

          /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.
               x    Print two-byte integer in hexadecimal.
               X    Print four-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.  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 as UTF the addressed two-byte integer
                    (rune).
               R    Print as 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.
               Y    Print a four-byte integer in date format (see
                    ctime(2)).
               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 alternate form if possible: sunsparc and mipsco

     Page 4                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

                    reproduce the manufacturers' syntax.
               M    Print the addressed machine instruction in a
                    machine-dependent hexadecimal form.
               a    Print the value of dot in symbolic form.  Dot is
                    unaffected.
               A    Print the value of dot in hexadecimal.  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.

          Other commands include:

          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 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 subse-
               quent requests.  For example, `/m?'  causes `/' to
               refer to textfile.

          >name

     Page 5                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

               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
                    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.
               <<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 stop-
                    ping 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 con-
                    trol registers 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 speci-
                    fies the address of a pair of 32-bit values con-
                    taining 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, automatic and
                    static variables are printed for each active func-
                    tion.  If count is given, only the first count
                    frames are printed.
               a    Attach to the running process whose pid is con-
                    tained 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

     Page 6                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

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

        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),

     Page 7                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

          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 over-
          lap.  An address a is translated to a file address by find-
          ing 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 segments 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 region 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 trans-
          lation.

          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 commands 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, respectively.

     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

     Page 8                       Plan 9             (printed 3/28/24)

     DB(1)                                                       DB(1)

               $C

          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.

          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 (suppressed 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 proces-
          sor 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.

     Page 9                       Plan 9             (printed 3/28/24)