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
41 specifies the name of a core dump (see
43 on your system of choice) containing the
44 memory image of a terminated process.
45 This manual refers to the memory image specified by
58 supports accesses to instructions and data in the file;
61 An argument consisting entirely of digits is assumed
62 to be a process id; otherwise, it is the name of a
68 is given, the textfile map
69 is associated with it.
72 is given, the textfile map is
73 derived from the corresponding
75 if it can be determined
76 (this varies from system to system).
79 is given, the memfile map is associated with it;
80 otherwise the map is undefined and accesses to it
85 are read from the standard input and
86 responses are to the standard output.
94 for writing as well as reading.
97 Directory in which to look for relative path names in
104 Assume instructions are for the given CPU type
105 (possible names include
116 selects disassembly in the manufacturer's syntax, if
118 rather than the default Plan 9 syntax).
122 commands have the following form:
131 is present then the current position, called `dot',
136 Most commands are repeated
139 dot advancing between repetitions.
147 Multiple commands on one line must be separated by
150 Expressions are evaluated as long
158 incremented by the current increment.
162 decremented by the current increment.
170 A number, in decimal radix by default.
177 (zero oh) force interpretation
178 in octal radix; the prefixes
182 force interpretation in
183 decimal radix; the prefixes
188 force interpretation in
196 all represent sixteen.
198 .IB integer . fraction
199 A single-precision floating point number.
204 value of a character.
206 may be used to escape a
212 which is a register name.
213 The register names are
222 of upper or lower case letters, underscores or
223 digits, not starting with a digit.
225 may be used to escape other characters.
228 is calculated from the symbol table
233 The address of the variable
245 is omitted the value is the address of the
246 most recently activated stack frame
256 The address of the instruction corresponding
257 to the source statement at the indicated
258 line number of the file. If the source line contains
259 no executable statement, the address of the
260 instruction associated with the nearest
261 executable source line is returned. Files
262 begin at line 1. If multiple files of the same
263 name are loaded, an expression of this form resolves
264 to the first file encountered in the symbol table.
267 The value of the expression
274 The contents of the location addressed
281 The contents of the location addressed by
296 is an offset into the segment named
301 .I "Dyadic\ operators"
303 and are less binding than monadic operators.
313 Integer multiplication.
326 rounded up to the next multiple of
331 Most commands have the following syntax:
334 Locations starting at
338 are printed according to the format
342 Locations starting at
346 are printed according to the format
352 itself is printed according to the format
357 consists of one or more characters that specify a style
359 Each format character may be preceded by a decimal integer
360 that is a repeat count for the format character.
361 If no format is given then the last format is used.
363 Most format letters fetch some data,
365 and advance (a local copy of) dot
366 by the number of bytes fetched.
367 The total number of bytes in a format becomes the
368 .IR current increment .
374 Print two-byte integer in octal.
377 Print four-byte integer in octal.
380 Print two-byte integer in signed octal.
383 Print four-byte integer in signed octal.
386 Print two-byte integer in decimal.
389 Print four-byte integer in decimal.
392 Print eight-byte integer in decimal.
395 Print eight-byte integer in unsigned decimal.
398 Print two-byte integer in hexadecimal.
401 Print four-byte integer in hexadecimal.
404 Print eight-byte integer in hexadecimal.
407 Print two-byte integer in unsigned decimal.
410 Print four-byte integer in unsigned decimal.
414 as a single-precision floating point number.
417 Print double-precision floating point.
420 Print the addressed byte in hexadecimal.
423 Print the addressed byte as an
428 Print the addressed byte as a character.
432 are represented normally; others
433 are printed in the form
437 Print the addressed characters, as a
439 string, until a zero byte
442 by the length of the string,
443 including the zero terminator.
447 the escape convention (see
454 the addressed two-byte integer (rune).
459 the addressed two-byte integers as runes
460 until a zero rune is reached.
462 by the length of the string,
463 including the zero terminator.
466 Print as machine instructions. Dot is
467 incremented by the size of the instruction.
472 above, but print the machine instructions in
473 an alternate form if possible.
476 Print the addressed machine instruction in a
477 machine-dependent hexadecimal form.
480 Print the value of dot
485 Print the value of dot
490 Print the function name, source file, and line number
491 corresponding to dot (textfile only). Dot is unaffected.
494 Print the addressed value in symbolic form.
495 Dot is advanced by the size of a machine address.
498 When preceded by an integer, tabs to the next
499 appropriate tab stop.
502 moves to the next 8-space tab stop.
511 Print the enclosed string.
517 Dot is decremented by the current increment.
521 Dot is incremented by 1.
525 Dot is decremented by 1.
530 Other commands include:
533 Update dot by the current increment.
534 Repeat the previous command with a
538 .RB [ ?/ ] l "\fI value mask\fR"
539 Words starting at dot
549 the match is for a two-byte integer;
552 If no match is found then dot
553 is unchanged; otherwise dot
554 is set to the matched location.
557 is omitted then ~0 is used.
559 .RB [ ?/ ] w "\fI value ...\fR"
568 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
574 are recorded. Valid segment names are
579 If less than three address expressions are given,
580 the remaining parameters are left unchanged.
581 If the list is terminated by
589 respectively) is used
590 for subsequent requests.
599 Dot is assigned to the variable or register named.
602 The rest of the line is passed to
607 Miscellaneous commands.
615 Read commands from the file
617 If this command is executed in a file, further commands
618 in the file are not seen.
621 is omitted, the current input stream is terminated.
624 is given, and is zero, the command is ignored.
629 except it can be used in a file of commands without
630 causing the file to be closed.
631 There is a (small) limit to the number of
633 files that can be open at once.
638 Append output to the file
640 which is created if it does not exist.
643 is omitted, output is returned to the terminal.
646 Print process id, the condition which caused stopping or termination,
647 the registers and the instruction addressed by
649 This is the default if
654 Print the general registers and
655 the instruction addressed by
663 but include miscellaneous processor control registers
664 and floating point registers.
667 Print floating-point register values as
668 single-precision floating point numbers.
671 Print floating-point register values as
672 double-precision floating point numbers.
675 Print all breakpoints
676 and their associated counts and commands. `B' produces the same results.
682 is given, it specifies the address of a pair of 32-bit
683 values containing the
687 of an active process. This allows selecting
688 among various contexts of a multi-threaded
692 is used, the names and (long) values of all
695 and static variables are printed for each active function.
698 is given, only the first
703 Attach to the running process whose pid
708 The names and values of all
709 external variables are printed.
712 Set the page width for output to
721 Print the address maps.
724 Simulate kernel memory management.
729 type used for disassembling instructions.
735 Available modifiers are:
741 an asynchronously running process to allow breakpointing.
742 Unnecessary for processes created under
750 The breakpoint is executed
756 is given it is executed at each
757 breakpoint and if it sets dot to zero
758 the breakpoint causes a stop.
771 program is entered at that point; otherwise
772 the standard entry point is used.
774 specifies how many breakpoints are to be
775 ignored before stopping.
776 Arguments to the subprocess may be supplied on the
777 same line as the command.
778 An argument starting with < or > causes the standard
779 input or output to be established for the command.
782 The subprocess is continued.
788 is sent the note that caused it to stop.
792 (If the stop was due to a breakpoint or single-step,
793 the corresponding note is elided before continuing.)
794 Breakpoint skipping is the same
802 the subprocess is single stepped for
804 machine instructions.
805 If a note is pending,
807 before the first instruction is executed.
808 If there is no current subprocess then
811 as a subprocess as for
813 In this case no note can be sent; the remainder of the line
814 is treated as arguments to the subprocess.
819 except the subprocess is single stepped for
821 lines of C source. In optimized code, the correspondence
822 between C source and the machine instructions is
826 The current subprocess, if any, is released by
828 and allowed to continue executing normally.
831 The current subprocess, if any, is terminated.
834 Display the pending notes for the process.
837 is specified, first delete
843 The location in a file or memory image associated with
844 an address is calculated from a map
845 associated with the file.
846 Each map contains one or more quadruples
847 .RI ( "t, f, b, e, o" ),
848 defining a segment named
857 mapping addresses in the range
861 to the part of the file
865 If segments overlap, later segments obscure earlier ones.
870 by finding the last segment in the list
873 the location in the file
875 .IR address + f \- b .
878 the text and initialized data of a program
879 are mapped by segments called
884 Since a program file does not contain stack data,
887 The text segment is mapped similarly in
888 a normal (i.e., non-kernel)
890 However, one or more segments called
892 provide access to process memory.
893 This region contains the program's static data, the bss, the
896 Sometimes it is useful to define a map with a single segment
897 mapping the region from 0 to 0xFFFFFFFF; a map of this type
898 allows an entire file to be examined
899 without address translation.
903 command dumps the currently active maps. The
907 commands modify the segment parameters in the
913 To set a breakpoint at the beginning of
915 in extant process 27:
932 To set a breakpoint at the entry of function
934 when the local variable
941 parse:b *main.argc-1=X
944 This prints the value of
946 which as a side effect sets dot; when
948 is one the breakpoint will fire.
949 Beware that local variables may be stored in registers; see the
955 .B /usr/local/plan9/src/cmd/db
957 Exit status is 0, unless the last command failed or
958 returned non-zero status.
960 Examining a local variable with
962 returns the contents of the memory allocated for the variable, but
963 with optimization, variables often reside in registers.
964 Also, on some architectures, the first argument is always
965 passed in a register.
967 Variables and parameters that have been
968 optimized away do not appear in the
969 symbol table, returning the error
970 .IR "bad local variable"
974 Breakpoints should not be set on instructions scheduled
975 in delay slots. When a program stops on such a breakpoint,
976 it is usually impossible to continue its execution.
