1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.proprietary.roff% 5.\" 6.\" @(#)adb.1 5.13 (Berkeley) 04/18/94 7.\" 8.Dd 9.Dt ADB 1 10.Os BSD 4 11.Sh NAME 12.Nm adb 13.Nd debugger 14.Sh SYNOPSIS 15.Nm adb 16.Op Fl w 17.Op Fl k 18.Op Fl I Ns Ar dir 19.Op Ar objfil Op Ar corfil 20.Sh DESCRIPTION 21.Nm Adb 22is a general purpose debugging program. 23It may be used to examine files and to provide 24a controlled environment for the execution of UNIX programs. 25.Pp 26.Ar Objfil 27is normally an executable program file, preferably 28containing a symbol table; if not then the symbolic features of 29.Nm adb 30cannot be used although the file can still be examined. 31The default for 32.Ar objfil 33is 34.Pa a.out . 35.Ar Corfil 36is assumed to be a core image file produced after executing 37.Ar objfil ; 38the default for 39.Ar corfil 40is 41.Pa core 42.Pp 43Requests to 44.Nm adb 45are read from the standard input and responses are to the standard output. 46If the 47.Fl w 48flag is present then both 49.Ar objfil 50and 51.Ar corfil 52are created if necessary and opened for reading and writing 53so that files can be modified using 54.Nm adb . 55.Pp 56The 57.Fl k 58option makes 59.Nm adb 60do 61.Ux 62kernel memory 63mapping; it should be used when 64.Pa core 65is a 66.Ux 67crash dump 68or 69.Pa /dev/mem . 70.Pp 71The 72.Fl I 73option specifies a directory where files to be read 74with 75.Ic $< 76or 77.Ic $<< 78(see below) will be sought; the default is 79.Pa /usr/lib/adb . 80.Pp 81.Nm Adb 82ignores 83.Li QUIT ; 84.Li INTERRUPT 85causes return to the next 86.Nm adb 87command. 88.Pp 89In general requests to 90.Nm adb 91are of the form 92.Bd -filled -offset indent 93.Op Ad address 94.Op \&, Va count 95.Op Ic command 96.Op \&; 97.Ed 98.Pp 99If 100.Ad address 101is present then 102.Ad dot 103is set to 104.Ad address . 105Initially 106.Ad dot 107is set to 0. For most commands 108.Va count 109specifies how many times the command will be executed. The default 110.Va count 111is 1. 112.Ad Address 113and 114.Va count 115are expressions. 116.Pp 117The interpretation of an address depends on the context it is used in. 118If a subprocess is being debugged then addresses are interpreted 119in the usual way in the address space of the subprocess. 120If the operating system is being debugged, either post-mortem or using 121the special file 122.Pa /dev/mem 123to interactively examine and/or modify memory, the maps are set to map 124the kernel virtual addresses which start at 125.Li \&0x80000000 126(on the VAX); see ADDRESSES below. 127.Sh EXPRESSIONS 128.Bl -tag -width integer 129.It Sy \&\. 130The value of 131.Ad dot . 132.It Sy \&\+ 133The value of 134.Ad dot 135incremented by the current increment. 136.It Sy \&^ 137The value of 138.Ad dot 139decremented by the current increment. 140.It Sy \&" 141The last 142.Ad address 143typed. 144.It Va integer 145A number. The prefixes 146.Li \&0o 147and 148.Li \&0O 149(\*(lqzero oh\*(rq) 150force interpretation 151in octal radix; the prefixes 152.Li 0t 153and 154.Li 0T 155force interpretation in 156decimal radix; the prefixes 157.Li 0x 158and 159.Li 0X 160force interpretation in 161hexadecimal radix. Thus 162.Li 0o20 163= 164.Li 0t16 165= 166.Li 0x10 167= sixteen. 168If no prefix appears, then the 169.Em default radix 170is used; see the 171.Ic $d 172command. The default radix is initially hexadecimal. 173The hexadecimal digits are 174.Li 0123456789abcdefABCDEF 175with the obvious 176values. Note that a hexadecimal number whose most significant 177digit would otherwise be an alphabetic character must have a 178.Li 0x 179(or 180.Li 0X ) 181prefix (or a leading zero if the default radix is hexadecimal). 182.It Va integer.fraction 183A 32 bit floating point number. 184.It Li \'cccc\' 185The ASCII value of up to 4 characters. 186.Li \e 187may be used to escape a 188.Li \' . 189.It Va < name 190The value of 191.Va name , 192which is either a variable name or a register name. 193.Nm Adb 194maintains a number of variables (see 195.Sx VARIABLES 196below) 197named by single letters or digits. 198If 199.Va name 200is a register name then the value of the register is obtained from 201the system header in 202.Ar corfil . 203The register names are those printed by the 204.Ic $r 205command. 206.It Va symbol 207A 208.Va symbol 209is a sequence of upper or lower case letters, underscores or 210digits, not starting with a digit. The backslash character 211.Li \e 212may be used to escape other characters. The value of the 213.Va symbol 214is taken from the symbol table in 215.Ar objfil . 216An initial 217.Li \_ 218will be prepended to 219.Va symbol 220if needed. 221.It Va _symbol 222In C, the `true name' of an external symbol begins with 223.Li \_ . 224It may be necessary to utter this name to distinguish it 225from internal or hidden variables of a program. 226.It Va routine.name 227The address of the variable 228.Va name 229in the specified C routine. Both 230.Va routine 231and 232.Va name 233are 234.Va symbols . 235If 236.Va routine 237is omitted, the currently active frame is used. 238(This form is currently broken; local variables can be examined 239only with 240.Xr dbx 1 ) . 241If 242.Va name 243is omitted the value is the address 244of the most recently activated C stack frame 245corresponding to 246.Va routine 247(this much works). 248.It Pq Va exp 249The value of the expression 250.Ar exp . 251.El 252.Ss Monadic Operators 253.Bl -tag -width flag -compact 254.It Li \&* Ns Va exp 255The contents of the location addressed by 256.Va exp 257in 258.Ar corfil . 259.It Li \&@ Ns Va exp 260The contents of the location addressed by 261.Va exp 262in 263.Ar objfil . 264.It Li \&\- Ns Va exp 265Integer negation. 266.It Li \&~ Ns Va exp 267Bitwise complement. 268.It Li \&# Ns Va exp 269Logical negation. 270.El 271.Ss Dyadic operators 272Are left associative and are less binding than monadic operators. 273.Pp 274.Bl -tag -width xxXxx -compact 275.It Va e1 Ns Li \&\+ Ns Va e2 276Integer addition. 277.It Va e1 Ns Li \&\- Ns Va e2 278Integer subtraction. 279.It Va e1 Ns Li \&* Ns Va e2 280Integer multiplication. 281.It Va e1 Ns Li \&% Ns Va e2 282Integer division. 283.It Va e1 Ns Li & Ns Va e2 284Bitwise conjunction. 285.It Va e1 Ns Li \&| Ns Va e2 286Bitwise disjunction. 287.It Va e1 Ns Li # Ns Va e2 288.Va e1 289rounded up to the next multiple of 290.Va e2 . 291.El 292.Sh COMMANDS 293Most commands consist of a verb followed by a modifier or list of modifiers. 294The following verbs are available. 295(The commands 296.Ic ? 297and 298.Li / 299may be followed by 300.Li * ; 301see the 302.Sx ADDRESSES 303section 304for further details.) 305.Bl -tag -width flag 306.It Ic ? Ns Va f 307Locations starting at 308.Ad address 309in 310.Ar objfil 311are printed according to the format 312.Va f . 313.Ad dot 314is incremented by the sum of the increments for each format letter (q.v.). 315.It Ic / Ns Va f 316Locations starting at 317.Ad address 318in 319.Ar corfil 320are printed according to the format 321.Va f 322and 323.Ad dot 324is incremented as for 325.Ic ? . 326.It Ic = Ns Va f 327The value of 328.Ad address 329itself is printed in the styles indicated by the format 330.Va f . 331(For 332.Va i 333format, zero values are assumed 334for the parts of the instruction that reference 335subsequent words.) 336.El 337.Pp 338A 339.Va format 340consists of one or more characters that specify a style of printing. 341Each format character may be preceded by a decimal integer 342that is a repeat count for the format character. 343While stepping through a format, 344.Ad dot 345is incremented by the amount given for each format letter. 346If no format is given then the last format is used. 347The format characters available are as follows. 348Note that a backslash 349.Pq Li \e 350must be used 351to quote the three numeric formats. 352.Pp 353.Bl -tag -width \&M_____\&M -compact 354.It Ic 1 Va 1 355Print 1 byte in the current radix 356(which may be either signed or unsigned; see the 357.Ic $d 358command). 359.It Ic 2 Va 2 360Print 2 bytes in the current radix. 361.It Ic 4 Va 4 362Print 4 bytes in the current radix. 363.It Ic v Va 2 364Print 2 bytes in the signed variant of the current radix. 365.It Ic V Va 4 366Print 4 bytes in the signed variant of the current radix. 367.It Ic o Va 2 368Print 2 bytes in unsigned octal. All octal numbers output by 369.Nm adb 370are preceded by 0. 371.It Ic O Va 4 372Print 4 bytes in unsigned octal. 373.It Ic q Va 2 374Print 2 bytes in signed octal. 375.It Ic Q Va 4 376Print 4 bytes in signed octal. 377.It Ic u Va 2 378Print 2 bytes in unsigned decimal. 379.It Ic U Va 4 380Print 4 bytes in long unsigned decimal. 381.It Ic d Va 2 382Print 2 bytes in signed decimal. 383.It Ic D Va 4 384Print 4 bytes in long signed decimal. 385.It Ic x Va 2 386Print 2 bytes in unsigned hexadecimal. 387.It Ic X Va 4 388Print 4 bytes in unsigned hexadecimal. 389.It Ic z Va 2 390Print 2 bytes in signed hexadecimal. 391.It Ic Z Va 4 392Print 4 bytes in signed hexadecimal. 393.It Ic f Va 4 394Print 4 bytes as a floating point number. 395.It Ic F Va 8 396Print 8 bytes as a double precision floating point number. 397.It Ic b Va 1 398Print 1 byte in unsigned octal. 399.It Ic c Va 1 400Print 1 byte as a character. 401.It Ic C Va 1 402Print 1 byte as a character, using 403the standard escape convention where control characters 404are printed as 405.Ql \&^X 406and the delete character is printed as 407.Ql ^? . 408.It Ic s Va n 409Print the addressed characters until a zero character is reached. 410.Ar n 411is the length of the string including its zero terminator. 412.It Ic S Va n 413Print a string using the 414.Ql ^X 415escape convention (see 416.Ar C 417above). 418.Ar n 419is the length of the string including its zero terminator. 420.It Ic Y Va 4 421Print 4 bytes in date format (see 422.Xr ctime 3 ) . 423.It Ic i Va n 424Print as machine instructions. 425.Ar n 426is the number of bytes occupied by the instruction. 427This style of printing causes the numeric variables 1, 2, ... to be set 428according to the offset parts of the arguments, if any, of the instruction 429(up to 6 on the 430.Tn VAX ) . 431.It Ic a Va 0 432Print the value of 433.Ad dot 434in symbolic form. 435Symbols are checked to ensure that they have an appropriate 436type as indicated below. 437.Bl -tag -width flag -compact 438.It Va / 439local or global data symbol 440.It Va \&? 441local or global text symbol 442.It Va \&= 443local or global absolute symbol 444.El 445.It Ic p Va 4 446Print the addressed value in symbolic form using 447the same rules for symbol lookup as 448.Ic a . 449.It Ic t Va 0 450When preceded by an integer, tabs to the next appropriate tab stop. 451For example, 452.Li 8t 453moves to the next 8-space tab stop. 454.It Ic r Va 0 455Print a space. 456.It Ic n Va 0 457Print a newline. 458.ne 2v 459.It Ic \*(Lq...\*(Rq Va 0 460Print the enclosed string. 461.It Ic \&^ 462.Ad Dot 463is decremented by the current increment. Nothing is printed. 464.It Ic \&+ 465.Ad Dot 466is incremented by 1. Nothing is printed. 467.It Ic \&\- 468.Ad Dot 469is decremented by 1. Nothing is printed. 470.It newline 471Repeat the previous command with a 472.Va count 473of 1. 474.El 475.Pp 476.Bl -tag -width $modifier 477.It Xo 478.Oo Ic ?/ Oc Ns Ic l 479.Va "value mask" 480.Xc 481Words starting at 482.Ad dot 483are masked with 484.Va mask 485and 486compared with 487.Va value 488until a match is found. 489If 490.Cm L 491is used then the match is for 4 bytes at a time instead of 2. 492If no match is found then 493.Ad dot 494is unchanged; otherwise 495.Ad dot 496is set to the matched location. 497If 498.Va mask 499is omitted then all bits are compared. 500.It Xo 501.Oo Ic ?/ Oc Ns Ic w 502.Va "value ..." 503.Xc 504Write the 2-byte 505.Va value 506into the addressed location. If the command is 507.Ic W , 508write 4 bytes. 509Odd addresses 510.Em are 511allowed 512when writing to the subprocess address space. 513.It Xo 514.Oo Ic ?/ Oc Ns Ic m 515.Ad b1 e1 f1 Ns Op Ic ?/ 516.Xc 517New values for 518.Pq Ad b1 , e1 , f1 519are recorded. If less than three expressions are given then 520the remaining map parameters are left unchanged. 521If the 522.Ic ? 523or 524.Ic / 525is followed by 526.Li * 527then 528the second segment 529.Pq Ad b2 , e2 , f2 530of the mapping is changed. 531If the list is terminated by 532.Ic ? 533or 534.Ic / 535then the file 536.Pf ( Ar objfil 537or 538.Ar corfil 539respectively) is used for subsequent requests. 540For example, 541.Sq Li /m? 542will cause 543.Ic / 544to refer to 545.Ar objfil . 546.It Ic > Ns Va name 547.Ad Dot 548is assigned to the variable or register named. 549.It Ic \&! 550A shell 551.Pq Pa /bin/sh 552is called to read the rest of the line following 553.Ic \&! . 554.It Cm $ Ns Va modifier 555Miscellaneous commands. The available 556.Va modifiers 557are: 558.Bl -tag -width filexx 559.It Cm < Ns Va file 560Read commands from 561.Va file . 562If this command is executed in a file, further commands 563in the file are not seen. 564If 565.Va file 566is omitted, the current input stream is terminated. If a 567.Va count 568is given, and is zero, the command will be ignored. 569The value of the count will be placed in variable 570.Va 9 571before the first command in 572.Va file 573is executed. 574.It Cm << Ns Va file 575Similar to 576.Cm < 577except it can be used in a file of commands without 578causing the file to be closed. Variable 579.Va 9 580is saved during the execution of this command, and restored when it completes. 581There is a (small) finite limit to the number of 582.Cm << 583files that can be open at once. 584.It Cm > Ns Va file 585Append output to the file 586.Va file , 587which is created if it does not exist. If 588.Va file 589is omitted, output is returned to the terminal. 590.It Cm ? Ns Va file 591Print process id, the signal which caused stoppage or termination, 592as well as the registers as 593.Ic $r . 594This is the default if 595.Va modifier 596is omitted. 597.It Cm r 598Print the general registers and the instruction addressed by 599.Nm pc . 600.Ad Dot 601is set to 602.Nm pc . 603.It Cm b 604Print all breakpoints and their associated counts and commands. 605.It Cm c 606C stack backtrace. If 607.Ad address 608is given then it is taken as the address of the current frame 609instead of the contents of the frame\-pointer register. If 610.Cm C 611is used then the names and (32 bit) values of all automatic 612and static variables are printed for each active function 613(this is partially broken; the names are not now available). If 614.Va count 615is given then only the first 616.Va count 617frames are printed. 618.It Cm d 619Set the default radix to 620.Ad address 621and report the new value. If no 622.Ad address 623is given, the default radix is not changed. 624The new radix must be between -16 (decimal) and 16 (decimal) 625and must not be 0, 1, or -1. 626A negative radix implies that numbers printed in that radix 627will be treated as signed; otherwise they are treated as unsigned. 628Note that 629.Ad address 630is interpreted in the (old) current radix. 631Thus 632.Dq "10$d" 633simply changes the default radix to unsigned. 634To make signed decimal the default radix, use 635.Dq "-0t10$d" 636.It Cm e 637The names and values of external variables are printed. 638.It Cm w 639Set the page width for output to 640.Ad address 641(default 80). 642.It Cm s 643Set the limit for symbol matches to 644.Ad address 645(default 1024). 646.It Cm q 647Exit from 648.Nm adb . 649.It Cm v 650Print all non zero variables in octal. 651.It Cm m 652Print the address map. 653.It Cm p 654.Pq Em Kernel debugging 655Change the current kernel memory mapping to map the designated 656.Sy user structure 657to the address given by the symbol 658.Sy _u . 659The 660.Ad address 661argument is the address of the user's user page table entries. 662.El 663.It Cm : Ns Va modifier 664Manage a subprocess. Available modifiers are: 665.Bl -tag -width Ds 666.It Cm b Ns Va c 667Set breakpoint at 668.Ad address . 669The breakpoint is executed 670.Va count\-1 671times before causing a stop, 672after which it stops unconditionally. 673Each time the breakpoint is encountered the command 674.Va c 675is executed. If this command is omitted or sets 676.Ad dot 677to zero, the breakpoint causes a stop immediately, 678regardless of any remaining count. 679.It Cm d 680Delete breakpoint at 681.Ad address . 682.It Cm D 683Delete all breakpoints. 684.It Cm r 685Run 686.Ar objfil 687as a subprocess. If 688.Ad address 689is given explicitly then the program is entered at this point; otherwise 690the program is entered at its standard entry point. 691.Va count 692specifies how many breakpoints are to be ignored before stopping. 693Arguments to the subprocess may be supplied on the same line as the command. 694An argument starting with < or > causes the standard 695input or output to be established for the command. 696.It Cm c Ns Va s 697The subprocess is continued with signal 698.Va s ; 699see 700.Xr sigvec 2 . 701If 702.Ad address 703is given then the subprocess is continued at this address. 704If no signal is specified then the signal 705that caused the subprocess to stop is sent. 706Breakpoint skipping is the same as for 707.Cm r . 708.It Cm s Ns Va s 709As for 710.Cm c 711except that the subprocess is single stepped 712.Va count 713times. If there is no current subprocess then 714.Ar objfil 715is run as a subprocess as for 716.Cm r . 717In this case no signal can be sent; the remainder of the line 718is treated as arguments to the subprocess. 719.It Cm k 720The current subprocess, if any, is terminated. 721.El 722.El 723.Sh VARIABLES 724.Nm Adb 725provides a number of variables. 726Named variables are set initially by 727.Nm adb 728but are not used subsequently. 729Numbered variables are reserved for communication as follows. 730.Pp 731.Bl -tag -width Ds -compact 732.It \&0 733The last value printed. 734.It \&1 735The last offset part of an instruction source. 736This continues up through at most 6 on the 737.Tn VAX . 738For a three-operand instruction, variable 2 is the second source offset 739and variable 3 the destination offset part. 740.It \&9 741The count on the last $< or $<< command. 742.El 743.Pp 744On entry the following are set from the system header in the 745.Ar corfil . 746If 747.Ar corfil 748does not appear to be a 749.Pa core 750file then these values are set from 751.Ar objfil . 752.Pp 753.Bl -tag -width Ds -compact 754.It b 755The base address of the data segment. 756.It d 757The data segment size. 758.It e 759The entry point. 760.It m 761The `magic' number (0407, 0410 or 0413). 762.It s 763The stack segment size. 764.It t 765The text segment size. 766.Sh ADDRESSES 767The address in a file associated with 768a written address is determined by a mapping associated with that file. 769Each mapping is represented by two triples 770.Pq Ad b1 , e1 , f1 771and 772.Pq Ad b2 , e2 , f2 773and the 774.Ad file 775.Ad address 776corresponding to a written 777.Ad address 778is calculated as follows. 779.Bd -filled -offset indent 780\*(aDb1\*(sY\*(<=\*(aRaddress\*(<=\*(aDe1 \*(sY\(-> 781\*(aRfile address\*(dF=\*(aRaddress\*(sY+\*(aDf1\*(sY-\*(aDb1, 782otherwise 783.Ed 784.Pp 785.Bd -filled -offset indent 786\*(aDb2\*(sY\*(<=\*(aRaddress\*(<=\*(aDe2 \*(sY\(-> 787\*(aRfile address\*(dF=\*(aRaddress\*(sY+\*(aDf2\*(sY-\*(aDb2\*(dF 788.Ed 789.Pp 790otherwise, the requested 791.Ar address 792is not legal. In some cases (e.g. for programs with separated I and D 793space) the two segments for a file may overlap. If a 794.Ic ? 795or 796.Ic / 797is followed by an 798.Ic * 799then only the second triple is used. 800.Pp 801The initial setting of both mappings is suitable for normal 802.Pa a.out 803and 804.Pa core 805files. If either file is not of the kind expected then, for that file, 806.Ad b1 807is set to 808.Li 0 , 809.Ad e1 810is set to the maximum file size and 811.Ad f1 812is set to 0; in this way the whole 813file can be examined with no address translation. 814.Sh FILES 815.Bl -tag -width a.out -compact 816.It Pa a.out 817.It Pa core 818.El 819.Sh SEE ALSO 820.Xr cc 1 , 821.Xr dbx 1 , 822.Xr ptrace 2 , 823.Xr a.out 5 , 824.Xr core 5 825.Sh HISTORY 826.Nm Adb 827was first released with 828.At v7 . 829The version 830of 831.Nm adb 832this man page describes 833is descended from the original. 834.Sh DIAGNOSTICS 835.Li `adb' 836when there is no current command or format. 837Comments about inaccessible files, syntax errors, 838abnormal termination of commands, etc. 839Exit status is 0, unless last command failed or returned nonzero status. 840.Sh BUGS 841Since no shell is invoked to interpret the arguments of the 842.Ic :r 843command, the customary wild-card and variable expansions cannot occur. 844