tdb.1 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tdb.1 (17167B)
---
1 .TH DB 1
2 .SH NAME
3 db, stack \- debugger
4 .SH SYNOPSIS
5 .B db
6 [
7 .I option ...
8 ]
9 [
10 .I pid
11 |
12 .I corefile
13 ]
14 [
15 .I textfile
16 ]
17 .PP
18 .B stack
19 [
20 .I pid
21 |
22 .I corefile
23 |
24 .I name
25 ]
26 [
27 .I textfile
28 ]
29 .SH DESCRIPTION
30 .I Db
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
34 of programs.
35 .PP
36 A
37 .I textfile
38 is a file containing the text and initialized
39 data of an executable program.
40 A
41 .I pid
42 or
43 .I corefile
44 specifies the memory image of a process.
45 A
46 .I pid
47 gives the id of an executing process to be accessed via
48 .MR ptrace (2) .
49 A
50 .I corefile
51 specifies the name of a core dump (see
52 .MR core (5)
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
56 .I pid
57 or
58 .I corefile
59 as a
60 .IR memfile .
61 .PP
62 A
63 .I map
64 associated with each
65 .I textfile
66 or
67 .I memfile
68 supports accesses to instructions and data in the file;
69 see `Addresses'.
70 .PP
71 An argument consisting entirely of digits is assumed
72 to be a process id; otherwise, it is the name of a
73 .I textfile
74 or
75 .IR corefile .
76 When a
77 .I textfile
78 is given, the textfile map
79 is associated with it.
80 If only a
81 .I memfile
82 is given, the textfile map is
83 derived from the corresponding
84 .IR textfile ,
85 if it can be determined
86 (this varies from system to system).
87 When a
88 .I memfile
89 is given, the memfile map is associated with it;
90 otherwise the map is undefined and accesses to it
91 are not permitted.
92 .PP
93 .I Stack
94 takes the same arguments as
95 .IR db .
96 It prints a stack trace (see the
97 .B $c
98 command below) and then exits.
99 If the first argument is a process name,
100 then
101 .I stack
102 prints the stack trace of every running process
103 with the given name
104 that is
105 owned by the current user.
106 .PP
107 Commands to
108 .I db
109 are read from the standard input and
110 responses are to the standard output.
111 The options are
112 .TP
113 .B -q
114 Quiet mode:
115 suppress informational prints at startup.
116 .TP
117 .B -w
118 Open
119 .I textfile
120 and
121 .I memfile
122 for writing as well as reading.
123 .TP
124 .BI -I path
125 Directory in which to look for relative path names in
126 .B $<
127 and
128 .B $<<
129 commands.
130 .TP
131 .BI -m machine
132 Assume instructions are for the given CPU type
133 (possible names include
134 .B 386
135 and
136 .BR powerpc ;
137 adding
138 the suffix
139 .B -co
140 as in
141 .B 386-co
142 and
143 .B powerpc-co
144 selects disassembly in the manufacturer's syntax, if
145 available,
146 rather than the default Plan 9 syntax).
147 .PP
148 Most
149 .I db
150 commands have the following form:
151 .IP
152 .RI [ address ]
153 .RB [ ,
154 .IR count ]
155 .RI [ command ]
156 .PP
157 If
158 .I address
159 is present then the current position, called `dot',
160 is set to
161 .IR address .
162 Initially dot
163 is set to 0.
164 Most commands are repeated
165 .I count
166 times with
167 dot advancing between repetitions.
168 The default
169 .I count
170 is 1.
171 .I Address
172 and
173 .I count
174 are expressions.
175 Multiple commands on one line must be separated by
176 .LR ; .
177 .SS Expressions
178 Expressions are evaluated as long
179 .IR ints .
180 .TP 7.2n
181 .B .
182 The value of dot.
183 .TP 7.2n
184 .B +
185 The value of dot
186 incremented by the current increment.
187 .TP 7.2n
188 .B ^
189 The value of dot
190 decremented by the current increment.
191 .TP 7.2n
192 .B \&"
193 The last
194 .I address
195 typed.
196 .TP 7.2n
197 .I integer
198 A number, in decimal radix by default.
199 The prefixes
200 .L 0
201 and
202 .L 0o
203 and
204 .L 0O
205 (zero oh) force interpretation
206 in octal radix; the prefixes
207 .L 0t
208 and
209 .L 0T
210 force interpretation in
211 decimal radix; the prefixes
212 .LR 0x ,
213 .LR 0X ,
214 and
215 .L #
216 force interpretation in
217 hexadecimal radix.
218 Thus
219 .LR 020 ,
220 .LR 0o20 ,
221 .LR 0t16 ,
222 and
223 .L #10
224 all represent sixteen.
225 .TP 7.2n
226 .IB integer . fraction
227 A single-precision floating point number.
228 .TP 7.2n
229 .BI \' c\| \'
230 The
231 16-bit
232 value of a character.
233 .L \e
234 may be used to escape a
235 .LR \' .
236 .TP 7.2n
237 .BI < name
238 The value of
239 .IR name ,
240 which is a register name.
241 The register names are
242 those printed by the
243 .B $r
244 command.
245 .TP 7.2n
246 .I symbol
247 A
248 .I symbol
249 is a sequence
250 of upper or lower case letters, underscores or
251 digits, not starting with a digit.
252 .L \e
253 may be used to escape other characters.
254 The location of the
255 .I symbol
256 is calculated from the symbol table
257 in
258 .IR textfile .
259 .TP 7.2n
260 .IB routine . name
261 The address of the variable
262 .I name
263 in the specified
264 C routine.
265 Both
266 .I routine
267 and
268 .I name
269 are
270 .IR symbols .
271 If
272 .I name
273 is omitted the value is the address of the
274 most recently activated stack frame
275 corresponding to
276 .IR routine ;
277 if
278 .I routine
279 is omitted,
280 the active procedure
281 is assumed.
282 .TP 7.2n
283 .IB file : integer
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.
293 .TP 7.2n
294 .BI ( exp )
295 The value of the expression
296 .IR exp .
297 .LP
298 .I Monadic operators
299 .RS
300 .TP 7.2n
301 .BI * exp
302 The contents of the location addressed
303 by
304 .I exp
305 in
306 .IR memfile .
307 .TP 7.2n
308 .BI @ exp
309 The contents of the location addressed by
310 .I exp
311 in
312 .IR textfile .
313 .TP 7.2n
314 .BI - exp
315 Integer negation.
316 .TP 7.2n
317 .BI ~ exp
318 Bitwise complement.
319 .TP 7.2n
320 .BI % exp
321 When used as an
322 .IR address ,
323 .I exp
324 is an offset into the segment named
325 .IR ublock ;
326 see `Addresses'.
327 .RE
328 .LP
329 .I "Dyadic\ operators"
330 are left-associative
331 and are less binding than monadic operators.
332 .RS
333 .TP 7.2n
334 .IB e1 + e2
335 Integer addition.
336 .TP 7.2n
337 .IB e1 - e2
338 Integer subtraction.
339 .TP 7.2n
340 .IB e1 * e2
341 Integer multiplication.
342 .TP 7.2n
343 .IB e1 % e2
344 Integer division.
345 .TP 7.2n
346 .IB e1 & e2
347 Bitwise conjunction.
348 .TP 7.2n
349 .IB e1 | e2
350 Bitwise disjunction.
351 .TP 7.2n
352 .IB e1 # e2
353 .I E1
354 rounded up to the next multiple of
355 .IR e2 .
356 .RE
357 .DT
358 .SS Commands
359 Most commands have the following syntax:
360 .TP .5i
361 .BI ? f
362 Locations starting at
363 .I address
364 in
365 .I textfile
366 are printed according to the format
367 .IR f .
368 .TP
369 .BI / f
370 Locations starting at
371 .I address
372 in
373 .I memfile
374 are printed according to the format
375 .IR f .
376 .TP
377 .BI = f
378 The value of
379 .I address
380 itself is printed according to the format
381 .IR f .
382 .PP
383 A
384 .I format
385 consists of one or more characters that specify a style
386 of printing.
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.
390 .PP
391 Most format letters fetch some data,
392 print it,
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 .
397 .ta 2.5n .5i
398 .RS
399 .TP
400 .PD 0
401 .B o
402 Print two-byte integer in octal.
403 .TP
404 .B O
405 Print four-byte integer in octal.
406 .TP
407 .B q
408 Print two-byte integer in signed octal.
409 .TP
410 .B Q
411 Print four-byte integer in signed octal.
412 .TP
413 .B d
414 Print two-byte integer in decimal.
415 .TP
416 .B D
417 Print four-byte integer in decimal.
418 .TP
419 .B V
420 Print eight-byte integer in decimal.
421 .TP
422 .B Z
423 Print eight-byte integer in unsigned decimal.
424 .TP
425 .B x
426 Print two-byte integer in hexadecimal.
427 .TP
428 .B X
429 Print four-byte integer in hexadecimal.
430 .TP
431 .B Y
432 Print eight-byte integer in hexadecimal.
433 .TP
434 .B u
435 Print two-byte integer in unsigned decimal.
436 .TP
437 .B U
438 Print four-byte integer in unsigned decimal.
439 .TP
440 .B f
441 Print
442 as a single-precision floating point number.
443 .TP
444 .B F
445 Print double-precision floating point.
446 .TP
447 .B b
448 Print the addressed byte in hexadecimal.
449 .TP
450 .B c
451 Print the addressed byte as an
452 .SM ASCII
453 character.
454 .TP
455 .B C
456 Print the addressed byte as a character.
457 Printable
458 .SM ASCII
459 characters
460 are represented normally; others
461 are printed in the form
462 .BR \exnn .
463 .TP
464 .B s
465 Print the addressed characters, as a
466 .SM UTF
467 string, until a zero byte
468 is reached.
469 Advance dot
470 by the length of the string,
471 including the zero terminator.
472 .TP
473 .B S
474 Print a string using
475 the escape convention (see
476 .B C
477 above).
478 .TP
479 .B r
480 Print as
481 .SM UTF
482 the addressed two-byte integer (rune).
483 .TP
484 .B R
485 Print as
486 .SM UTF
487 the addressed two-byte integers as runes
488 until a zero rune is reached.
489 Advance dot
490 by the length of the string,
491 including the zero terminator.
492 .TP
493 .B i
494 Print as machine instructions. Dot is
495 incremented by the size of the instruction.
496 .TP
497 .B I
498 As
499 .B i
500 above, but print the machine instructions in
501 an alternate form if possible.
502 .TP
503 .B M
504 Print the addressed machine instruction in a
505 machine-dependent hexadecimal form.
506 .TP
507 .B a
508 Print the value of dot
509 in symbolic form.
510 Dot is unaffected.
511 .TP
512 .B A
513 Print the value of dot
514 in hexadecimal.
515 Dot is unaffected.
516 .TP
517 .B z
518 Print the function name, source file, and line number
519 corresponding to dot (textfile only). Dot is unaffected.
520 .TP
521 .B p
522 Print the addressed value in symbolic form.
523 Dot is advanced by the size of a machine address.
524 .TP
525 .B t
526 When preceded by an integer, tabs to the next
527 appropriate tab stop.
528 For example,
529 .B 8t
530 moves to the next 8-space tab stop.
531 Dot is unaffected.
532 .TP
533 .B n
534 Print a newline.
535 Dot is unaffected.
536 .tr '"
537 .TP
538 .BR ' ... '
539 Print the enclosed string.
540 Dot is unaffected.
541 .br
542 .tr ''
543 .TP
544 .B ^
545 Dot is decremented by the current increment.
546 Nothing is printed.
547 .TP
548 .B +
549 Dot is incremented by 1.
550 Nothing is printed.
551 .TP
552 .B -
553 Dot is decremented by 1.
554 Nothing is printed.
555 .RE
556 .PD
557 .LP
558 Other commands include:
559 .TP
560 newline
561 Update dot by the current increment.
562 Repeat the previous command with a
563 .I count
564 of 1.
565 .TP
566 .RB [ ?/ ] l "\fI value mask\fR"
567 Words starting at dot
568 are masked with
569 .I mask
570 and compared with
571 .I value
572 until
573 a match is found.
574 If
575 .B l
576 is used,
577 the match is for a two-byte integer;
578 .B L
579 matches four bytes.
580 If no match is found then dot
581 is unchanged; otherwise dot
582 is set to the matched location.
583 If
584 .I mask
585 is omitted then ~0 is used.
586 .TP
587 .RB [ ?/ ] w "\fI value ...\fR"
588 Write the two-byte
589 .I value
590 into the addressed
591 location.
592 If the command is
593 .BR W ,
594 write four bytes.
595 .TP
596 .RB [ ?/ ] "m\fI s b e f \fP" [ ?\fR]
597 .br
598 New values for
599 .RI ( b,\ e,\ f )
600 in the segment named
601 .I s
602 are recorded. Valid segment names are
603 .IR text ,
604 .IR data ,
605 or
606 .IR ublock .
607 If less than three address expressions are given,
608 the remaining parameters are left unchanged.
609 If the list is terminated by
610 .L ?
611 or
612 .L /
613 then the file
614 .RI ( textfile
615 or
616 .I memfile
617 respectively) is used
618 for subsequent requests.
619 For example,
620 .L /m?
621 causes
622 .L /
623 to refer to
624 .IR textfile .
625 .TP
626 .BI > name
627 Dot is assigned to the variable or register named.
628 .TP
629 .B !
630 The rest of the line is passed to
631 .MR rc (1)
632 for execution.
633 .TP
634 .BI $ modifier
635 Miscellaneous commands.
636 The available
637 .I modifiers
638 are:
639 .RS
640 .TP
641 .PD 0
642 .BI < f
643 Read commands from the file
644 .IR f .
645 If this command is executed in a file, further commands
646 in the file are not seen.
647 If
648 .I f
649 is omitted, the current input stream is terminated.
650 If a
651 .I count
652 is given, and is zero, the command is ignored.
653 .TP
654 .BI << f
655 Similar to
656 .B <
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
660 .B <<
661 files that can be open at once.
662 .br
663 .ns
664 .TP
665 .BI > f
666 Append output to the file
667 .IR f ,
668 which is created if it does not exist.
669 If
670 .I f
671 is omitted, output is returned to the terminal.
672 .TP
673 .B ?
674 Print process id, the condition which caused stopping or termination,
675 the registers and the instruction addressed by
676 .BR pc .
677 This is the default if
678 .I modifier
679 is omitted.
680 .TP
681 .B r
682 Print the general registers and
683 the instruction addressed by
684 .BR pc .
685 Dot is set to
686 .BR pc .
687 .TP
688 .B R
689 Like
690 .BR $r ,
691 but include miscellaneous processor control registers
692 and floating point registers.
693 .TP
694 .B f
695 Print floating-point register values as
696 single-precision floating point numbers.
697 .TP
698 .B F
699 Print floating-point register values as
700 double-precision floating point numbers.
701 .TP
702 .B b
703 Print all breakpoints
704 and their associated counts and commands. `B' produces the same results.
705 .TP
706 .B c
707 Stack backtrace.
708 If
709 .I address
710 is given, it specifies the address of a pair of 32-bit
711 values containing the
712 .B sp
713 and
714 .B pc
715 of an active process. This allows selecting
716 among various contexts of a multi-threaded
717 process.
718 If
719 .B C
720 is used, the names and (long) values of all
721 parameters,
722 automatic
723 and static variables are printed for each active function.
724 If
725 .I count
726 is given, only the first
727 .I count
728 frames are printed.
729 .TP
730 .B a
731 Attach to the running process whose pid
732 is contained in
733 .IR address .
734 .TP
735 .B e
736 The names and values of all
737 external variables are printed.
738 .TP
739 .B w
740 Set the page width for output to
741 .I address
742 (default 80).
743 .TP
744 .B q
745 Exit from
746 .IR db .
747 .TP
748 .B m
749 Print the address maps.
750 .TP
751 .B k
752 Simulate kernel memory management.
753 .TP
754 .BI M machine
755 Set the
756 .I machine
757 type used for disassembling instructions.
758 .PD
759 .RE
760 .TP
761 .BI : modifier
762 Manage a subprocess.
763 Available modifiers are:
764 .RS
765 .TP
766 .PD 0
767 .BI h
768 Halt
769 an asynchronously running process to allow breakpointing.
770 Unnecessary for processes created under
771 .IR db ,
772 e.g. by
773 .BR :r .
774 .TP
775 .BI b c
776 Set breakpoint at
777 .IR address .
778 The breakpoint is executed
779 .IR count \-1
780 times before
781 causing a stop.
782 Also, if a command
783 .I c
784 is given it is executed at each
785 breakpoint and if it sets dot to zero
786 the breakpoint causes a stop.
787 .TP
788 .B d
789 Delete breakpoint at
790 .IR address .
791 .TP
792 .B r
793 Run
794 .I textfile
795 as a subprocess.
796 If
797 .I address
798 is given the
799 program is entered at that point; otherwise
800 the standard entry point is used.
801 .I Count
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.
808 .TP
809 .BI c s
810 The subprocess is continued.
811 If
812 .I s
813 is omitted
814 or nonzero,
815 the subprocess
816 is sent the note that caused it to stop.
817 If 0
818 is specified,
819 no note is sent.
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
823 as for
824 .BR r .
825 .TP
826 .BI s s
827 As for
828 .B c
829 except that
830 the subprocess is single stepped for
831 .I count
832 machine instructions.
833 If a note is pending,
834 it is received
835 before the first instruction is executed.
836 If there is no current subprocess then
837 .I textfile
838 is run
839 as a subprocess as for
840 .BR r .
841 In this case no note can be sent; the remainder of the line
842 is treated as arguments to the subprocess.
843 .TP
844 .BI S s
845 Identical to
846 .B s
847 except the subprocess is single stepped for
848 .I count
849 lines of C source. In optimized code, the correspondence
850 between C source and the machine instructions is
851 approximate at best.
852 .TP
853 .BI x
854 The current subprocess, if any, is released by
855 .I db
856 and allowed to continue executing normally.
857 .TP
858 .B k
859 The current subprocess, if any, is terminated.
860 .TP
861 .BI n c
862 Display the pending notes for the process.
863 If
864 .I c
865 is specified, first delete
866 .I c'th
867 pending note.
868 .PD
869 .RE
870 .SS Addresses
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
877 .I t
878 (usually,
879 .IR text ,
880 .IR data ,
881 or
882 .IR core )
883 in file
884 .I f
885 mapping addresses in the range
886 .I b
887 through
888 .IR e
889 to the part of the file
890 beginning at
891 offset
892 .IR o .
893 If segments overlap, later segments obscure earlier ones.
894 An address
895 .I a
896 is translated
897 to a file address
898 by finding the last segment in the list
899 for which
900 .IR b ≤ a < e ;
901 the location in the file
902 is then
903 .IR address + f \- b .
904 .PP
905 Usually,
906 the text and initialized data of a program
907 are mapped by segments called
908 .IR text ,
909 .IR data ,
910 and
911 .IR bss .
912 Since a program file does not contain stack data,
913 this data is
914 not mapped.
915 The text segment is mapped similarly in
916 a normal (i.e., non-kernel)
917 .IR memfile .
918 However, one or more segments called
919 .I data
920 provide access to process memory.
921 This region contains the program's static data, the bss, the
922 heap and the stack.
923 .PP
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.
928 .PP
929 The
930 .B $m
931 command dumps the currently active maps. The
932 .B ?m
933 and
934 .B /m
935 commands modify the segment parameters in the
936 .I textfile
937 and
938 .I memfile
939 maps, respectively.
940 .SH EXAMPLES
941 To set a breakpoint at the beginning of
942 .B write()
943 in extant process 27:
944 .IP
945 .EX
946 % db 27
947 :h
948 write:b
949 :c
950 .EE
951 .PP
952 To set a breakpoint at the entry of function
953 .B parse
954 when the local variable
955 .B argc
956 in
957 .B main
958 is equal to 1:
959 .IP
960 .EX
961 parse:b *main.argc-1=X
962 .EE
963 .PP
964 This prints the value of
965 .B argc-1
966 which as a side effect sets dot; when
967 .B argc
968 is one the breakpoint will fire.
969 Beware that local variables may be stored in registers; see the
970 BUGS section.
971 .SH "SEE ALSO"
972 .MR acid (1) ,
973 .MR core (1)
974 .SH SOURCE
975 .B \*9/src/cmd/db
976 .SH DIAGNOSTICS
977 Exit status is 0, unless the last command failed or
978 returned non-zero status.
979 .SH BUGS
980 Examining a local variable with
981 .I routine.name
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.
986 .PP
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"
991 when accessed by
992 .IR db .
993 .PP
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.