17 is a general purpose debugging program.
18 It may be used to examine files and to provide
19 a controlled environment for the execution
24 is a file containing the text and initialized
25 data of an executable program.
28 is the memory image of an executing process. It is
29 usually accessed via the process id
32 .BI /proc/ pid /mem\f1.
35 contains the text, data, and saved registers and
42 supports accesses to instructions and data in the file;
45 An argument consisting entirely of digits is assumed
46 to be a process id; otherwise, it is the name of a
50 is given, the textfile map
51 is associated with it.
54 is given, the textfile map is
56 .BI /proc/ pid /text\f1.
59 is given, the memfile map is associated with
60 .BI /proc/ pid /mem\f1;
61 otherwise it is undefined and accesses to the
67 are read from the standard input and
68 responses are to the standard output.
72 Use the kernel stack of process
74 to debug the executing kernel process.
77 is not specified, file
78 .BI / $cputype /9 type
89 if they don't exist; open them for writing
93 Directory in which to look for relative path names in
100 Assume instructions are for the given CPU type
101 (any standard architecture name, such as
109 which cause disassembly to the manufacturer's syntax)
110 instead of using the magic number to select
115 commands have the following form:
124 is present then the current position, called `dot',
129 Most commands are repeated
132 dot advancing between repetitions.
140 Multiple commands on one line must be separated by
143 Expressions are evaluated as long
151 incremented by the current increment.
155 decremented by the current increment.
163 A number, in decimal radix by default.
170 (zero oh) force interpretation
171 in octal radix; the prefixes
175 force interpretation in
176 decimal radix; the prefixes
181 force interpretation in
189 all represent sixteen.
191 .IB integer . fraction
192 A single-precision floating point number.
197 value of a character.
199 may be used to escape a
205 which is a register name.
206 The register names are
215 of upper or lower case letters, underscores or
216 digits, not starting with a digit.
218 may be used to escape other characters.
221 is calculated from the symbol table
226 The address of the variable
238 is omitted the value is the address of the
239 most recently activated stack frame
249 The address of the instruction corresponding
250 to the source statement at the indicated
251 line number of the file. If the source line contains
252 no executable statement, the address of the
253 instruction associated with the nearest
254 executable source line is returned. Files
255 begin at line 1. If multiple files of the same
256 name are loaded, an expression of this form resolves
257 to the first file encountered in the symbol table.
260 The value of the expression
267 The contents of the location addressed
274 The contents of the location addressed by
289 is an offset into the segment named
294 .I "Dyadic\ operators"
296 and are less binding than monadic operators.
306 Integer multiplication.
319 rounded up to the next multiple of
324 Most commands have the following syntax:
327 Locations starting at
331 are printed according to the format
335 Locations starting at
339 are printed according to the format
345 itself is printed according to the format
350 consists of one or more characters that specify a style
352 Each format character may be preceded by a decimal integer
353 that is a repeat count for the format character.
354 If no format is given then the last format is used.
356 Most format letters fetch some data,
358 and advance (a local copy of) dot
359 by the number of bytes fetched.
360 The total number of bytes in a format becomes the
361 .IR current increment .
367 Print two-byte integer in octal.
370 Print four-byte integer in octal.
373 Print two-byte integer in signed octal.
376 Print four-byte integer in signed octal.
379 Print two-byte integer in decimal.
382 Print four-byte integer in decimal.
385 Print eight-byte integer in decimal.
388 Print eight-byte integer in unsigned decimal.
391 Print two-byte integer in hexadecimal.
394 Print four-byte integer in hexadecimal.
397 Print eight-byte integer in hexadecimal.
400 Print two-byte integer in unsigned decimal.
403 Print four-byte integer in unsigned decimal.
407 as a single-precision floating point number.
410 Print double-precision floating point.
413 Print the addressed byte in hexadecimal.
416 Print the addressed byte as an
421 Print the addressed byte as a character.
425 are represented normally; others
426 are printed in the form
430 Print the addressed characters, as a
432 string, until a zero byte
435 by the length of the string,
436 including the zero terminator.
440 the escape convention (see
447 the addressed two-byte integer (rune).
452 the addressed two-byte integers as runes
453 until a zero rune is reached.
455 by the length of the string,
456 including the zero terminator.
459 Print as machine instructions. Dot is
460 incremented by the size of the instruction.
465 above, but print the machine instructions in
466 an alternate form if possible:
470 reproduce the manufacturers' syntax.
473 Print the addressed machine instruction in a
474 machine-dependent hexadecimal form.
477 Print the value of dot
482 Print the value of dot
487 Print the function name, source file, and line number
488 corresponding to dot (textfile only). Dot is unaffected.
491 Print the addressed value in symbolic form.
492 Dot is advanced by the size of a machine address.
495 When preceded by an integer, tabs to the next
496 appropriate tab stop.
499 moves to the next 8-space tab stop.
508 Print the enclosed string.
514 Dot is decremented by the current increment.
518 Dot is incremented by 1.
522 Dot is decremented by 1.
527 Other commands include:
530 Update dot by the current increment.
531 Repeat the previous command with a
535 .RB [ ?/ ] l "\fI value mask\fR"
536 Words starting at dot
546 the match is for a two-byte integer;
549 If no match is found then dot
550 is unchanged; otherwise dot
551 is set to the matched location.
554 is omitted then ~0 is used.
556 .RB [ ?/ ] w "\fI value ...\fR"
565 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
571 are recorded. Valid segment names are
576 If less than three address expressions are given,
577 the remaining parameters are left unchanged.
578 If the list is terminated by
586 respectively) is used
587 for subsequent requests.
596 Dot is assigned to the variable or register named.
599 The rest of the line is passed to
604 Miscellaneous commands.
612 Read commands from the file
614 If this command is executed in a file, further commands
615 in the file are not seen.
618 is omitted, the current input stream is terminated.
621 is given, and is zero, the command is ignored.
626 except it can be used in a file of commands without
627 causing the file to be closed.
628 There is a (small) limit to the number of
630 files that can be open at once.
635 Append output to the file
637 which is created if it does not exist.
640 is omitted, output is returned to the terminal.
643 Print process id, the condition which caused stopping or termination,
644 the registers and the instruction addressed by
646 This is the default if
651 Print the general registers and
652 the instruction addressed by
660 but include miscellaneous processor control registers
661 and floating point registers.
664 Print floating-point register values as
665 single-precision floating point numbers.
668 Print floating-point register values as
669 double-precision floating point numbers.
672 Print all breakpoints
673 and their associated counts and commands. `B' produces the same results.
679 is given, it specifies the address of a pair of 32-bit
680 values containing the
684 of an active process. This allows selecting
685 among various contexts of a multi-threaded
689 is used, the names and (long) values of all
692 and static variables are printed for each active function.
695 is given, only the first
700 Attach to the running process whose pid
705 The names and values of all
706 external variables are printed.
709 Set the page width for output to
718 Print the address maps.
721 Simulate kernel memory management.
726 type used for disassembling instructions.
732 Available modifiers are:
738 an asynchronously running process to allow breakpointing.
739 Unnecessary for processes created under
747 The breakpoint is executed
753 is given it is executed at each
754 breakpoint and if it sets dot to zero
755 the breakpoint causes a stop.
768 program is entered at that point; otherwise
769 the standard entry point is used.
771 specifies how many breakpoints are to be
772 ignored before stopping.
773 Arguments to the subprocess may be supplied on the
774 same line as the command.
775 An argument starting with < or > causes the standard
776 input or output to be established for the command.
779 The subprocess is continued.
785 is sent the note that caused it to stop.
789 (If the stop was due to a breakpoint or single-step,
790 the corresponding note is elided before continuing.)
791 Breakpoint skipping is the same
799 the subprocess is single stepped for
801 machine instructions.
802 If a note is pending,
804 before the first instruction is executed.
805 If there is no current subprocess then
808 as a subprocess as for
810 In this case no note can be sent; the remainder of the line
811 is treated as arguments to the subprocess.
816 except the subprocess is single stepped for
818 lines of C source. In optimized code, the correspondence
819 between C source and the machine instructions is
823 The current subprocess, if any, is released by
825 and allowed to continue executing normally.
828 The current subprocess, if any, is terminated.
831 Display the pending notes for the process.
834 is specified, first delete
840 The location in a file or memory image associated with
841 an address is calculated from a map
842 associated with the file.
843 Each map contains one or more quadruples
844 .RI ( "t, b, e, f" ),
845 defining a segment named
852 mapping addresses in the range
856 to the part of the file
860 The memory model of a Plan 9 process assumes
861 that segments are disjoint. There
862 can be more than one segment of a given type (e.g., a process
863 may have more than one text segment) but segments
872 the location in the file
874 .IR address + f \- b .
877 the text and initialized data of a program
878 are mapped by segments called
882 Since a program file does not contain bss, stack or ublock data,
884 not mapped by the data segment.
885 The text segment is mapped similarly in
886 a normal (i.e., non-kernel)
888 However, the segment called
890 maps memory from the beginning of the program's data space to
891 the base of the ublock.
892 This region contains the program's static data, the bss, the
893 heap and the stack. A segment
896 maps the page containing its registers and process state.
898 Sometimes it is useful to define a map with a single segment
899 mapping the region from 0 to 0xFFFFFFFF; a map of this type
900 allows the entire file to be examined
901 without address translation.
903 Registers are saved at a machine-dependent offset in the ublock.
904 It is usually not necessary to know this offset; the
910 commands calculate it and display the register contents.
914 command dumps the currently active maps. The
918 commands modify the segment parameters in the
924 To set a breakpoint at the beginning of
926 in extant process 27:
935 To examine the Plan 9 kernel stack for process 27:
942 Similar, but using a kernel named
950 To set a breakpoint at the entry of function
952 when the local variable
959 parse:b *main.argc-1=X
962 This prints the value of
964 which as a side effect sets dot; when
966 is one the breakpoint will fire.
967 Beware that local variables may be stored in registers; see the
970 Debug process 127 on remote machine
974 % import kremvax /proc
993 Exit status is null, unless the last command failed or
994 returned non-null status.
996 Examining a local variable with
998 returns the contents of the memory allocated for the variable, but
999 with optimization (suppressed by the
1001 compiler flag) variables often reside in registers.
1002 Also, on some architectures, the first argument is always
1003 passed in a register.
1005 Variables and parameters that have been
1006 optimized away do not appear in the
1007 symbol table, returning the error
1008 .IR "bad local variable"
1012 Because of alignment incompatibilities, Motorola 68000
1013 series machines can not be debugged remotely from a
1014 processor of a different type.
1016 Breakpoints should not be set on instructions scheduled
1017 in delay slots. When a program stops on such a breakpoint,
1018 it is usually impossible to continue its execution.
projects / plan9front.git / blob