19 is a general purpose debugging program.
20 It may be used to examine files and to provide
21 a controlled environment for the execution
26 is a file containing the text and initialized
27 data of an executable program.
32 specifies the memory image of a process.
35 gives the id of an executing process to be accessed via
39 specifies the name of a core dump (see
41 on your system of choice) containing the
42 memory image of a terminated process.
43 This manual refers to the memory image specified by
56 supports accesses to instructions and data in the file;
59 An argument consisting entirely of digits is assumed
60 to be a process id; otherwise, it is the name of a
66 is given, the textfile map
67 is associated with it.
70 is given, the textfile map is
71 derived from the corresponding
73 if it can be determined
74 (this varies from system to system).
77 is given, the memfile map is associated with it;
78 otherwise the map is undefined and accesses to it
83 are read from the standard input and
84 responses are to the standard output.
92 for writing as well as reading.
95 Directory in which to look for relative path names in
102 Assume instructions are for the given CPU type
103 (possible names include
114 selects disassembly in the manufacturer's syntax, if
116 rather than the default Plan 9 syntax).
120 commands have the following form:
129 is present then the current position, called `dot',
134 Most commands are repeated
137 dot advancing between repetitions.
145 Multiple commands on one line must be separated by
148 Expressions are evaluated as long
156 incremented by the current increment.
160 decremented by the current increment.
168 A number, in decimal radix by default.
175 (zero oh) force interpretation
176 in octal radix; the prefixes
180 force interpretation in
181 decimal radix; the prefixes
186 force interpretation in
194 all represent sixteen.
196 .IB integer . fraction
197 A single-precision floating point number.
202 value of a character.
204 may be used to escape a
210 which is a register name.
211 The register names are
220 of upper or lower case letters, underscores or
221 digits, not starting with a digit.
223 may be used to escape other characters.
226 is calculated from the symbol table
231 The address of the variable
243 is omitted the value is the address of the
244 most recently activated stack frame
254 The address of the instruction corresponding
255 to the source statement at the indicated
256 line number of the file. If the source line contains
257 no executable statement, the address of the
258 instruction associated with the nearest
259 executable source line is returned. Files
260 begin at line 1. If multiple files of the same
261 name are loaded, an expression of this form resolves
262 to the first file encountered in the symbol table.
265 The value of the expression
272 The contents of the location addressed
279 The contents of the location addressed by
294 is an offset into the segment named
299 .I "Dyadic\ operators"
301 and are less binding than monadic operators.
311 Integer multiplication.
324 rounded up to the next multiple of
329 Most commands have the following syntax:
332 Locations starting at
336 are printed according to the format
340 Locations starting at
344 are printed according to the format
350 itself is printed according to the format
355 consists of one or more characters that specify a style
357 Each format character may be preceded by a decimal integer
358 that is a repeat count for the format character.
359 If no format is given then the last format is used.
361 Most format letters fetch some data,
363 and advance (a local copy of) dot
364 by the number of bytes fetched.
365 The total number of bytes in a format becomes the
366 .IR current increment .
372 Print two-byte integer in octal.
375 Print four-byte integer in octal.
378 Print two-byte integer in signed octal.
381 Print four-byte integer in signed octal.
384 Print two-byte integer in decimal.
387 Print four-byte integer in decimal.
390 Print eight-byte integer in decimal.
393 Print eight-byte integer in unsigned decimal.
396 Print two-byte integer in hexadecimal.
399 Print four-byte integer in hexadecimal.
402 Print eight-byte integer in hexadecimal.
405 Print two-byte integer in unsigned decimal.
408 Print four-byte integer in unsigned decimal.
412 as a single-precision floating point number.
415 Print double-precision floating point.
418 Print the addressed byte in hexadecimal.
421 Print the addressed byte as an
426 Print the addressed byte as a character.
430 are represented normally; others
431 are printed in the form
435 Print the addressed characters, as a
437 string, until a zero byte
440 by the length of the string,
441 including the zero terminator.
445 the escape convention (see
452 the addressed two-byte integer (rune).
457 the addressed two-byte integers as runes
458 until a zero rune is reached.
460 by the length of the string,
461 including the zero terminator.
464 Print as machine instructions. Dot is
465 incremented by the size of the instruction.
470 above, but print the machine instructions in
471 an alternate form if possible.
474 Print the addressed machine instruction in a
475 machine-dependent hexadecimal form.
478 Print the value of dot
483 Print the value of dot
488 Print the function name, source file, and line number
489 corresponding to dot (textfile only). Dot is unaffected.
492 Print the addressed value in symbolic form.
493 Dot is advanced by the size of a machine address.
496 When preceded by an integer, tabs to the next
497 appropriate tab stop.
500 moves to the next 8-space tab stop.
509 Print the enclosed string.
515 Dot is decremented by the current increment.
519 Dot is incremented by 1.
523 Dot is decremented by 1.
528 Other commands include:
531 Update dot by the current increment.
532 Repeat the previous command with a
536 .RB [ ?/ ] l "\fI value mask\fR"
537 Words starting at dot
547 the match is for a two-byte integer;
550 If no match is found then dot
551 is unchanged; otherwise dot
552 is set to the matched location.
555 is omitted then ~0 is used.
557 .RB [ ?/ ] w "\fI value ...\fR"
566 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
572 are recorded. Valid segment names are
577 If less than three address expressions are given,
578 the remaining parameters are left unchanged.
579 If the list is terminated by
587 respectively) is used
588 for subsequent requests.
597 Dot is assigned to the variable or register named.
600 The rest of the line is passed to
605 Miscellaneous commands.
613 Read commands from the file
615 If this command is executed in a file, further commands
616 in the file are not seen.
619 is omitted, the current input stream is terminated.
622 is given, and is zero, the command is ignored.
627 except it can be used in a file of commands without
628 causing the file to be closed.
629 There is a (small) limit to the number of
631 files that can be open at once.
636 Append output to the file
638 which is created if it does not exist.
641 is omitted, output is returned to the terminal.
644 Print process id, the condition which caused stopping or termination,
645 the registers and the instruction addressed by
647 This is the default if
652 Print the general registers and
653 the instruction addressed by
661 but include miscellaneous processor control registers
662 and floating point registers.
665 Print floating-point register values as
666 single-precision floating point numbers.
669 Print floating-point register values as
670 double-precision floating point numbers.
673 Print all breakpoints
674 and their associated counts and commands. `B' produces the same results.
680 is given, it specifies the address of a pair of 32-bit
681 values containing the
685 of an active process. This allows selecting
686 among various contexts of a multi-threaded
690 is used, the names and (long) values of all
693 and static variables are printed for each active function.
696 is given, only the first
701 Attach to the running process whose pid
706 The names and values of all
707 external variables are printed.
710 Set the page width for output to
719 Print the address maps.
722 Simulate kernel memory management.
727 type used for disassembling instructions.
733 Available modifiers are:
739 an asynchronously running process to allow breakpointing.
740 Unnecessary for processes created under
748 The breakpoint is executed
754 is given it is executed at each
755 breakpoint and if it sets dot to zero
756 the breakpoint causes a stop.
769 program is entered at that point; otherwise
770 the standard entry point is used.
772 specifies how many breakpoints are to be
773 ignored before stopping.
774 Arguments to the subprocess may be supplied on the
775 same line as the command.
776 An argument starting with < or > causes the standard
777 input or output to be established for the command.
780 The subprocess is continued.
786 is sent the note that caused it to stop.
790 (If the stop was due to a breakpoint or single-step,
791 the corresponding note is elided before continuing.)
792 Breakpoint skipping is the same
800 the subprocess is single stepped for
802 machine instructions.
803 If a note is pending,
805 before the first instruction is executed.
806 If there is no current subprocess then
809 as a subprocess as for
811 In this case no note can be sent; the remainder of the line
812 is treated as arguments to the subprocess.
817 except the subprocess is single stepped for
819 lines of C source. In optimized code, the correspondence
820 between C source and the machine instructions is
824 The current subprocess, if any, is released by
826 and allowed to continue executing normally.
829 The current subprocess, if any, is terminated.
832 Display the pending notes for the process.
835 is specified, first delete
841 The location in a file or memory image associated with
842 an address is calculated from a map
843 associated with the file.
844 Each map contains one or more quadruples
845 .RI ( "t, f, b, e, o" ),
846 defining a segment named
855 mapping addresses in the range
859 to the part of the file
863 If segments overlap, later segments obscure earlier ones.
868 by finding the last segment in the list
871 the location in the file
873 .IR address + f \- b .
876 the text and initialized data of a program
877 are mapped by segments called
882 Since a program file does not contain stack data,
885 The text segment is mapped similarly in
886 a normal (i.e., non-kernel)
888 However, one or more segments called
890 provide access to process memory.
891 This region contains the program's static data, the bss, the
894 Sometimes it is useful to define a map with a single segment
895 mapping the region from 0 to 0xFFFFFFFF; a map of this type
896 allows an entire file to be examined
897 without address translation.
901 command dumps the currently active maps. The
905 commands modify the segment parameters in the
911 To set a breakpoint at the beginning of
913 in extant process 27:
930 To set a breakpoint at the entry of function
932 when the local variable
939 parse:b *main.argc-1=X
942 This prints the value of
944 which as a side effect sets dot; when
946 is one the breakpoint will fire.
947 Beware that local variables may be stored in registers; see the
952 .B /usr/local/plan9/src/cmd/db
954 Exit status is 0, unless the last command failed or
955 returned non-zero status.
957 Examining a local variable with
959 returns the contents of the memory allocated for the variable, but
960 with optimization, variables often reside in registers.
961 Also, on some architectures, the first argument is always
962 passed in a register.
964 Variables and parameters that have been
965 optimized away do not appear in the
966 symbol table, returning the error
967 .IR "bad local variable"
971 Breakpoints should not be set on instructions scheduled
972 in delay slots. When a program stops on such a breakpoint,
973 it is usually impossible to continue its execution.
