man(1) Manual page archive

     DB(1)                                                       DB(1)

          db, dbfmt - debugger

          db [ option ... ] [ textfile [ memfile ] ]

          db [ -k ] pid


          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.

          Textfile is normally an executable program file or
          /proc/pid/text.  Memfile is the memory image of a process,
          usually obtained from /proc/pid/mem.  If there is exactly
          one argument, and it is numeric, then it is used as a pid to
          find the text and mem files in /proc/pid.

          Requests to db are read from the standard input and
          responses are to the standard output.  The options are

          -k pid
               Use the kernel for the textfile and memfile, with the
               kernel stack of process pid.

          -w   Create textfile and memfile if they don't exist; open
               them for writing as well as reading.

               Directory in which to look for relative path names in
               $< and $<< commands.

               Assume instructions are for the given CPU type (one of
               386, 68020, 960, hobbit, mips, mipsco, sparc, or
               sunsparc) instead of using the magic number in the text
               file to select the CPU type.

          In general requests to db have the following form.  Multiple
          requests on one line must be separated by `;'.

               [address] [, count] [command]

          If address is present then the current position, called
          `dot', is set to address. Initially dot is set to 0.  In
          general commands are repeated count times.  Dot advances
          between repetitions.  The default count is 1.  Address and

     DB(1)                                                       DB(1)

          count are expressions.

          Expressions are evaluated as long ints.

          .      The value of dot.

          +      The value of dot incremented by the current incre-

          ^      The value of dot decremented by the current incre-

          "      The last address typed.

                 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.

                 A single-precision floating point number.

          'c'    The Unicode value of a character.  `\' may be used to
                 escape a `''.

          <name  The value of name, which is either a variable name or
                 a register name.  db maintains a number of variables
                 named by single letters or digits.  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.

                 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 C stack frame corresponding to
                 routine; if routine is omitted, the active procedure
                 is assumed.

                 The address of the instruction corresponding to the C
                 source statement at the indicated line number of the

     DB(1)                                                       DB(1)

                 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

          @exp   The contents of the location addressed by exp in

          -exp   Integer negation.

          ~exp   Bitwise complement.

          %exp   If exp is used as an address, it is in register
                 space; 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.

          Most commands consist of a verb followed by a modifier or
          list of modifiers.  The following verbs are available.  (The
          commands `?'  and `/' may be followed by `*'; see
          `Addresses' for further details.)

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

     DB(1)                                                       DB(1)

          =f   The value of address itself is printed in the styles
               indicated by 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

          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

               o    Print two-byte integer in octal.
               O    Print four-byte integer in octal.
               q    Print two-byte in signed octal.
               Q    Print four-byte in signed octal.
               d    Print two-byte in decimal.
               D    Print four-byte in decimal.
               x    Print two-byte in hexadecimal.
               X    Print four-byte in hexadecimal.
               u    Print two-byte in unsigned decimal.
               U    Print four-byte 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-
               S    Print a string using the escape convention (see C
               r    Print the addressed two-byte integer as a rune.
               R    Print the addressed two-byte integers as runes
                    until a zero rune is reached.  Advance dot by the
                    length of the string, including the zero termina-
               Y    Print a four-byte integer in date format (see
               i    Print as machine instructions.  This style of
                    printing causes variables 0, (1, ...)  to be set
                    to the offset parts of the first (second, ...)
                    operand of the instruction.
               I    As i above, but print the machine instructions in
                    an alternate form if possible: sunsparc and mipsco
                    reproduce the manufacturers' syntax.
               M    Print the addressed machine instruction in a

     DB(1)                                                       DB(1)

                    machine dependent hexadecimal form.
               a    Print the value of dot in symbolic form.  Dot is
               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.

               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 map entry named s are
               recorded.  Valid map entry names are text, data,
               ublock, or regs. If less than three address expressions
               are given then the remaining map parameters are left
               unchanged.  The address type (instruction or data) is
               unchanged in any case.  If the list is terminated by
               `?'  or `/' then the file (textfile or memfile respec-
               tively) is used for subsequent requests.  For example,
               `/m?'  causes `/' to refer to textfile.

               Dot is assigned to the variable or register named.

          !    Tem rest of the line is passed to the rc(1) for execu-

     DB(1)                                                       DB(1)

               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.  The value of the
                    count is placed in variable 9 before the first
                    command in f is executed.  A common use for this
                    command is to print the fields of a structure.
                    The dbfmt program takes a structure description on
                    standard input and produces a file on standard
                    output suitable for use in a addr$<f command.  The
                    -sname option of 2c(1) produces a structure
                    description for structure or union name.
               <<f  Similar to < except it can be used in a file of
                    commands without causing the file to be closed.
                    Variable 9 is saved during the execution of this
                    command, and restored when it completes.  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, as well as the registers.
                    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 registers such
                    as the kernel stack pointer and floating point
               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.
               c    C stack backtrace.  If address is given then it is
                    taken as the address of the current frame; other-
                    wise, the current C frame pointer is used.  If C
                    is used then the names and (long) values of all
                    parameters, automatic and static variables are
                    printed for each active function.  If count is
                    given then only the first count frames are
               a    Set the maximum number of arguments printed by $c
                    or $C to address. The default is 20.
               e    The names and values of all external variables are
               w    Set the page width for output to address (default

     DB(1)                                                       DB(1)

               s    Set the limit for symbol matches, used in printing
                    addresses, to address (default 255).
               q    Exit from db.
               v    Print all non zero variables.
               m    Print the address maps.
               k    Simulate kernel memory management.
               p    Use kernel data and stack maps for the specified
                    $k and $p are used for system debugging (see the
                    Examples section).
                    Set the machine type used for disassembling

               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

     DB(1)                                                       DB(1)

                    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.

          db provides a number of variables.  Named variables are set
          initially by db but are not used subsequently.  Numbered
          variables are reserved for communication as follows.

          0, 1, ...
               The offset parts of the first, second, ...  operands of
               the last instruction printed.  Meaningless if the
               operand was a register.
          9    The count on the last $< or $<< command.

          On entry the following are set from the system header in the
          memfile. If memfile does not appear to be a memory image
          then these values are set from textfile.

          b    The base address of the data segment.
          d    The data segment size.
          e    The entry point.
          m    The `magic' number (see a.out(6)).
          s    The stack segment size.
          t    The text segment size.

          The address in a file associated with a written address is
          determined by a mapping associated with that file.  Each
          mapping is represented by one or more quadruples (t, b, e,
          f), mapping an address of type t (text, data, user block, or
          registers) in the range b through e to the part of the file
          beginning at address f. An address a of type t is mapped to
          a file address by finding a quadruple of type t, for which
          b≦a<e; the file address is address+f-b.  As a special case,
          if a text space address is not found, a second search is
          made for the same address in data space.

          Typically, the text segment of a program is mapped as text
          space, the data and bss segments as data space.  If textfile
          is an executable file or if memfile is a memory image, maps
          are set accordingly.  Otherwise, a single `data space' map
          is set up, with b and f set to zero, and e set to a huge
          number; thus the entire file can be examined without address

          The ? and / commands attempt to examine text and data space
          respectively.  ?* tries for data space (in textfile); /*

     DB(1)                                                       DB(1)

          accesses text space (in memfile).

          Registers in process and core images are a special case;
          they live in a special `register' address space starting at
          %0; the layout of this space is machine-dependent.  %
          addresses are mapped to the registers for the `current
          frame,' set by local variable references, and reset to the
          outermost frame (the `real' registers) whenever a process
          runs or a stack trace is requested.

          Simulated memory management translations (the $k and $p com-
          mands) are done before the mapping described above.

          To set a breakpoint at the beginning of write() in extant
          process 27:

               db 27

          To examine the Plan 9 kernel stack for process 27:

               db -k 27

          Similar, but using a kernel test:

               db test /proc/27/mem

          To print the fields of the Dir structure at address #20000,
          assuming main.c includes a declaration of that structure:

               !2c -sDir -o /dev/null main.c | dbfmt > Dir.dbfmt

          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


     DB(1)                                                       DB(1)


          nm(1), proc(3)
          J. F. Maranzano and S. R. Bourne, `A Tutorial Introduction
          to ADB' in Bell Laboratories, UNIX Programmer's Manual, Vol-
          ume 2, Holt, Rinehart and Winston (1984)

          Exit status is null, unless the last command failed or
          returned non-null status.

          The alternate sparc disassembly format, sunsparc, reverses
          the order of the first two registers relative to the SUN

          Examining a local variable with returns the
          contents of the memory allocated for the variable.  This
          might return the wrong value: optimization may move the
          variable into a register, especially in the current stack
          frame.  Compiling with the -N flag may help.

          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.

          In some cases, the stack frame is not completely set when a
          breakpoint or single step stops a process in the first cou-
          ple of instructions of a function.  As a result, the $c and
          $C produce inaccurate stack traces.  Stepping a couple of
          instructions into the function sets the stack frame and pro-
          duces accurate traces.