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