dbx(1) dbx(1)NAME dbx - debugs and executes programs SYNOPSIS dbx [-c file] [-D] [-i] [-I dir]... [-r] [objfile [coredump]] ARGUMENTS -c file Executes the dbx commands in the specified file before reading from standard input. -D Installs Macintosh low-memory globals into the dbx symbol table, allowing dbx to disassemble A-line traps generated for A/UX Toolbox routines. This option is useful for debugging applications that call the A/UX Toolbox. -i Causes dbx to act as though standard input is a terminal. This option enables you to manually input dbx commands from the keyboard to the command line. -I dir Adds the specified directory, dir, to the list of directories that are searched when dbx is looking for a source file. Normally dbx looks for source files in the current directory and in the directory where objfile is located. The directory search path can also be set with the use command. objfile [coredump] Specifies the object file to debug. Such files are produced by a compiler with the appropriate flag (usually -g), which places symbol information in the object file. 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 you are using the debugger. If a file named core exists in the current directory or if a coredump file is specified, dbx can be used to examine the state of the program when it was terminated. -r Causes dbx to execute objfile before accepting debugging commands. If objfile runs successfully as indicated by a zero exit status, dbx exits. Otherwise, dbx reports the reason for termination and offers you the option of either entering the debugger or letting the program terminate. When this option is specified January 1992 1
dbx(1) dbx(1)and the standard input is not a terminal, dbx reads from /dev/tty. Unless this option is specified, dbx waits for an explicit run command or another debugger command. DESCRIPTION dbx is a tool for source-level debugging and execution of programs under UNIX(Reg.). The machine-level facilities of dbx can be used on any program. If the file dbxinit exists in the current directory, the debugger commands in it are executed. Your home directory will also be checked for a dbxinit file if one does not exist in the current directory. When you are debugging A/UX applications that use the A/UX Toolbox, it is useful to use the -D option and to ignore the IOT, IO, and URG signals. The ignore command is described in the next section, ``Execution and Tracing Commands.'' Execution and Tracing Commands The execution and tracing commands follow. call procedure(parameters) Executes the object code associated with the named procedure or function. catch number catch signal-name ignore number ignore signal-name Start or stop trapping of the signal before it is sent to the program. This method is useful when a program being debugged handles interrupt signals. You can specify a signal by number or by a name (for example, SIGINT). Signal names are case insensitive and the SIG prefix is optional. By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM, and SIGKILL. If you are debugging A/UX applications that call the A/UX Toolbox, it is advisable to ignore SIGIOT, SIGIO, and SIGURG because these signals are used by A/UX Toolbox routines. cont integer cont signal-name Continue execution from the point at which it stopped. If a signal is specified, the process continues as though it received the signal. Otherwise, the process continues as though it had not been stopped. Execution cannot continue if the process called the 2 January 1992
dbx(1) dbx(1)standard procedure exit. The dbx program does not allow the process to exit, so you can examine the program state. delete command-number... Removes the trace or stop corresponding to each given command-number argument. (You can print the numbers associated with traces and stops can be printed by using the status command.) next Executes up to the next source line. The difference between next 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, whereas the next command will not. return [procedure] Continues until a return to procedure is executed if procedure is specified. If no procedure is specified, execution continues until the current procedure returns. run [args] [<file][>file] rerun [args] [<file][>file] Start executing objfile, passing the args arguments as command-line arguments. The symbols < and > 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 this command is identical to run. If objfile argument has been written since the last time the symbolic information was read, dbx will read the new information. status > [filename] Prints the currently active trace and stop commands. step Executes one source line. stop if condition stop at source-line-number [if condition] stop in procedure-or-function [if condition] stop variable [if condition] Stop execution when the given line is reached, the given procedure or function is called, the given variable is changed, or the given condition is true. trace [in procedure-or-function] [if condition] trace source-line-number [if condition] trace procedure-or-function [in procedure-or-function] [if condition] trace expression at source-line-number [if condition] January 1992 3
dbx(1) dbx(1)trace variable in procedure-or-function [if condition] Print tracing information when the program is executed. A number is associated with the command that is used to turn the tracing off. (See the description of delete command later in this list.) The first argument describes what is to be traced. If it is a source-line-number argument, then the line is printed immediately before it is executed. Numbers for source line in a file other than the current one must be preceded by the name of the file in quotation marks and a colon, as shown here: "mumble.p":17 If the argument is a procedure or function name, every time the procedure or function is called, dbx displays information that tells you 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 is a function, the value it returns is also printed. If the argument is an expression with an at clause, the value of the expression is printed when the identified source line is reached. If the argument is a variable, the name and value of the variable are printed whenever they change. Execution is substantially slower during this form of tracing. If no argument is specified, all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. The clause in procedure-or-function causes tracing information to be printed only while dbx is being executed inside the given procedure or function. The condition argument is a Boolean expression evaluated before the tracing information is printed. If the value is FALSE, the information is not printed. Variables and Expressions The dbx debugger resolves variables first in terms of the static scope of the current function, then in terms of 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 qualified name]'' is printed. You can override the 4 January 1992
dbx(1) dbx(1)name-resolution procedure by qualifying an identifier with a block name, for example, module.variable. For C, source files are treated as modules named by the filename without the .c extension. Expressions are specified with an approximately common subset of C and Pascal syntax. You can denote indirection by using either a prefix asterisk (*) or a postfix caret (^). Array expressions are subscripted by brackets ([ ]). The field reference dot operator (.) can be used with pointers as well as records, making the C arrow operator (- >) unnecessary (although it is supported). Types of expressions are checked. You can override the type of an expression by using the type-name(expression) construct. When there is no corresponding named type, you can use the special constructs &type-name and $$tag-name to represent a pointer to a named type or C structure tag. The commands are: assign variable=expression Assigns the value of the expression to the variable. dump [procedure] > [filename] Prints the names and values of variables in the given procedure, or the current one if none is specified. If the replacement value for procedure is supplied as period (.), then the names and values of all active variables are printed. print expression[, expression ]... Prints the values of the given expressions. up [count] down [count] Move the current function, which is used for resolving names, up or down the stack count levels. The default for count is 1. whatis name Prints the declaration of the given name, which can be qualified with block names as described earlier. where Prints a list of the active procedures and functions. whereis identifier Prints the full qualification of all symbols whose names match the given identifier. The order in which the symbols are printed is not meaningful. January 1992 5
dbx(1) dbx(1)which identifier Prints the full qualification of the given identifier, that is, the outer blocks with which the identifier is associated. Accessing Source Files vs Navigating through You can access source files by using these commands instead of navigating through your source code: /regular expression[/] ?regular expression[?] Search forward or backward in the current source file for the given pattern. edit [filename] edit procedure-or-function-name Invoke an editor on the specified file or on the current source file if no filename argument is specified. If a procedure or function name is specified, the editor is invoked on the file that contains that procedure or function. Which editor is invoked by default depends on the installation. You can override the default by setting the environment variable EDITOR to the name of the desired editor. file [filename] Changes the current source filename to the specified filename. If none is specified, the current source filename is printed. func [procedure-or-function] Changes the current function to the one specified. If none is specified, this command prints 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-number1[, source-line-number2]] list procedure-or-function List the lines in the current source file from the specified source-line-number1 to source-line-number2, inclusive. If no lines are specified, the next $listwindow lines (the default is 10) 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 defined by the variable $listwindow. use directory-list Sets the list of directories to be searched when looking for source files. (Also see the description of 6 January 1992
dbx(1) dbx(1)the -I option in the ``Arguments'' section earlier in this manual page.) If no directory-list argument is provided for the use command, the current directory list is displayed. Command Aliases and Variables The command aliases and variables commands follow. alias name name alias name "string" alias name(parameters) "string" Check to see if name is an alias for either a command or a string when commands are processed. If it is an alias, then treats the input as though the corresponding string (with values substituted for any parameters) had been entered. For example, the command alias rr rerun can be used to define an alias rr for the rerun command. The command alias b(x) can be used to define an alias b that sets a stop at the passed line number (x). For example, the command b(12) expands to stop at 12 when b is aliased, as shown earlier. set name[=expression] Defines values for debugger variables. The names of these variables must not 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 Causes dbx to use the stack frame pointed to by the address for performing stack traces and accessing local variables when this variable is set to an address. This facility is of particular use for kernel debugging. $hexchars January 1992 7
dbx(1) dbx(1)$hexints $hexoffsets $hexstrings Cause dbx to print out characters, integers, offsets from registers, or character pointers, respectively, in hexadecimal when one of these is set. $listwindow Specifies a number of lines to be listed by the list command. The default value is 10. $mapaddrs Causes dbx to start mapping addresses. Unsetting this variable causes address mapping to stop. As with $frame, this variable is useful for kernel debugging. $unsafecall $unsafeassign Turn off strict type-checking for arguments to the subroutine or function calls (for example, in the call statement) when the $unsafecall variable is set. When the $unsafeassign variable 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 the usefulness of dbx in detecting errors. unalias name Removes the alias with the given name. unset name Deletes the debugger variable associated with the specified name. Machine-Level Commands You specify symbolic addresses by preceding the name of a register with an ampersand (&). Registers are denoted by $rn where n is the number of the register. Addresses can be expressions made up of other addresses and the operators +, -, and indirection (unary *). The machine-level commands as described below: 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 8 January 1992
dbx(1) dbx(1)(.), the address following the one printed most recently is used. The mode argument specifies how memory is to be printed; if it is omitted, the mode last specified is used. The initial mode is X, which prints long words in hexadecimal. The following modes are supported: b Prints a byte in octal. c Prints a byte as a character. d Prints a short word in decimal. D Prints a long word in decimal. f Prints a single-precision real number. g Prints a double-precision real number. i Prints the machine instruction. o Prints a short word in octal. O Prints a long word in octal. s Prints a string of characters terminated by a null byte. x Prints a short word in hexadecimal. X Prints a long word in hexadecimal. stepi nexti Step by a single instruction rather than by a source line. These variables single-step as the step and next variables do. 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 the machine- instruction address specified by address. Miscellaneous Commands help Prints out a synopsis of dbx commands. quit Exits dbx. sh command-line Passes the command line to the shell for execution. January 1992 9
dbx(1) dbx(1)The SHELL environment variable determines which shell is used. source filename Reads dbx commands from the specified file. FILES .dbxinit File containing initial commands /usr/ucb/dbx Executable file a.out Object file SEE ALSO c89(1), cc(1) ``dbx Reference'' in A/UX Development Tools 10 January 1992