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