DBX(1) COMMAND REFERENCE DBX(1) NAME dbx - debugger SYNOPSIS dbx [ -r ] [ -i ] [ -k ] [ -I dir ] [ -c file ] [ -t { xterm | tterm } ] [ -X ] [ -x ] [ objfile [ coredump [ kernel ] ] ] DESCRIPTION The dbx debugger is a tool for source-level debugging and execution of programs under UNIXr. The objfile is an object file produced by a compiler with the appropriate flag (-g) specified to produce symbol information in the object file. Currently, cc(1), f77(1), and pc(1) produce the appropriate source information. The machine level facilities of dbx can be used on any program. The object file contains a symbol table that includes the name of all source files translated by the compiler to create it. These files are available for perusal while using the debugger. If a file named core exists in the current directory or a coredump file is specified, dbx can be used to examine the state of the program when it faulted. If a coredump file is specified, then a kernel file may also be specified. (This would only be needed if the coredump file was produced under a different release of VMUNIXr other than the one currently running.) If the file .dbxinit exists in the current directory then the debugger commands in it are executed. The dbx debugger also checks for a .dbxinit file in the user's home directory if there isn't one in the current directory. The command line options and their meanings are listed here. -r Execute objfile immediately; if it terminates successfully dbx exits. Otherwise the reason for termination will be reported and the user is offered the option of entering the debugger or letting the program fault. /& The debugger reads from /dev/tty when -r is specified and standard input is not a terminal. -i Force dbx to act as though standard input is a terminal. -k Map memory addresses; useful for kernel debugging. Printed 4/6/89 1
DBX(1) COMMAND REFERENCE DBX(1) -I dir Add dir to the list of directories searched when looking for a source file. dbx normally looks for source files in the current directory and the directory where objfile is located. The directory search path can also be set with the use command described below. -c file Execute dbx commands in the file before reading from standard input. The following options are not supported for 6130 and 4132 workstations. -t { xterm | tterm } Used with -X to attach a subprocess to its own xterm or tterm window. For more information, refer to xdb(1). -X Use an experimental X window user interface. For more information, refer to xdb(1). -x Use an experimental X window user interface. For more information, refer to xdb(1). Unless -r is specified, dbx prompts and waits for a command. Execution and Tracing Commands run [args] [< filename] [> filename] rerun [args] [< filename] [> filename] Start executing objfile, passing args as command line arguments; < or > can be used to redirect input or output in the usual manner. When rerun is used without any arguments the previous argument list is passed to the program; otherwise it is identical to run. If objfile has been written since the last time the symbolic information was read in, dbx reads in the new information. trace [in procedure/function] [if condition] trace source-line-number [if condition] trace procedure/function [in procedure/function] [if condition] trace expression at source-line-number [if condition] trace variable [in procedure/function] [if condition] Have tracing information printed when the program is executed. A number is associated with the command that is used to turn the tracing off (see the delete command in this manual reference page). The first argument describes what is to be traced; if it is a source-line-number, then the line is printed immediately prior to being executed. Source line Printed 4/6/89 2
DBX(1) COMMAND REFERENCE DBX(1) numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon, e.g. "mumble.p":17. If the argument is a procedure or function name every time it is called information is printed telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it's a function the value it is returning is also printed. If the argument is an expression with an at clause the value of the expression is printed whenever the identified source line is reached. If the argument is a variable then the name and value of the variable is printed whenever it changes. Execution is substantially slower during this form of tracing. If no argument is specified then all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. The clause in procedure/function restricts tracing information to be printed only while executing inside the given procedure or function. Condition is a boolean expression and is evaluated prior to printing the tracing information; if it is false then the information is not printed. stop if condition stop at source-line-number [if condition] stop in procedure/function [if condition] stop variable [if condition] Stop execution when the given line is reached, procedure or function is called, variable is changed, or condition true. status [> filename] Print out the currently active trace and stop commands. delete command-number ... The traces or stops corresponding to the given numbers are removed. The numbers associated with traces and stops are printed by the status command. catch number catch signal-name Printed 4/6/89 3
DBX(1) COMMAND REFERENCE DBX(1) ignore number ignore signal-name Start or stop trapping a signal before it is sent to the program; this is useful when a program being debugged handles signals such as interrupts. A signal may be specified by number or by name (e.g., SIGINT). Signal names are case insensitive and the ``SIG'' prefix is optional. By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM, and SIGKILL. cont integer cont signal-name Continue execution from where it stopped. If execution was stoped by a signal other then SIGINT, SIGTSTP, or SIGTRAP (breakpoint or single stepping), then that signal will be sent to the process. If a signal is specified with the cont, the process continues as though it also received that signal. Otherwise, the process is continued as though it had not been stopped. This implies that the only way for the process to recieve SIGINT, SIGTSTP, or SIGTRAP is via the cont command with that signal specified. Execution cannot be continued if the process has ``finished'', that is, if the process has called the standard procedure ``exit''. The dbx program does not allow the process to exit, thereby letting the user examine the program state. step Execute one source line. next Execute up to the next source line. The difference between this and step is that if the line contains a call to a procedure or function the step command will stop at the beginning of that block, while the next command will not. return [procedure] Continue until a return to procedure is executed, or until the current procedure returns if none is specified. call procedure(parameters) Execute the object code associated with the named procedure or function. Printing Variables and Expressions Names are resolved first using the static scope of the current function, then using the dynamic scope if the name is not defined in the static scope. If static and dynamic searches do not yield a result, an arbitrary symbol is Printed 4/6/89 4
DBX(1) COMMAND REFERENCE DBX(1) chosen and the message ``[using qualified name]'' is printed. The name resolution procedure may be overridden by qualifying an identifier with a block name, e.g., ``module.variable''. For C, source files are treated as modules named by the file name without the .c extension. Expressions are specified with an approximately common subset of C and Pascal (or equivalently, Modula-2) syntax. Indirection can be denoted using either a prefix (*) or a postfix (^), and array expressions are subscripted by brackets ([ ]). The field reference operator dot (.) can be used with pointers as well as records, making the C operator -> unnecessary (although it is supported). Types of expressions are checked; the type of an expression may be overridden by using type-name(expression). When there is no corresponding named type the special constructs &type-name and $$tag-name can be used to represent a pointer to a named type or C structure tag. assign variable = expression Assign the value of the expression to the variable. dump [procedure] [> filename] Print the names and values of variables in the given procedure, or the current procedure if none is specified. If the procedure given is dot (.), then all active variables are dumped. print expression [, expression ...] Print the values of the expressions. whatis name Print the declaration of the given name, which may be qualified with block names as previously described. which identifier Print the full qualification of the given identifier, i.e. the outer blocks with which the identifier is associated. up [count] down [count] Move the current function, which is used for resolving names, up or down the stack count levels. The default count is 1. whatsat expression Take the value of the expression to be an address and print it in symbolic form. where Printed 4/6/89 5
DBX(1) COMMAND REFERENCE DBX(1) Print a list of the active procedures and function. whereis identifier Print the full qualification of all symbols whose name matches the given identifier; the order in which the symbols are printed is not meaningful. Accessing Source Files /regular expression[/] ?regular expression[?] Search forward or backward in the current source file for the given pattern. edit [filename] edit procedure/function-name Invoke an editor on filename or the current source file if none is specified. If a procedure or function name is specified, the editor is invoked on the file that contains it; which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable EDITOR to the name of the desired editor. file [filename] Change the current source file name to filename; if none is specified the current source file name is printed. func [procedure/function] Change the current function; if none is specified print the current function. Changing the current function implicitly changes the current source file to the one that contains the function; it also changes the current scope used for name resolution. list [source-line-number [, source-line-number]] list procedure/function List the lines in the current source file from the first line number to the second inclusive line number; if no lines are specified, the next 10 lines are listed. If the name of a procedure or function is given, lines n-k to n+k are listed where n is the first statement in the procedure or function and k is small. use directory-list Set the list of directories searched when looking for source files. Command Aliases and Variables alias name name Printed 4/6/89 6
DBX(1) COMMAND REFERENCE DBX(1) alias name ``string'' alias name (parameters) ``string'' When commands are processed, dbx first checks to see if the word is an alias for either a command or a string; if it is an alias, dbx treats the input as though the corresponding string (with values substituted for any parameters) had been entered. For example, to define an alias rr for the command rerun, type: alias rr rerun To define an alias called b that sets a stop at a particular line, type: alias b(x) ``stop at x'' Subsequently, the command b(12) expands to stop at 12. There are a number of default aliases. Aliases can be displayed by typing alias without any parameters. set name [= expression] The set command defines values for debugger variables; the names of these variables cannot conflict with names in the program being debugged, and are expanded to the corresponding expression within other commands. The following variables have a special meaning: $frame Setting this variable to an address, dbx uses the stack frame pointed to by the address for doing stack traces and accessing local variables. This facility is of particular use for kernel debugging. $hexchars $hexints $hexoffsets $hexstrings When set, dbx prints characters, integers, offsets from registers, or character pointers (respectively) in hexadecimal. $listwindow The value of this variable specifies the number of lines listed around a function or when the list command is given without any parameters. Its default value is 10. $mapaddrs Setting (unsetting) this variable causes dbx to start (stop) mapping addresses. As with $frame, this command is useful for kernel Printed 4/6/89 7
DBX(1) COMMAND REFERENCE DBX(1) debugging. $unsafecall $unsafeassign When $unsafecall is set, strict type checking is turned off for arguments to subroutine or function calls (e.g. in the call statement). When $unsafeassign is set, strict type checking between the two sides of an assign statement is turned off. These variables should be used with great care because they severely limit dbx's usefulness for detecting errors. $repeat_step When $repeatstep is set, a carriage return entered on an otherwise blank line will repeat the last command if this was a step, stepi, next, or nexti. $repeat_examine When $repeatexamine is set, a carriage return entered on an otherwise blank line will repeat the last command if this was an examine command. The starting address of the repeated command is set to one past the last address displayed by the previous command. $clobber When $clobber is set, a command with redirected output will overwrite the output file. $octin $decin $hexin $hexwhenleadingzero These variables control the interpretation of numbers given as input to dbx. Numbers beginning with 0x, 0t, and 0o are taken as hex, decimal, and octal, respectively. A number with a leading zero will be taken as hex if a $hexin or $hexwhenleadingzero is set, decimal when $decin is set and as an octal otherwise. Numbers without a leading zero are taken as hex if $hexin is set, octal if $octin is set, and decimal otherwise. unalias name Remove the alias with the given name. unset name Delete the debugger variable associated with name. Printed 4/6/89 8
DBX(1) COMMAND REFERENCE DBX(1) Machine Level Commands listi Same as list with the addition of printing the disassembled code for each source line printed. tracei [address] [if cond] tracei [variable] [at address] [if cond] stopi [address] [if cond] stopi [at] [address] [if cond] Turn on tracing or set a stop using a machine instruction address. stepi nexti Single step as in step or next, but do a single instruction rather than source line. address ,address/ [mode] address / [count] [mode] Print the contents of memory starting at the first address and continuing up to the second address or until count items are printed. If the address is dot (.) the address following the one printed most recently is used. The mode specifies how memory is to be printed; if it is omitted the previous mode specified is used. The initial mode is X. The following modes are supported: i print the machine instruction d print a short word in decimal D print a long word in decimal o print a short word in octal O print a long word in octal x print a short word in hexadecimal X print a long word in hexadecimal b print a byte in octal c print a byte as a character s print a string of characters terminated by a null byte f print a single precision real number g print a double precision real number Symbolic addresses are specified by preceding the name with an ampersand (&). Registers are denoted by $rN where N is the number of the register. Addresses may be expressions made up of other addresses and the operators plus (+), minus (-), and indirection (unary *). Miscellaneous Commands Printed 4/6/89 9
DBX(1) COMMAND REFERENCE DBX(1) gripe Invoke a mail program to send a message to the person in charge of dbx. help Print out a synopsis of dbx commands. quit Exit dbx. sh command-line Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used. source filename Read dbx commands from the given filename. FILES a.out Object file .dbxinit Initial commands VARIABLES EDITOR The editor to use when the edit command is issued. SHELL The shell to use when the sh command is issued. HOME The user's home directory; used to find dbxinit. The dbx program suffers from the same ``multiple include'' malady as did sdb(1). If you have a program consisting of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file. Since about one debugger start-up is done for each link, having the linker (ld) reorganize the symbol information would not save much time, though it would reduce some of the disk space used. CAVEATS This problem is an artifact of the unrestricted semantics of #include's in C; for example, an include file can contain static declarations that are separate entities for each file in which they are included. However, even with Modula-2 there is a substantial amount of duplication of symbol information necessary for inter-module type checking. Some problems remain with the support for individual languages. Fortran problems include inability to assign to logical, logical*2, complex and double complex variables, inability to represent parameter constants which are not type integer or real, and peculiar representation for the Printed 4/6/89 10
DBX(1) COMMAND REFERENCE DBX(1) values of dummy procedures (the value shown for a dummy procedure is actually the first few bytes of the procedure text; to find the location of the procedure, use the & sign to take the address of the variable). If objfile has been written since the last time symbolic information was read in, dbx is supposed to read in the new information, however it does not do this. Recursive function invocation can confuse the where and return commands. Calling functions from dbx does not always work. SEE ALSO cc(1), f77(1), pc(1), and xdb(1). Printed 4/6/89 11
%%index%% na:216,66; sy:282,494; de:776,2423;3487,4072;7847,3157;11292,3374;14954,2906;18148,3325;21761,2745;24794,3806;28888,3352;32528,799; fi:33327,149; va:33476,968; ca:34444,876;35608,732; se:36340,182; %%index%%000000000231