DBX(1) UNIX Reference Manual DBX(1) NNAAMMEE ddbbxx - debugger SSYYNNOOPPSSIISS DDbbxx [--rr] [--ii] [--kk] [--II _d_i_r] [--cc _f_i_l_e] [_o_b_j_f_i_l_e [_c_o_r_e_d_u_m_p]] DDEESSCCRRIIPPTTIIOONN DDbbxx is a tool for source level debugging and execution of programs under UNIX. The _o_b_j_f_i_l_e is an object file produced by a compiler with the ap- propriate flag (usually --gg) specified to produce symbol information in the object file. Currently, cc(1), f77(1), pc(1), and the DEC Western Research Laboratory Modula-2 compiler, mod(l), produce the appropriate source information. The machine level facilities of ddbbxx can be used on any program. The object file contains a symbol table that includes the names of all the source files translated by the compiler to create it. These files are available for perusal while using the debugger. If a file named _c_o_r_e exists in the current directory or a _c_o_r_e_d_u_m_p file is specified, ddbbxx can be used to examine the state of the program when it faulted. If the file ._d_b_x_i_n_i_t exists in the current directory then the debugger commands in it are executed. DDbbxx also checks for a ._d_b_x_i_n_i_t in the user's home directory if there isn't one in the current directory. The command line options and their meanings are: --rr Execute _o_b_j_f_i_l_e immediately. If it terminates successfully ddbbxx exits. Otherwise the reason for termination will be reported and the user offered the option of entering the debugger or letting the program fault. DDbbxx will read from /_d_e_v/_t_t_y when --rr is specified and standard input is not a terminal. --ii Force ddbbxx to act as though standard input is a terminal. --kk Map memory addresses, useful for kernel debugging. --II _d_i_r Add _d_i_r to the list of directories that are searched when look- ing for a source file. Normally ddbbxx looks for source files in the current directory and in the directory where _o_b_j_f_i_l_e is lo- cated. The directory search path can also be set with the uussee command. --cc _f_i_l_e Execute the ddbbxx commands in the _f_i_l_e before reading from stan- dard input. Unless --rr is specified, ddbbxx just prompts and waits for a command. EExxeeccuuttiioonn aanndd TTrraacciinngg CCoommmmaannddss rruunn [_a_r_g_s] [<< _f_i_l_e_n_a_m_e] [>> _f_i_l_e_n_a_m_e] rreerruunn [_a_r_g_s] [<< _f_i_l_e_n_a_m_e] [>> _f_i_l_e_n_a_m_e] Start executing _o_b_j_f_i_l_e, passing _a_r_g_s as command line argu- ments; << or >> can be used to redirect input or output in the usual manner. When rreerruunn is used without any arguments the previous argument list is passed to the program; otherwise it is identical to rruunn. If _o_b_j_f_i_l_e has been written since the last time the symbolic information was read in, ddbbxx will read in the new information. ttrraaccee [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n] ttrraaccee _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n] ttrraaccee _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n] ttrraaccee _e_x_p_r_e_s_s_i_o_n aatt _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n] ttrraaccee _v_a_r_i_a_b_l_e [iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] [iiff _c_o_n_d_i_t_i_o_n] 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 ddeelleettee command). The first argument describes what is to be traced. If it is a _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r, then the line is printed immediately prior to being executed. Source line 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 then every time it is called, information is printed telling what routine called it, from what source line it was called, and what param- eters were passed to it. In addition, its return is noted, and if it's a function then the value it is returning is also printed. If the argument is an _e_x_p_r_e_s_s_i_o_n with an aatt clause then 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 substan- tially 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 iinn _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n restricts tracing information to be printed only while executing inside the given procedure or function. _C_o_n_d_i_t_i_o_n is a boolean expression and is evaluated prior to printing the tracing information; if it is false then the in- formation is not printed. ssttoopp iiff _c_o_n_d_i_t_i_o_n ssttoopp aatt _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n] ssttoopp iinn _s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [iiff _c_o_n_d_i_t_i_o_n] ssttoopp _v_a_r_i_a_b_l_e [iiff _c_o_n_d_i_t_i_o_n] Stop execution when the given line is reached, procedure or function called, variable changed, or condition true. ssttaattuuss [>> _f_i_l_e_n_a_m_e] Print out the currently active ttrraaccee and ssttoopp commands. ddeelleettee _c_o_m_m_a_n_d-_n_u_m_b_e_r ... The traces or stops corresponding to the given numbers are removed. The numbers associated with traces and stops are printed by the ssttaattuuss command. ccaattcchh _n_u_m_b_e_r ccaattcchh _s_i_g_n_a_l-_n_a_m_e iiggnnoorree _n_u_m_b_e_r iiggnnoorree _s_i_g_n_a_l-_n_a_m_e 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 a 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. ccoonntt _i_n_t_e_g_e_r ccoonntt _s_i_g_n_a_l-_n_a_m_e Continue execution from where it stopped. If a signal is specified, the process continues as though it received the signal. Otherwise, the process is continued as though it had not been stopped. Execution cannot be continued if the process has ``finished'', that is, called the standard procedure ``exit''. DDbbxx does not allow the process to exit, thereby letting the user to examine the program state. sstteepp Execute one source line. nneexxtt Execute up to the next source line. The difference between this and sstteepp is that if the line contains a call to a pro- cedure or function the sstteepp command will stop at the beginning of that block, while the nneexxtt command will not. rreettuurrnn [_p_r_o_c_e_d_u_r_e] Continue until a return to _p_r_o_c_e_d_u_r_e is executed, or until the current procedure returns if none is specified. ccaallll _p_r_o_c_e_d_u_r_e (_p_a_r_a_m_e_t_e_r_s) Execute the object code associated with the named procedure or function. PPrriinnttiinngg VVaarriiaabblleess aanndd EExxpprreessssiioonnss 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 chosen and the message ``[using Ar qualified name]'' is printed. The name resolution procedure may be overridden by qualify- ing an identifier with a block name, e.g., ``module.variable'' For C, source files are treated as modules named by the file name without ``.c''. Expressions are specified with an approximately common subset of C and Pascal (or equivalently Modula-2) syntax. Indirection can be denoted us- ing either a prefix ``*'' or a postfix ``^'' and array expressions are subscripted by brackets (``[]''). The field reference operator (``.'') 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 ``_t_y_p_e-_n_a_m_e (_e_x_p_r_e_s_s_i_o_n)''. When there is no corresponding named type the special constructs ``&_t_y_p_e-_n_a_m_e'' and ``$$_t_a_g-_n_a_m_e'' can be used to represent a pointer to a named type or C structure tag. aassssiiggnn _v_a_r_i_a_b_l_e==_e_x_p_r_e_s_s_i_o_n Assign the value of the expression to the variable. dduummpp [_p_r_o_c_e_d_u_r_e] [>> _f_i_l_e_n_a_m_e] Print the names and values of variables in the given procedure, or the current one if none is specified. If the procedure given is ``.'', then the all active variables are dumped. pprriinntt _e_x_p_r_e_s_s_i_o_n [,, _e_x_p_r_e_s_s_i_o_n ...] Print out the values of the expressions. wwhhaattiiss _n_a_m_e Print the declaration of the given name, which may be qualified with block names as above. wwhhiicchh _i_d_e_n_t_i_f_i_e_r Print the full qualification of the given identifer, i.e. the outer blocks that the identifier is associated with. uupp [_c_o_u_n_t] ddoowwnn [_c_o_u_n_t] Move the current function, which is used for resolving names, up or down the stack _c_o_u_n_t levels. The default _c_o_u_n_t is 1. wwhheerree Print out a list of the active procedures and function. wwhheerreeiiss _i_d_e_n_t_i_f_i_e_r Print the full qualification of all the symbols whose name matches the given identifier. The order in which the symbols are printed is not meaningful. AAcccceessssiinngg SSoouurrccee FFiilleess /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[/] ?_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n[?] Search forward or backward in the current source file for the given pattern. eeddiitt [_f_i_l_e_n_a_m_e] eeddiitt _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n-_n_a_m_e Invoke an editor on _f_i_l_e_n_a_m_e or the current source file if none is specified. If a _p_r_o_c_e_d_u_r_e or _f_u_n_c_t_i_o_n 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. ffiillee [_f_i_l_e_n_a_m_e] Change the current source file name to _f_i_l_e_n_a_m_e. If none is specified then the current source file name is printed. ffuunncc [_p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n] Change the current function. If none is specified then 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. lliisstt [_s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r [,,_s_o_u_r_c_e-_l_i_n_e-_n_u_m_b_e_r] lliisstt _p_r_o_c_e_d_u_r_e/_f_u_n_c_t_i_o_n List the lines in the current source file from the first line number to the second inclusive. 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. uussee _d_i_r_e_c_t_o_r_y-_l_i_s_t Set the list of directories to be searched when looking for source files. CCoommmmaanndd AAlliiaasseess aanndd VVaarriiaabblleess aalliiaass _n_a_m_e _n_a_m_e aalliiaass _n_a_m_e _s_t_r_i_n_g aalliiaass _n_a_m_e (_p_a_r_a_m_e_t_e_r_s) ``_s_t_r_i_n_g'' 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, then 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'', one can say alias rr rerun To define an alias called ``b'' that sets a stop at a particular line one can say alias b(x) ``stop at x'' Subsequently, the command ``b(12)'' will expand to ``stop at 12''. sseett _n_a_m_e[_e_x_p_r_e_s_s_i_o_n] The sseett command defines values for debugger variables. The names of these variables cannot conflict with names in the pro- gram being debugged, and are expanded to the corresponding ex- pression within other commands. The following variables have a special meaning: $frame Setting this variable to an address causes dbx to use 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 out out characters, integers, offsets from registers, or character pointers respective- ly in hexadecimal. $listwindow The value of this variable specifies the number of lines to list around a function or when the lliisstt 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 is useful for kernel debugging. $unsafecall $unsafeassign When ``$unsafecall'' is set, strict type checking is turned off for arguments to subroutine or function calls ( _e ._g. in the ccaallll statement). When ``$unsafeassign'' is set, strict type checking between the two sides of an aassssiiggnn statement is turned off. These variables should be used only with great care, because they severely limit dbx's usefulness for detecting errors. uunnaalliiaass _n_a_m_e Remove the alias with the given name. uunnsseett _n_a_m_e Delete the debugger variable associated with _n_a_m_e. MMaacchhiinnee LLeevveell CCoommmmaannddss ttrraacceeii [_a_d_d_r_e_s_s] [_c_o_n_d] ttrraacceeii [_v_a_r_i_a_b_l_e] [aatt_a_d_d_r_e_s_s] [iiff_c_o_n_d] ssttooppii [_a_d_d_r_e_s_s] [iiff_c_o_n_d] ssttooppii [aatt] [_a_d_d_r_e_s_s] [iiff_c_o_n_d] Turn on tracing or set a stop using a machine instruction address. sstteeppii nneexxttii Single step as in sstteepp or nneexxtt, but do a single instruction rather than source line. _a_d_d_r_e_s_s,_a_d_d_r_e_s_s/[_m_o_d_e] _a_d_d_r_e_s_s/[_c_o_u_n_t][_m_o_d_e] Print the contents of memory starting at the first _a_d_d_r_e_s_s and continuing up to the second _a_d_d_r_e_s_s or until _c_o_u_n_t items are printed. If the address is ``.'', the address following the one printed most recently is used. The _m_o_d_e 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: ii print the machine instruction dd print a short word in decimal DD print a long word in decimal oo print a short word in octal OO print a long word in octal xx print a short word in hexadecimal XX print a long word in hexadecimal bb print a byte in octal cc print a byte as a character ss print a string of characters terminated by a null byte ff print a single precision real number gg print a double precision real number Symbolic addresses are specified by preceding the name with an ``&''. 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 ``+'', ``-'', and indirection (unary ``*''). MMiisscceellllaanneeoouuss CCoommmmaannddss ggrriippee Invoke a mail program to send a message to the person in charge of ddbbxx. hheellpp Print out a synopsis of ddbbxx commands. qquuiitt Exit ddbbxx. sshh _c_o_m_m_a_n_d-_l_i_n_e Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used. ssoouurrccee _f_i_l_e_n_a_m_e Read ddbbxx commands from the given _f_i_l_e_n_a_m_e. EENNVVIIRROONNMMEENNTT DDbbxx utilizes the following environment variables: EDITOR HOME PATH SHELL FFIILLEESS _a._o_u_t object file ._d_b_x_i_n_i_t initial commands SSEEEE AALLSSOO cc(1), mod(l), f77(1), pc(1) HHIISSTTOORRYY DDbbxx appeared in 4.2 BSD. BBUUGGSS DDbbxx suffers from the same ``multiple include'' malady as did ssddbb. 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 de- bugger start-up is done for each link, having the linker ld(1) re- organize the symbol information would not save much time, though it would reduce some of the disk space used. 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; peculiar representation for the values of dummy procedures (the value shown for a dummy procedure is ac- tually the first few bytes of the procedure text; to find the location of the procedure, use ``&'' to take the address of the variable).