|  | 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. 
    
    
    A textfile is a file containing the text and initialized data
    of an executable program. A pid or corefile specifies the memory
    image of a process. A pid gives the id of an executing process
    to be accessed via ptrace(2). A corefile specifies the name of
    a core dump (see core(5) on your system of choice) containing
    the memory image of a terminated process.
    This manual refers to the memory image specified by pid or corefile
    as a memfile. 
    
    
    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 or corefile. When
    a textfile is given, the textfile map is associated with it. If
    only a memfile is given, the textfile map is derived from the
    corresponding textfile, if it can be determined (this varies from
    system to system). When a memfile is given,
    the memfile map is associated with it; otherwise the map is undefined
    and accesses to it are not permitted. 
    
    
    Stack takes the same arguments as db. It prints a stack trace
    (see the $c command below) and then exits. If the first argument
    is a process name, then stack prints the stack trace of every
    running process with the given name that is owned by the current
    user. 
    
    
    Commands to db are read from the standard input and responses
    are to the standard output. The options are −q    Quiet mode: suppress informational prints at startup.
 −w    Open textfile and memfile for writing as well as reading.
 −IpathDirectory in which to look for relative path names in $<
    and $<< commands.
 −mmachine
 
 Most db commands have the following form:|  |  |  | Assume instructions are for the given CPU type (possible names
        include 386 and powerpc; adding the suffix −co as in 386−co and
        powerpc−co selects disassembly in the manufacturer’s syntax, if
        available, rather than the default Plan 9 syntax). | 
 
 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 ;.|  |  |  | [address] [, count] [command] | 
 
 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.
 integerA 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
 
 'c'   The 16-bit value of a character. \ may be used to escape a
    '.|  |  |  | A single-precision floating point number. 
 | 
 <nameThe value of name, which is a register name. The register
    names are those printed by the $r command.
 symbolA symbol is a sequence of upper or lower case letters, 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
 
 file:integer|  |  |  | 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 corresponding
        to routine; if routine is omitted, the active procedure is assumed. 
 | 
 
 (exp)The value of the expression exp. 
    
    
    Monadic operators|  |  |  | 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. 
 | 
 
 Dyadic operators are left-associative and are less binding than
    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’.
 
 | 
 
 |  |  |  | e1+e2Integer addition. e1−e2Integer subtraction.
 e1*e2Integer multiplication.
 e1%e2Integer division.
 e1&e2Bitwise conjunction.
 e1|e2Bitwise disjunction.
 e1#e2E1 rounded up to the next multiple of e2.
 
 | 
 Commands     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 currentincrement.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.
 
 Other commands include:|  |  |  | 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 until 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 alternate
        form if possible.
 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.
 
 | 
 newline
 
 [?/]l value mask|  |  |  | Update dot by the current increment. Repeat the previous command
        with a count of 1. 
 | 
 
 [?/]w value ...|  |  |  | 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. 
 | 
 
 [?/]m s b e f [?]|  |  |  | Write the two-byte value into the addressed location. If the command
        is W, write four bytes. 
 | 
 
 >nameDot is assigned to the variable or register named.|  |  |  | 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, /m? causes
        / to refer to textfile. 
 | 
 !     The rest of the line is passed to rc(1) for execution.
 $modifier
 
 :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 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 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 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,
        automatic and static variables are printed for each active function.
        If
 a     Attach to the running process whose pid is contained in address.|  |  |  | count is given, only the first count frames are printed. 
 | 
 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. 
 | 
 | 
 
 |  |  |  | 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 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 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
 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.|  |  |  | standard input or output to be established for the command. 
 | 
 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     Usually, the text and initialized data of a program are mapped
    by segments called text, data, and 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) memfile. However,
    one or more segments called data provide access to process memory.
    This region
    contains the program’s static data, the bss, the heap and the
    stack. 
    
    
    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. 
    
    
    The $m command dumps the currently active maps. The ?m and /m
    commands modify the segment parameters in the textfile and memfile
    maps, respectively.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, f, b, e, o), defining a segment named
    t (usually, text, data, or core) in file f mapping addresses in
    the range b through e to the part of the file beginning at offset
    o. If segments overlap, later
    segments obscure earlier ones. An address a is translated to a
    file address by finding the last segment in the list for which
    b≤a<e; the location in the file is then address+f–b.
 
 |