29 is a general purpose debugging program.
30 It may be used to examine files and to provide
31 a controlled environment for the execution
36 is a file containing the text and initialized
37 data of an executable program.
42 specifies the memory image of a process.
45 gives the id of an executing process to be accessed via
49 specifies the name of a core dump (see
51 on your system of choice) containing the
52 memory image of a terminated process.
53 This manual refers to the memory image specified by
66 supports accesses to instructions and data in the file;
69 An argument consisting entirely of digits is assumed
70 to be a process id; otherwise, it is the name of a
76 is given, the textfile map
77 is associated with it.
80 is given, the textfile map is
81 derived from the corresponding
83 if it can be determined
84 (this varies from system to system).
87 is given, the memfile map is associated with it;
88 otherwise the map is undefined and accesses to it
92 takes the same arguments as
94 It prints a stack trace (see the
96 command below) and then exits.
100 are read from the standard input and
101 responses are to the standard output.
106 suppress informational prints at startup.
113 for writing as well as reading.
116 Directory in which to look for relative path names in
123 Assume instructions are for the given CPU type
124 (possible names include
135 selects disassembly in the manufacturer's syntax, if
137 rather than the default Plan 9 syntax).
141 commands have the following form:
150 is present then the current position, called `dot',
155 Most commands are repeated
158 dot advancing between repetitions.
166 Multiple commands on one line must be separated by
169 Expressions are evaluated as long
177 incremented by the current increment.
181 decremented by the current increment.
189 A number, in decimal radix by default.
196 (zero oh) force interpretation
197 in octal radix; the prefixes
201 force interpretation in
202 decimal radix; the prefixes
207 force interpretation in
215 all represent sixteen.
217 .IB integer . fraction
218 A single-precision floating point number.
223 value of a character.
225 may be used to escape a
231 which is a register name.
232 The register names are
241 of upper or lower case letters, underscores or
242 digits, not starting with a digit.
244 may be used to escape other characters.
247 is calculated from the symbol table
252 The address of the variable
264 is omitted the value is the address of the
265 most recently activated stack frame
275 The address of the instruction corresponding
276 to the source statement at the indicated
277 line number of the file. If the source line contains
278 no executable statement, the address of the
279 instruction associated with the nearest
280 executable source line is returned. Files
281 begin at line 1. If multiple files of the same
282 name are loaded, an expression of this form resolves
283 to the first file encountered in the symbol table.
286 The value of the expression
293 The contents of the location addressed
300 The contents of the location addressed by
315 is an offset into the segment named
320 .I "Dyadic\ operators"
322 and are less binding than monadic operators.
332 Integer multiplication.
345 rounded up to the next multiple of
350 Most commands have the following syntax:
353 Locations starting at
357 are printed according to the format
361 Locations starting at
365 are printed according to the format
371 itself is printed according to the format
376 consists of one or more characters that specify a style
378 Each format character may be preceded by a decimal integer
379 that is a repeat count for the format character.
380 If no format is given then the last format is used.
382 Most format letters fetch some data,
384 and advance (a local copy of) dot
385 by the number of bytes fetched.
386 The total number of bytes in a format becomes the
387 .IR current increment .
393 Print two-byte integer in octal.
396 Print four-byte integer in octal.
399 Print two-byte integer in signed octal.
402 Print four-byte integer in signed octal.
405 Print two-byte integer in decimal.
408 Print four-byte integer in decimal.
411 Print eight-byte integer in decimal.
414 Print eight-byte integer in unsigned decimal.
417 Print two-byte integer in hexadecimal.
420 Print four-byte integer in hexadecimal.
423 Print eight-byte integer in hexadecimal.
426 Print two-byte integer in unsigned decimal.
429 Print four-byte integer in unsigned decimal.
433 as a single-precision floating point number.
436 Print double-precision floating point.
439 Print the addressed byte in hexadecimal.
442 Print the addressed byte as an
447 Print the addressed byte as a character.
451 are represented normally; others
452 are printed in the form
456 Print the addressed characters, as a
458 string, until a zero byte
461 by the length of the string,
462 including the zero terminator.
466 the escape convention (see
473 the addressed two-byte integer (rune).
478 the addressed two-byte integers as runes
479 until a zero rune is reached.
481 by the length of the string,
482 including the zero terminator.
485 Print as machine instructions. Dot is
486 incremented by the size of the instruction.
491 above, but print the machine instructions in
492 an alternate form if possible.
495 Print the addressed machine instruction in a
496 machine-dependent hexadecimal form.
499 Print the value of dot
504 Print the value of dot
509 Print the function name, source file, and line number
510 corresponding to dot (textfile only). Dot is unaffected.
513 Print the addressed value in symbolic form.
514 Dot is advanced by the size of a machine address.
517 When preceded by an integer, tabs to the next
518 appropriate tab stop.
521 moves to the next 8-space tab stop.
530 Print the enclosed string.
536 Dot is decremented by the current increment.
540 Dot is incremented by 1.
544 Dot is decremented by 1.
549 Other commands include:
552 Update dot by the current increment.
553 Repeat the previous command with a
557 .RB [ ?/ ] l "\fI value mask\fR"
558 Words starting at dot
568 the match is for a two-byte integer;
571 If no match is found then dot
572 is unchanged; otherwise dot
573 is set to the matched location.
576 is omitted then ~0 is used.
578 .RB [ ?/ ] w "\fI value ...\fR"
587 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
593 are recorded. Valid segment names are
598 If less than three address expressions are given,
599 the remaining parameters are left unchanged.
600 If the list is terminated by
608 respectively) is used
609 for subsequent requests.
618 Dot is assigned to the variable or register named.
621 The rest of the line is passed to
626 Miscellaneous commands.
634 Read commands from the file
636 If this command is executed in a file, further commands
637 in the file are not seen.
640 is omitted, the current input stream is terminated.
643 is given, and is zero, the command is ignored.
648 except it can be used in a file of commands without
649 causing the file to be closed.
650 There is a (small) limit to the number of
652 files that can be open at once.
657 Append output to the file
659 which is created if it does not exist.
662 is omitted, output is returned to the terminal.
665 Print process id, the condition which caused stopping or termination,
666 the registers and the instruction addressed by
668 This is the default if
673 Print the general registers and
674 the instruction addressed by
682 but include miscellaneous processor control registers
683 and floating point registers.
686 Print floating-point register values as
687 single-precision floating point numbers.
690 Print floating-point register values as
691 double-precision floating point numbers.
694 Print all breakpoints
695 and their associated counts and commands. `B' produces the same results.
701 is given, it specifies the address of a pair of 32-bit
702 values containing the
706 of an active process. This allows selecting
707 among various contexts of a multi-threaded
711 is used, the names and (long) values of all
714 and static variables are printed for each active function.
717 is given, only the first
722 Attach to the running process whose pid
727 The names and values of all
728 external variables are printed.
731 Set the page width for output to
740 Print the address maps.
743 Simulate kernel memory management.
748 type used for disassembling instructions.
754 Available modifiers are:
760 an asynchronously running process to allow breakpointing.
761 Unnecessary for processes created under
769 The breakpoint is executed
775 is given it is executed at each
776 breakpoint and if it sets dot to zero
777 the breakpoint causes a stop.
790 program is entered at that point; otherwise
791 the standard entry point is used.
793 specifies how many breakpoints are to be
794 ignored before stopping.
795 Arguments to the subprocess may be supplied on the
796 same line as the command.
797 An argument starting with < or > causes the standard
798 input or output to be established for the command.
801 The subprocess is continued.
807 is sent the note that caused it to stop.
811 (If the stop was due to a breakpoint or single-step,
812 the corresponding note is elided before continuing.)
813 Breakpoint skipping is the same
821 the subprocess is single stepped for
823 machine instructions.
824 If a note is pending,
826 before the first instruction is executed.
827 If there is no current subprocess then
830 as a subprocess as for
832 In this case no note can be sent; the remainder of the line
833 is treated as arguments to the subprocess.
838 except the subprocess is single stepped for
840 lines of C source. In optimized code, the correspondence
841 between C source and the machine instructions is
845 The current subprocess, if any, is released by
847 and allowed to continue executing normally.
850 The current subprocess, if any, is terminated.
853 Display the pending notes for the process.
856 is specified, first delete
862 The location in a file or memory image associated with
863 an address is calculated from a map
864 associated with the file.
865 Each map contains one or more quadruples
866 .RI ( "t, f, b, e, o" ),
867 defining a segment named
876 mapping addresses in the range
880 to the part of the file
884 If segments overlap, later segments obscure earlier ones.
889 by finding the last segment in the list
892 the location in the file
894 .IR address + f \- b .
897 the text and initialized data of a program
898 are mapped by segments called
903 Since a program file does not contain stack data,
906 The text segment is mapped similarly in
907 a normal (i.e., non-kernel)
909 However, one or more segments called
911 provide access to process memory.
912 This region contains the program's static data, the bss, the
915 Sometimes it is useful to define a map with a single segment
916 mapping the region from 0 to 0xFFFFFFFF; a map of this type
917 allows an entire file to be examined
918 without address translation.
922 command dumps the currently active maps. The
926 commands modify the segment parameters in the
932 To set a breakpoint at the beginning of
934 in extant process 27:
943 To set a breakpoint at the entry of function
945 when the local variable
952 parse:b *main.argc-1=X
955 This prints the value of
957 which as a side effect sets dot; when
959 is one the breakpoint will fire.
960 Beware that local variables may be stored in registers; see the
968 Exit status is 0, unless the last command failed or
969 returned non-zero status.
971 Examining a local variable with
973 returns the contents of the memory allocated for the variable, but
974 with optimization, variables often reside in registers.
975 Also, on some architectures, the first argument is always
976 passed in a register.
978 Variables and parameters that have been
979 optimized away do not appear in the
980 symbol table, returning the error
981 .IR "bad local variable"
985 Breakpoints should not be set on instructions scheduled
986 in delay slots. When a program stops on such a breakpoint,
987 it is usually impossible to continue its execution.
