1.\" Copyright (c) 1983, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)dbx.1 6.5 (Berkeley) 07/24/90 7.\" 8.Dd 9.Dt DBX 1 10.Os BSD 4.2 11.Sh NAME 12.Nm dbx 13.Nd debugger 14.Sh SYNOPSIS 15.Nm Dbx 16.Op Fl r 17.Op Fl i 18.Op Fl k 19.Op Fl I Ar dir 20.Op Fl c Ar file 21.Op Ar objfile Op Ar coredump 22.Sh DESCRIPTION 23.Nm Dbx 24is a tool for source level debugging and execution of 25programs under UNIX. 26The 27.Ar objfile 28is an object file produced by a compiler 29with the appropriate flag (usually 30.Fl g ) 31specified to produce symbol information in the object file. 32Currently, 33.Xr cc 1 , 34.Xr f77 1 , 35.Xr pc 1 , 36and the DEC Western 37Research Laboratory Modula-2 compiler, 38.Xr mod l , 39produce the appropriate source information. 40The machine level facilities of 41.Nm dbx 42can be used on any program. 43.Pp 44The object file contains a symbol table that includes the names of 45all the source files translated by the compiler to create it. 46These files are available for perusal while using the debugger. 47.Pp 48If a file named 49.Pa core 50exists in the current directory 51or a 52.Ar coredump 53file is specified, 54.Nm dbx 55can be used 56to examine the state of the program when it faulted. 57.Pp 58If the file 59.Pa .dbxinit 60exists in the current directory then the 61debugger commands in it are executed. 62.Nm Dbx 63also checks for a 64.Pa .dbxinit 65in the user's home directory 66if there isn't one in the current directory. 67.Pp 68The command line options and their meanings are: 69.Tw Fl 70.Tp Fl r 71Execute 72.Ar objfile 73immediately. 74If it terminates successfully 75.Nm dbx 76exits. 77Otherwise the reason for termination will be reported 78and the user offered the option of entering the debugger 79or letting the program fault. 80.Nm Dbx 81will read from 82.Pa /dev/tty 83when 84.Fl r 85is specified 86and standard input is not a terminal. 87.Tp Fl i 88Force 89.Nm dbx 90to act as though standard input is a terminal. 91.Tp Fl k 92Map memory addresses, useful for kernel debugging. 93.Tp Cx Fl I 94.Cx \&\ \& 95.Ar dir 96.Cx 97Add 98.Ar dir 99to the list of directories 100that are searched when looking for a source file. 101Normally 102.Nm dbx 103looks for source files in the current directory 104and in the directory where 105.Ar objfile 106is located. 107The directory search path can also be set with the 108.Ic use 109command. 110.Tp Cx Fl c 111.Cx \&\ \& 112.Ar file 113.Cx 114Execute the 115.Nm dbx 116commands in the 117.Ar file 118before 119reading from standard input. 120.Tp 121.Pp 122Unless 123.Fl r 124is specified, 125.Nm dbx 126just prompts and waits for a command. 127.Ss Execution and Tracing Commands 128.Dw Fl 129.Di L 130.Dp Cx Ic run 131.Cx \&\ \& 132.Op Ar args 133.Cx \&\ \& 134.Op Sy < Ar filename 135.Cx \&\ \& 136.Op Sy > Ar filename 137.Cx 138.Dp Cx Ic rerun 139.Cx \&\ \& 140.Op Ar args 141.Cx \&\ \& 142.Op Sy < Ar filename 143.Cx \&\ \& 144.Op Sy > Ar filename 145.Cx 146Start executing 147.Ar objfile , 148passing 149.Ar args 150as command line arguments; 151.Sy < 152or 153.Sy > 154can be used to redirect input or output in the usual manner. 155When 156.Ic rerun 157is used without any arguments the previous 158argument list is passed to the program; 159otherwise it is identical to 160.Ic run . 161If 162.Ar objfile 163has been written since the last time the symbolic information 164was read in, 165.Nm dbx 166will read in the new information. 167.Dp Cx Ic trace 168.Cx \&\ \& 169.Op Ic in Ar procedure/function 170.Cx \&\ \& 171.Op Ic if Ar condition 172.Cx 173.Dp Cx Ic trace 174.Cx \&\ \& 175.Ar source-line-number 176.Cx \&\ \& 177.Op Ic if Ar condition 178.Cx 179.Dp Cx Ic trace 180.Cx \&\ \& 181.Ar procedure/function 182.Cx \&\ \& 183.Op Ic in Ar procedure/function 184.Cx \&\ \& 185.Op Ic if Ar condition 186.Cx 187.Dp Cx Ic trace 188.Cx \&\ \& 189.Ar expression 190.Cx \&\ \& 191.Ic at 192.Cx \&\ \& 193.Ar source-line-number 194.Cx \&\ \& 195.Op Ic if Ar condition 196.Cx 197.Dp Cx Ic trace 198.Cx \&\ \& 199.Ar variable 200.Cx \&\ \& 201.Op Ic in Ar procedure/function 202.Cx \&\ \& 203.Op Ic if Ar condition 204.Cx 205Have tracing information printed when the program is executed. 206A number is associated with the command that is used 207to turn the tracing off (see the 208.Ic delete 209command). 210.Pp 211The first argument describes what is to be traced. 212If it is a 213.Ar source-line-number , 214then the line is printed 215immediately prior to being executed. 216Source line numbers in a file other than the current one 217must be preceded by the name of the file in quotes and a colon, e.g. 218"mumble.p":17. 219.Pp 220If the argument is a procedure or function name then 221every time it is called, information is printed telling 222what routine called it, from what source line it was called, 223and what parameters were passed to it. 224In addition, its return is noted, and if it's a function 225then the value it is returning is also printed. 226.Pp 227If the argument is an 228.Ar expression 229with an 230.Ic at 231clause 232then the value of the expression is printed whenever the 233identified source line is reached. 234.Pp 235If the argument is a variable then the name and value of the variable 236is printed whenever it changes. 237Execution is substantially slower during this form of tracing. 238.Pp 239If no argument is specified then all source lines are printed 240before they are executed. 241Execution is substantially slower during this form of tracing. 242.Pp 243The clause 244.Ic in 245.Ar procedure/function 246restricts tracing information 247to be printed only while executing inside the given procedure 248or function. 249.Pp 250.Ar Condition 251is a boolean expression and is 252evaluated prior to printing the tracing information; 253if it is false then the information is not printed. 254.Dp Cx Ic stop if 255.Cx \&\ \& 256.Ar condition 257.Cx 258.Dp Cx Ic stop at 259.Cx \&\ \& 260.Ar source-line-number 261.Cx \&\ \& 262.Op Ic if Ar condition 263.Cx 264.Dp Cx Ic stop in 265.Cx \&\ \& 266.Ar source-line-number 267.Cx \&\ \& 268.Op Ic if Ar condition 269.Cx 270.Dp Cx Ic stop 271.Cx \&\ \& 272.Ar variable 273.Cx \&\ \& 274.Op Ic if Ar condition 275.Cx 276Stop execution when the given line is reached, procedure or function 277called, variable changed, or condition true. 278.Dp Cx Ic status 279.Cx \&\ \& 280.Op Ic \&> Ar filename 281.Cx 282Print out the currently active 283.Ic trace 284and 285.Ic stop 286commands. 287.Dp Cx Ic delete 288.Cx \&\ \& 289.Ar command-number ... 290.Cx 291The traces or stops corresponding to the given numbers are removed. 292The numbers associated with traces and stops are printed by 293the 294.Ic status 295command. 296.Dp Cx Ic catch 297.Cx \&\ \& 298.Ar number 299.Cx 300.Dp Cx Ic catch 301.Cx \&\ \& 302.Ar signal-name 303.Cx 304.Dp Cx Ic ignore 305.Cx \&\ \& 306.Ar number 307.Cx 308.Dp Cx Ic ignore 309.Cx \&\ \& 310.Ar signal-name 311.Cx 312Start or stop trapping a signal before it is sent 313to the program. 314This is useful when a program being debugged 315handles signals such as interrupts. 316A signal may be specified by number or by a name 317(e.g., SIGINT). 318Signal names are case insensitive and the ``SIG'' prefix is optional. 319By default all signals are trapped except SIGCONT, SIGCHILD, 320SIGALRM and SIGKILL. 321.Dp Cx Ic cont 322.Cx \&\ \& 323.Ar integer 324.Cx 325.Dp Cx Ic cont 326.Cx \&\ \& 327.Ar signal-name 328.Cx 329Continue execution from where it stopped. 330If a signal is specified, the process continues as though 331it received the signal. 332Otherwise, the process is continued as though it had not been stopped. 333.Pp 334Execution cannot be continued if the process has ``finished'', 335that is, called the standard procedure ``exit''. 336.Nm Dbx 337does not allow the process to exit, thereby 338letting the user to examine the program state. 339.Dp Ic step 340Execute one source line. 341.Dp Ic next 342Execute up to the next source line. 343The difference between this and 344.Ic step 345is that 346if the line contains a call to a procedure or function 347the 348.Ic step 349command will stop at the beginning of that 350block, while the 351.Ic next 352command will not. 353.Dp Cx Ic return 354.Cx \&\ \& 355.Op Ar procedure 356.Cx 357Continue until a return to 358.Ar procedure 359is executed, or 360until the current procedure returns if none is specified. 361.Dp Cx Ic call 362.Cx \&\ \& 363.Ar procedure (parameters ) 364.Cx 365Execute the object code associated with the named procedure or function. 366.Dp 367.Ss Printing Variables and Expressions 368Names are resolved first using the static scope of the current function, 369then using the dynamic scope if the name is not defined 370in the static scope. 371If static and dynamic searches do not yield a result, 372an arbitrary symbol is chosen and 373the message 374.Dq Li [using Ar qualified name] 375is printed. 376The name resolution procedure may be overridden by qualifying an identifier 377with a block name, e.g., 378.Dq Li module.variable 379For C, source files are treated as modules named 380by the file name without ``.c''. 381.Pp 382Expressions are specified with an approximately 383common subset of C and Pascal (or equivalently Modula-2) syntax. 384Indirection can be denoted using either a prefix ``*'' or 385a postfix ``^'' and 386array expressions are subscripted by brackets 387.Cx (`` 388.Op 389.Cx \'\'). 390.Cx 391The field reference operator (``.'') can be used with pointers 392as well as records, making the C operator ``\->'' unnecessary 393(although it is supported). 394.Pp 395Types of expressions are checked; 396the type of an expression may be overridden 397by using 398.Cx `` 399.Ar type-name (expression) 400.Cx \'\'. 401.Cx 402When there is no corresponding named type 403the special constructs 404.Cx ``& 405.Ar type-name 406.Cx \'\' 407.Cx 408and 409.Cx ``$$ 410.Ar tag-name 411.Cx \'\' 412.Cx 413can be used to represent a pointer to a named type or C structure tag. 414.Dw Fl 415.Di L 416.Dp Cx Ic assign 417.Cx \&\ \& 418.Ar variable 419.Ic = 420.Ar expression 421.Cx 422Assign the value of the expression to the variable. 423.Dp Cx Ic dump 424.Cx \&\ \& 425.Op Ar procedure 426.Cx \&\ \& 427.Op Ic > Ar filename 428.Cx 429Print the names and values of variables in the given procedure, 430or the current one if none is specified. 431If the procedure given is ``.'', then the all active variables 432are dumped. 433.Dp Cx Ic print 434.Cx \&\ \& 435.Ar expression 436.Cx \&\ \& 437.Op Ic \&, Ar expression ... 438.Cx 439Print out the values of the expressions. 440.Dp Cx Ic whatis 441.Cx \&\ \& 442.Ar name 443.Cx 444Print the declaration of the given name, which may be qualified 445with block names as above. 446.Dp Cx Ic which 447.Cx \&\ \& 448.Ar identifier 449.Cx 450Print the full qualification of the given identifer, i.e. 451the outer blocks that the identifier is associated with. 452.Dp Cx Ic up 453.Cx \&\ \& 454.Op Ar count 455.Cx 456.Dp Cx Ic down 457.Cx \&\ \& 458.Op Ar count 459.Cx 460Move the current function, which is used for resolving names, 461up or down the stack 462.Ar count 463levels. 464The default 465.Ar count 466is 1. 467.Dp Ic where 468Print out a list of the active procedures and function. 469.Dp Cx Ic whereis 470.Cx \&\ \& 471.Ar identifier 472.Cx 473Print the full qualification of all the symbols whose 474name matches the given identifier. 475The order in which the symbols are printed is not meaningful. 476.Dp 477.Ss Accessing Source Files 478.Pp 479.Di L 480.Dp Cx Ar /regular expression 481.Op / 482.Cx 483.Dp Cx Ar ?regular expression 484.Op ? 485.Cx 486Search forward or backward in the current source file 487for the given pattern. 488.Dp Cx Ic edit 489.Cx \&\ \& 490.Op Ar filename 491.Cx 492.Dp Cx Ic edit 493.Cx \&\ \& 494.Ar procedure/function-name 495.Cx 496Invoke an editor on 497.Ar filename 498or the current source file if none 499is specified. 500If a 501.Ar procedure 502or 503.Ar function 504name is specified, 505the editor is invoked on the file that contains it. 506Which editor is invoked by default depends on the installation. 507The default can be overridden by setting the environment variable 508.Ev EDITOR 509to the name of the desired editor. 510.Dp Cx Ic file 511.Cx \&\ \& 512.Op Ar filename 513.Cx 514Change the current source file name to 515.Ar filename . 516If none is specified then the current source file name is printed. 517.Dp Cx Ic func 518.Cx \&\ \& 519.Op Ar procedure/function 520.Cx 521Change the current function. 522If none is specified then print the current function. 523Changing the current function implicitly changes the current source file 524to the one that contains the function; it also changes the current scope 525used for name resolution. 526.Dp Cx Ic list 527.Cx \&\ \& 528.Op Ar source-line-number Op Ic \&, Ar source-line-number 529.Cx 530.Dp Cx Ic list 531.Cx \&\ \& 532.Ar procedure/function 533.Cx 534List the lines in the current source file from the first line number to 535the second inclusive. 536If no lines are specified, the next 10 lines are listed. 537If the name of a procedure or function is given 538lines 539.Ar n-k 540to 541.Ar n+k 542are listed where 543.Ar n 544is the first statement 545in the procedure or function and 546.Ar k 547is small. 548.Dp Cx Ic use 549.Cx \&\ \& 550.Ar directory-list 551.Cx 552Set the list of directories to be searched 553when looking for source files. 554.Dp 555.Ss Command Aliases and Variables 556.Dw Fl 557.Di L 558.Dp Cx Ic alias 559.Cx \&\ \& 560.Ar name 561.Cx \&\ \& 562.Ar name 563.Cx 564.Dp Cx Ic alias 565.Cx \&\ \& 566.Ar name 567.Cx \&\ \& 568.Ar string 569.Cx 570.Dp Cx Ic alias 571.Cx \&\ \& 572.Ar name (parameters) 573.Cx \&\ \& 574.Cx `` 575.Ar string 576.Cx \'\' 577.Cx 578When commands are processed, 579dbx first checks to see if the word 580is an alias for either a command or a string. 581If it is an alias, then dbx treats the input as though 582the corresponding string (with values substituted for any parameters) 583had been entered. 584For example, 585to define an alias ``rr'' for the command ``rerun'', 586one can say 587.Pp 588.Dl alias rr rerun 589.Pp 590To define an alias called ``b'' that sets a stop at a particular line 591one can say 592.Pp 593.Dl alias b(x) ``stop at x'' 594.Pp 595Subsequently, the command ``b(12)'' will expand to ``stop at 12''. 596.Pp 597.Dp Cx Ic set 598.Ws 599.Ar name 600.Op \&= Ar expression 601.Cx 602The 603.Ic set 604command defines values for debugger variables. 605The names of these variables cannot conflict with names in the program 606being debugged, and are expanded to the corresponding expression 607within other commands. 608The following variables have a special meaning: 609.Dw Ds 610.Di L 611.Dp Li $frame 612Setting this variable to an address causes dbx to use the stack frame 613pointed to by the address for 614doing stack traces and accessing local variables. 615This facility is of particular use for kernel debugging. 616.Dp Li $hexchars 617.Dp Li $hexints 618.Dp Li $hexoffsets 619.Dp Li $hexstrings 620When set, dbx prints out 621out characters, integers, offsets from registers, or character pointers 622respectively in hexadecimal. 623.Dp Li $listwindow 624The value of this variable specifies the number 625of lines to list around a function or when the 626.Ic list 627command 628is given without any parameters. 629Its default value is 10. 630.Dp Li $mapaddrs 631Setting (unsetting) this variable causes dbx to start (stop) 632mapping addresses. 633As with ``$frame'', this is useful for kernel debugging. 634.Dp Li $unsafecall 635.Dp Li $unsafeassign 636When ``$unsafecall'' is set, 637strict type checking is turned off for arguments to 638subroutine or function calls ( 639.Ar e .g . 640in the 641.Ic call 642statement). 643When ``$unsafeassign'' is set, 644strict type checking between the two sides 645of an 646.Ic assign 647statement is turned off. 648These variables should be used only with great care, 649because they severely limit dbx's usefulness 650for detecting errors. 651.Dp 652.Dp Cx Ic unalias 653.Cx \&\ \& 654.Ar name 655.Cx 656Remove the alias with the given name. 657.Dp Cx Ic unset 658.Cx \&\ \& 659.Ar name 660.Cx 661Delete the debugger variable associated with 662.Ar name . 663.Dp 664.Ss Machine Level Commands 665.Dw Fl 666.Di L 667.Dp Cx Ic tracei 668.Cx \&\ \& 669.Op Ar address 670.Cx \&\ \& 671.Op .Ic if Ar cond 672.Cx 673.Dp Cx Ic tracei 674.Cx \&\ \& 675.Op Ar variable 676.Cx \&\ \& 677.Op Ic at Ar address 678.Cx \&\ \& 679.Op Ic if Ar cond 680.Cx 681.Dp Cx Ic stopi 682.Cx \&\ \& 683.Op Ar address 684.Cx \&\ \& 685.Op Ic if Ar cond 686.Cx 687.Dp Cx Ic stopi 688.Cx \&\ \& 689.Op Ic at 690.Cx \&\ \& 691.Op Ar address 692.Cx \&\ \& 693.Op Ic if Ar cond 694.Cx 695Turn on tracing or set a stop using a machine instruction address. 696.Dp Ic stepi 697.Dp Ic nexti 698Single step as in 699.Ic step 700or 701.Ic next , 702but do a single instruction 703rather than source line. 704.Dp Cx Ar address 705.Cx \&, 706.Ar address 707.Cx \&/ 708.Op Ar mode 709.Cx 710.Dp Cx Ar address 711.Cx \&/ 712.Op Ar count 713.Op Ar mode 714.Cx 715Print the contents of memory starting at the first 716.Ar address 717and continuing up to the second 718.Ar address 719or until 720.Ar count 721items are printed. 722If the address is ``.'', the address following the one 723printed most recently is used. 724The 725.Ar mode 726specifies how memory is to be printed; 727if it is omitted the previous mode specified is used. 728The initial mode is ``X''. 729The following modes are supported: 730.Dw Cm 731.Dp Cm i 732print the machine instruction 733.Dp Cm d 734print a short word in decimal 735.Dp Cm D 736print a long word in decimal 737.Dp Cm o 738print a short word in octal 739.Dp Cm O 740print a long word in octal 741.Dp Cm x 742print a short word in hexadecimal 743.Dp Cm X 744print a long word in hexadecimal 745.Dp Cm b 746print a byte in octal 747.Dp Cm c 748print a byte as a character 749.Dp Cm s 750print a string of characters terminated by a null byte 751.Dp Cm f 752print a single precision real number 753.Dp Cm g 754print a double precision real number 755.Dp 756.Pp 757Symbolic addresses are specified by preceding the name with an ``&''. 758Registers are denoted by ``$rN'' where N is the number of the register. 759Addresses may be expressions made up of other addresses and 760the operators ``+'', ``-'', and indirection (unary ``*''). 761.Dp 762.Ss Miscellaneous Commands 763.Tw Ic 764.Tp Ic gripe 765Invoke a mail program to send a message to the person in charge of 766.Nm dbx . 767.Tp Ic help 768Print out a synopsis of 769.Nm dbx 770commands. 771.Tp Ic quit 772Exit 773.Nm dbx . 774.Tp Cx Ic sh 775.Cx \&\ \& 776.Ar command-line 777.Cx 778Pass the command line to the shell for execution. 779The SHELL environment variable determines which shell is used. 780.Tp Cx Ic source 781.Cx \&\ \& 782.Ar filename 783.Cx 784Read 785.Nm dbx 786commands from the given 787.Ar filename . 788.Tp 789.Sh ENVIRONMENT 790.Nm Dbx 791utilizes the following environment variables: 792.Ds I 793EDITOR 794HOME 795PATH 796SHELL 797.De 798.Sh FILES 799.Dw .dbxinit 800.Di L 801.Dp Pa a.out 802object file 803.Dp Pa .dbxinit 804initial commands 805.Dp 806.Sh SEE ALSO 807.Xr cc 1 , 808.Xr mod l , 809.Xr f77 1 , 810.Xr pc 1 811.Sh HISTORY 812.Nm Dbx 813appeared in 4.2 BSD. 814.Sh BUGS 815.Nm Dbx 816suffers from the same ``multiple include'' malady as did 817.Nm sdb . 818If you have a program consisting of a number of object files 819and each is built from source files that include header files, 820the symbolic information for the header files is replicated in 821each object file. 822Since about one debugger start-up is done for each link, 823having the linker 824.Xr ld 1 825re-organize the symbol information 826would not save much time, though it would reduce some of the 827disk space used. 828.Pp 829This problem is an artifact of the unrestricted semantics 830of #include's in C; for example an include file can contain 831static declarations that are separate entities for each file 832in which they are included. 833However, even with Modula-2 there is a substantial amount of duplication 834of symbol information necessary for inter-module type checking. 835.Pp 836Some problems remain with the support for individual languages. 837Fortran problems include: 838inability to assign to logical, logical*2, complex 839and double complex variables; 840inability to represent parameter constants 841which are not type integer or real; 842peculiar representation for the values of dummy procedures 843(the value shown for a dummy procedure is actually 844the first few bytes of the procedure text; 845to find the location of the procedure, 846use ``&'' to take the address of the variable). 847