31 is a general purpose debugging program.
32 It may be used to examine files and to provide
33 a controlled environment for the execution
38 is a file containing the text and initialized
39 data of an executable program.
44 specifies the memory image of a process.
47 gives the id of an executing process to be accessed via
51 specifies the name of a core dump (see
53 on your system of choice) containing the
54 memory image of a terminated process.
55 This manual refers to the memory image specified by
68 supports accesses to instructions and data in the file;
71 An argument consisting entirely of digits is assumed
72 to be a process id; otherwise, it is the name of a
78 is given, the textfile map
79 is associated with it.
82 is given, the textfile map is
83 derived from the corresponding
85 if it can be determined
86 (this varies from system to system).
89 is given, the memfile map is associated with it;
90 otherwise the map is undefined and accesses to it
94 takes the same arguments as
96 It prints a stack trace (see the
98 command below) and then exits.
99 If the first argument is a process name,
102 prints the stack trace of every running process
105 owned by the current user.
109 are read from the standard input and
110 responses are to the standard output.
115 suppress informational prints at startup.
122 for writing as well as reading.
125 Directory in which to look for relative path names in
132 Assume instructions are for the given CPU type
133 (possible names include
144 selects disassembly in the manufacturer's syntax, if
146 rather than the default Plan 9 syntax).
150 commands have the following form:
159 is present then the current position, called `dot',
164 Most commands are repeated
167 dot advancing between repetitions.
175 Multiple commands on one line must be separated by
178 Expressions are evaluated as long
186 incremented by the current increment.
190 decremented by the current increment.
198 A number, in decimal radix by default.
205 (zero oh) force interpretation
206 in octal radix; the prefixes
210 force interpretation in
211 decimal radix; the prefixes
216 force interpretation in
224 all represent sixteen.
226 .IB integer . fraction
227 A single-precision floating point number.
232 value of a character.
234 may be used to escape a
240 which is a register name.
241 The register names are
250 of upper or lower case letters, underscores or
251 digits, not starting with a digit.
253 may be used to escape other characters.
256 is calculated from the symbol table
261 The address of the variable
273 is omitted the value is the address of the
274 most recently activated stack frame
284 The address of the instruction corresponding
285 to the source statement at the indicated
286 line number of the file. If the source line contains
287 no executable statement, the address of the
288 instruction associated with the nearest
289 executable source line is returned. Files
290 begin at line 1. If multiple files of the same
291 name are loaded, an expression of this form resolves
292 to the first file encountered in the symbol table.
295 The value of the expression
302 The contents of the location addressed
309 The contents of the location addressed by
324 is an offset into the segment named
329 .I "Dyadic\ operators"
331 and are less binding than monadic operators.
341 Integer multiplication.
354 rounded up to the next multiple of
359 Most commands have the following syntax:
362 Locations starting at
366 are printed according to the format
370 Locations starting at
374 are printed according to the format
380 itself is printed according to the format
385 consists of one or more characters that specify a style
387 Each format character may be preceded by a decimal integer
388 that is a repeat count for the format character.
389 If no format is given then the last format is used.
391 Most format letters fetch some data,
393 and advance (a local copy of) dot
394 by the number of bytes fetched.
395 The total number of bytes in a format becomes the
396 .IR current increment .
402 Print two-byte integer in octal.
405 Print four-byte integer in octal.
408 Print two-byte integer in signed octal.
411 Print four-byte integer in signed octal.
414 Print two-byte integer in decimal.
417 Print four-byte integer in decimal.
420 Print eight-byte integer in decimal.
423 Print eight-byte integer in unsigned decimal.
426 Print two-byte integer in hexadecimal.
429 Print four-byte integer in hexadecimal.
432 Print eight-byte integer in hexadecimal.
435 Print two-byte integer in unsigned decimal.
438 Print four-byte integer in unsigned decimal.
442 as a single-precision floating point number.
445 Print double-precision floating point.
448 Print the addressed byte in hexadecimal.
451 Print the addressed byte as an
456 Print the addressed byte as a character.
460 are represented normally; others
461 are printed in the form
465 Print the addressed characters, as a
467 string, until a zero byte
470 by the length of the string,
471 including the zero terminator.
475 the escape convention (see
482 the addressed two-byte integer (rune).
487 the addressed two-byte integers as runes
488 until a zero rune is reached.
490 by the length of the string,
491 including the zero terminator.
494 Print as machine instructions. Dot is
495 incremented by the size of the instruction.
500 above, but print the machine instructions in
501 an alternate form if possible.
504 Print the addressed machine instruction in a
505 machine-dependent hexadecimal form.
508 Print the value of dot
513 Print the value of dot
518 Print the function name, source file, and line number
519 corresponding to dot (textfile only). Dot is unaffected.
522 Print the addressed value in symbolic form.
523 Dot is advanced by the size of a machine address.
526 When preceded by an integer, tabs to the next
527 appropriate tab stop.
530 moves to the next 8-space tab stop.
539 Print the enclosed string.
545 Dot is decremented by the current increment.
549 Dot is incremented by 1.
553 Dot is decremented by 1.
558 Other commands include:
561 Update dot by the current increment.
562 Repeat the previous command with a
566 .RB [ ?/ ] l "\fI value mask\fR"
567 Words starting at dot
577 the match is for a two-byte integer;
580 If no match is found then dot
581 is unchanged; otherwise dot
582 is set to the matched location.
585 is omitted then ~0 is used.
587 .RB [ ?/ ] w "\fI value ...\fR"
596 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
602 are recorded. Valid segment names are
607 If less than three address expressions are given,
608 the remaining parameters are left unchanged.
609 If the list is terminated by
617 respectively) is used
618 for subsequent requests.
627 Dot is assigned to the variable or register named.
630 The rest of the line is passed to
635 Miscellaneous commands.
643 Read commands from the file
645 If this command is executed in a file, further commands
646 in the file are not seen.
649 is omitted, the current input stream is terminated.
652 is given, and is zero, the command is ignored.
657 except it can be used in a file of commands without
658 causing the file to be closed.
659 There is a (small) limit to the number of
661 files that can be open at once.
666 Append output to the file
668 which is created if it does not exist.
671 is omitted, output is returned to the terminal.
674 Print process id, the condition which caused stopping or termination,
675 the registers and the instruction addressed by
677 This is the default if
682 Print the general registers and
683 the instruction addressed by
691 but include miscellaneous processor control registers
692 and floating point registers.
695 Print floating-point register values as
696 single-precision floating point numbers.
699 Print floating-point register values as
700 double-precision floating point numbers.
703 Print all breakpoints
704 and their associated counts and commands. `B' produces the same results.
710 is given, it specifies the address of a pair of 32-bit
711 values containing the
715 of an active process. This allows selecting
716 among various contexts of a multi-threaded
720 is used, the names and (long) values of all
723 and static variables are printed for each active function.
726 is given, only the first
731 Attach to the running process whose pid
736 The names and values of all
737 external variables are printed.
740 Set the page width for output to
749 Print the address maps.
752 Simulate kernel memory management.
757 type used for disassembling instructions.
763 Available modifiers are:
769 an asynchronously running process to allow breakpointing.
770 Unnecessary for processes created under
778 The breakpoint is executed
784 is given it is executed at each
785 breakpoint and if it sets dot to zero
786 the breakpoint causes a stop.
799 program is entered at that point; otherwise
800 the standard entry point is used.
802 specifies how many breakpoints are to be
803 ignored before stopping.
804 Arguments to the subprocess may be supplied on the
805 same line as the command.
806 An argument starting with < or > causes the standard
807 input or output to be established for the command.
810 The subprocess is continued.
816 is sent the note that caused it to stop.
820 (If the stop was due to a breakpoint or single-step,
821 the corresponding note is elided before continuing.)
822 Breakpoint skipping is the same
830 the subprocess is single stepped for
832 machine instructions.
833 If a note is pending,
835 before the first instruction is executed.
836 If there is no current subprocess then
839 as a subprocess as for
841 In this case no note can be sent; the remainder of the line
842 is treated as arguments to the subprocess.
847 except the subprocess is single stepped for
849 lines of C source. In optimized code, the correspondence
850 between C source and the machine instructions is
854 The current subprocess, if any, is released by
856 and allowed to continue executing normally.
859 The current subprocess, if any, is terminated.
862 Display the pending notes for the process.
865 is specified, first delete
871 The location in a file or memory image associated with
872 an address is calculated from a map
873 associated with the file.
874 Each map contains one or more quadruples
875 .RI ( "t, f, b, e, o" ),
876 defining a segment named
885 mapping addresses in the range
889 to the part of the file
893 If segments overlap, later segments obscure earlier ones.
898 by finding the last segment in the list
901 the location in the file
903 .IR address + f \- b .
906 the text and initialized data of a program
907 are mapped by segments called
912 Since a program file does not contain stack data,
915 The text segment is mapped similarly in
916 a normal (i.e., non-kernel)
918 However, one or more segments called
920 provide access to process memory.
921 This region contains the program's static data, the bss, the
924 Sometimes it is useful to define a map with a single segment
925 mapping the region from 0 to 0xFFFFFFFF; a map of this type
926 allows an entire file to be examined
927 without address translation.
931 command dumps the currently active maps. The
935 commands modify the segment parameters in the
941 To set a breakpoint at the beginning of
943 in extant process 27:
952 To set a breakpoint at the entry of function
954 when the local variable
961 parse:b *main.argc-1=X
964 This prints the value of
966 which as a side effect sets dot; when
968 is one the breakpoint will fire.
969 Beware that local variables may be stored in registers; see the
977 Exit status is 0, unless the last command failed or
978 returned non-zero status.
980 Examining a local variable with
982 returns the contents of the memory allocated for the variable, but
983 with optimization, variables often reside in registers.
984 Also, on some architectures, the first argument is always
985 passed in a register.
987 Variables and parameters that have been
988 optimized away do not appear in the
989 symbol table, returning the error
990 .IR "bad local variable"
994 Breakpoints should not be set on instructions scheduled
995 in delay slots. When a program stops on such a breakpoint,
996 it is usually impossible to continue its execution.
