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