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.11 (Berkeley) 08/07/91 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 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.It Ic S Va n 411Print a string using the 412.Ql ^X 413escape convention (see 414.Ar C 415above). 416.Ar n 417is the length of the string including its zero terminator. 418.It Ic Y Va 4 419Print 4 bytes in date format (see 420.Xr ctime 3 ) . 421.It Ic i Va n 422Print as machine instructions. 423.Ar n 424is the number of bytes occupied by the instruction. 425This style of printing causes the numeric variables 1, 2, ... to be set 426according to the offset parts of the arguments, if any, of the instruction 427(up to 6 on the 428.Tn VAX ) . 429.It Ic a Va 0 430Print the value of 431.Ad dot 432in symbolic form. 433Symbols are checked to ensure that they have an appropriate 434type as indicated below. 435.Bl -tag -width flag -compact 436.It Va / 437local or global data symbol 438.It Va \&? 439local or global text symbol 440.It Va \&= 441local or global absolute symbol 442.El 443.It Ic p Va 4 444Print the addressed value in symbolic form using 445the same rules for symbol lookup as 446.Ic a . 447.It Ic t Va 0 448When preceded by an integer tabs to the next appropriate tab stop. 449For example, 450.Li 8t 451moves to the next 8-space tab stop. 452.It Ic r Va 0 453Print a space. 454.It Ic n Va 0 455Print a newline. 456.It Ic \*(Lq...\*(Rq Va 0 457Print the enclosed string. 458.It Ic \&^ 459.Ad Dot 460is decremented by the current increment. Nothing is printed. 461.It Ic \&+ 462.Ad Dot 463is incremented by 1. Nothing is printed. 464.It Ic \&\- 465.Ad Dot 466is decremented by 1. Nothing is printed. 467.It newline 468Repeat the previous command with a 469.Va count 470of 1. 471.El 472.Pp 473.Bl -tag -width $modifier 474.It Xo 475.Oo Ic ?/ Oc Ns Ic l 476.Va "value mask" 477.Xc 478Words starting at 479.Ad dot 480are masked with 481.Va mask 482and 483compared with 484.Va value 485until a match is found. 486If 487.Cm L 488is used then the match is for 4 bytes at a time instead of 2. 489If no match is found then 490.Ad dot 491is unchanged; otherwise 492.Ad dot 493is set to the matched location. 494If 495.Va mask 496is omitted then all bits are compared. 497.It Xo 498.Oo Ic ?/ Oc Ns Ic w 499.Va "value ..." 500.Xc 501Write the 2-byte 502.Va value 503into the addressed location. If the command is 504.Ic W , 505write 4 bytes. 506Odd addresses 507.Em are 508allowed 509when writing to the subprocess address space. 510.It Xo 511.Oo Ic ?/ Oc Ns Ic m 512.Ad b1 e1 f1 Ns Op Ic ?/ 513.Xc 514New values for 515.Pq Ad b1 , e1 , f1 516are recorded. If less than three expressions are given then 517the remaining map parameters are left unchanged. 518If the 519.Ic ? 520or 521.Ic / 522is followed by 523.Li * 524then 525the second segment 526.Pq Ad b2 , e2 , f2 527of the mapping is changed. 528If the list is terminated by 529.Ic ? 530or 531.Ic / 532then the file 533.Pf ( Ar objfil 534or 535.Ar corfil 536respectively) is used for subsequent requests. 537For example, 538.Sq Li /m? 539will cause 540.Ic / 541to refer to 542.Ar objfil . 543.It Ic > Ns Va name 544.Ad Dot 545is assigned to the variable or register named. 546.It Ic \&! 547A shell 548.Pq Pa /bin/sh 549is called to read the rest of the line following 550.Ic \&! . 551.It Cm $ Ns Va modifier 552Miscellaneous commands. The available 553.Va modifiers 554are: 555.Bl -tag -width filexx 556.It Cm < Ns Va file 557Read commands from 558.Va file 559If this command is executed in a file, further commands 560in the file are not seen. 561If 562.Va file 563is omitted, the current input stream is terminated. If a 564.Va count 565is given, and is zero, the command will be ignored. 566The value of the count will be placed in variable 567.Va 9 568before the first command in 569.Va file 570is executed. 571.It Cm << Ns Va file 572Similar to 573.Cm < 574except it can be used in a file of commands without 575causing the file to be closed. Variable 576.Va 9 577is saved during the execution of this command, and restored when it completes. 578There is a (small) finite limit to the number of 579.Cm << 580files that can be open at once. 581.It Cm > Ns Va file 582Append output to the file 583.Va file , 584which is created if it does not exist. If 585.Va file 586is omitted, output is returned to the terminal. 587.It Cm ? Ns Va file 588Print process id, the signal which caused stoppage or termination, 589as well as the registers as 590.Ic $r . 591This is the default if 592.Va modifier 593is omitted. 594.It Cm r 595Print the general registers and the instruction addressed by 596.Nm pc . 597.Ad Dot 598is set to 599.Nm pc . 600.It Cm b 601Print all breakpoints and their associated counts and commands. 602.It Cm c 603C stack backtrace. If 604.Ad address 605is given then it is taken as the address of the current frame 606instead of the contents of the frame\-pointer register. If 607.Cm C 608is used then the names and (32 bit) values of all automatic 609and static variables are printed for each active function 610(this is partially broken; the names are not now available). If 611.Va count 612is given then only the first 613.Va count 614frames are printed. 615.It Cm d 616Set the default radix to 617.Ad address 618and report the new value. If no 619.Ad address 620is given, the default radix is not changed. 621The new radix must be between -16 (decimal) and 16 (decimal) 622and must not be 0, 1, or -1. 623A negative radix implies that numbers printed in that radix 624will be treated as signed; otherwise they are treated as unsigned. 625Note that 626.Ad address 627is interpreted in the (old) current radix. 628Thus 629.Dq "10$d" 630simply changes the default radix to unsigned. 631To make signed decimal the default radix, use 632.Dq "-0t10$d" 633.It Cm e 634The names and values of external variables are printed. 635.It Cm w 636Set the page width for output to 637.Ad address 638(default 80). 639.It Cm s 640Set the limit for symbol matches to 641.Ad address 642(default 1024). 643.It Cm q 644Exit from 645.Nm adb . 646.It Cm v 647Print all non zero variables in octal. 648.It Cm m 649Print the address map. 650.It Cm p 651.Pq Em Kernel debugging 652Change the current kernel memory mapping to map the designated 653.Sy user structure 654to the address given by the symbol 655.Sy _u . 656The 657.Ad address 658argument is the address of the user's user page table entries. 659.El 660.It Cm : Ns Va modifier 661Manage a subprocess. Available modifiers are: 662.Bl -tag -width Ds 663.It Cm b Ns Va c 664Set breakpoint at 665.Ad address . 666The breakpoint is executed 667.Va count\-1 668times before causing a stop, 669after which it stops unconditionally. 670Each time the breakpoint is encountered the command 671.Va c 672is executed. If this command is omitted or sets 673.Ad dot 674to zero, the breakpoint causes a stop immediately, 675regardless of any remaining count. 676.It Cm d 677Delete breakpoint at 678.Ad address . 679.It Cm D 680Delete all breakpoints. 681.It Cm r 682Run 683.Ar objfil 684as a subprocess. If 685.Ad address 686is given explicitly then the program is entered at this point; otherwise 687the program is entered at its standard entry point. 688.Va count 689specifies how many breakpoints are to be ignored before stopping. 690Arguments to the subprocess may be supplied on the same line as the command. 691An argument starting with < or > causes the standard 692input or output to be established for the command. 693.It Cm c Ns Va s 694The subprocess is continued with signal 695.Va s 696see 697.Xr sigvec 2 . 698If 699.Ad address 700is given then the subprocess is continued at this address. 701If no signal is specified then the signal 702that caused the subprocess to stop is sent. 703Breakpoint skipping is the same as for 704.Cm r . 705.It Cm s Ns Va s 706As for 707.Cm c 708except that the subprocess is single stepped 709.Va count 710times. If there is no current subprocess then 711.Ar objfil 712is run as a subprocess as for 713.Cm r . 714In this case no signal can be sent; the remainder of the line 715is treated as arguments to the subprocess. 716.It Cm k 717The current subprocess, if any, is terminated. 718.El 719.El 720.Sh VARIABLES 721.Nm Adb 722provides a number of variables. 723Named variables are set initially by 724.Nm adb 725but are not used subsequently. 726Numbered variables are reserved for communication as follows. 727.Pp 728.Bl -tag -width Ds -compact 729.It \&0 730The last value printed. 731.It \&1 732The last offset part of an instruction source. 733This continues up through at most 6 on the 734.Tn VAX . 735For a three-operand instruction, variable 2 is the second source offset 736and variable 3 the destination offset part. 737.It \&9 738The count on the last $< or $<< command. 739.El 740.Pp 741On entry the following are set from the system header in the 742.Ar corfil . 743If 744.Ar corfil 745does not appear to be a 746.Pa core 747file then these values are set from 748.Ar objfil . 749.Pp 750.Bl -tag -width Ds -compact 751.It b 752The base address of the data segment. 753.It d 754The data segment size. 755.It e 756The entry point. 757.It m 758The `magic' number (0407, 0410 or 0413). 759.It s 760The stack segment size. 761.It t 762The text segment size. 763.Sh ADDRESSES 764The address in a file associated with 765a written address is determined by a mapping associated with that file. 766Each mapping is represented by two triples 767.Pq Ad b1 , e1 , f1 768and 769.Pq Ad b2 , e2 , f2 770and the 771.Ad file 772.Ad address 773corresponding to a written 774.Ad address 775is calculated as follows. 776.Bd -filled -offset indent 777\*(aDb1\*(sY\*(<=\*(aRaddress \*(sY\(-> 778\*(aRfile address\*(dF=\*(aRaddress\*(sY+\*(aDf1\*(sY-\*(aDf1, 779otherwise 780.Ed 781.Pp 782.Bd -filled -offset indent 783\*(aDb1\*(sY\*(<=\*(aRaddress \*(sY\(-> 784\*(aRfile address\*(dF=\*(aRaddress\*(sY+\*(aDf2\*(sY-\*(aDf2\*(dF 785.Ed 786.Pp 787otherwise, the requested 788.Ar address 789is not legal. In some cases (e.g. for programs with separated I and D 790space) the two segments for a file may overlap. If a 791.Ic ? 792or 793.Ic / 794is followed by an 795.Ic * 796then only the second triple is used. 797.Pp 798The initial setting of both mappings is suitable for normal 799.Pa a.out 800and 801.Pa core 802files. If either file is not of the kind expected then, for that file, 803.Ad b1 804is set to 805.Li 0 , 806.Ad e1 807is set to the maximum file size and 808.Ad f1 809is set to 0; in this way the whole 810file can be examined with no address translation. 811.Sh FILES 812.Bl -tag -width a.out -compact 813.It Pa a.out 814.It Pa core 815.El 816.Sh SEE ALSO 817.Xr cc 1 , 818.Xr dbx 1 , 819.Xr ptrace 2 , 820.Xr a.out 5 , 821.Xr core 5 822.Sh HISTORY 823.Nm Adb 824was first released with 825.At v7 . 826The version 827of 828.Nm adb 829this man page describes 830is descended from the orignial. 831.Sh DIAGNOSTICS 832.Li `adb' 833when there is no current command or format. 834Comments about inaccessible files, syntax errors, 835abnormal termination of commands, etc. 836Exit status is 0, unless last command failed or returned nonzero status. 837.Sh BUGS 838Since no shell is invoked to interpret the arguments of the 839.Ic :r 840command, the customary wild-card and variable expansions cannot occur. 841