db.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.