HP 3000 Manuals HP 3000 Manuals
Entering Commands The HP Symbolic Debugger keeps track of the current file, procedure, line and data locations of the executing program. The current file, procedure, and line are always displayed in the source and location windows, but their values do not necessarily correspond to the point at which execution is suspended. However, the debugger always knows at any point in time where to continue execution. For example, you can stop execution to view a different source file, then continue where you left off. Most debugger commands assume that the command applies to the current location and its scope. For example, if you stop in procedure abc and then view procedure def and ask for the value of a local variable that exists in both, the debugger returns the value of that variable as it exists in def.
NOTE def must be a caller of abc, or the variable must be statically declared, for its value to be meaningful.
The general format of most debugger commands is: command [ location] [ command arguments] [ command-list] Commands are one- or two-word names or abbreviations for these names. A location is a particular line, procedure or file. (It can also be an address in some instances). Command arguments are explained in the description of each command, in this chapter and a command list is a sequence of commands separated by semicolons. Using Uppercase and Lowercase Some HP Symbolic Debugger commands are case-sensitive. The two cases are treated differently by the debugger. For example: s or step Lowercase "s" tells the HP Symbolic Debugger to single step to the next executable statement and step into a procedure, if necessary. S or Step Uppercase "S" tells the HP Symbolic Debugger single step to the next executable statement and step over a procedure call. Abbreviating Commands You can enter commands in their complete spelled-out form (long form) or in an abbreviated form (short form). Generally, you can abbreviate one-word commands using the first character of the word. Abbreviate two-word commands using the first character of each word in the command (do not leave a space between the two characters). If you use the long form, you can leave a space between words. For example: { w } number Changes the size of the source window. { window} { db } [ number] Deletes the selected breakpoint number. { delete breakpoint} Some debugger commands are not abbreviated by following the previous rules. Refer to the individual command syntax in this chapter to find abbreviations for these commands. Entering Variable Names When using HP Symbolic Debugger, use the same names for variables as are used in the source program. Global variables may be preceded by a colon to distinguish them from local variables of the same name. In the following example, the global variable gvar is preceded by a colon to distinguish it from a local variable gvar. p :gvar
NOTE Use of variable names in debugger commands is normally case insensitive; for example, gvar is the same variable as GVAR. This may be changed with the tc (toggle case) command.
In addition to program variables the debugger allows you to use special variables. Special variables are used like regular program variables, but are maintained by the debugger. You assign values to them using the assignment operator of the language you're using. You can only assign integer values to special variables. Special variables have names that are prefixed by a $. Some special variable are predefined and have special meaning. Other special variables are user-defined, variables to which the user can assign values. Special variable names can be up to 98 characters long, but it is recommended that you limit the names of special variables to 80 characters long for display purposes. The first time you reference special variables, they are created and set to their initial values. Special variables can be used for the duration of the debugging session or you can redefine them. For example, if you enter the following command (in HP FORTRAN 77 or HP C), p $xyz = 3*4 the special variable $xyz is created and assigned the value of 12. To view special variables (except hardware registers), use the ls (list specials) command. There are several special variables that are available; all but user-defined special variables are predefined by the debugger. The special variables are: * $var Represents user-defined variables. They are of type long integer and do not take on the type of any expressions assigned to them. * Hardware Registers $r0...$r31 General Registers $f0...$f31 Floating Point Registers $pc Program Counter $sp Stack Pointer $dp Data Pointer $arg0...$arg3 Argument Registers $ret0...$ret1 Return-value Registers Represents the HP-PA registers. Some registers have both a register number and a "register use" name. For example, $arg3 and $r23 refer to the same register. The lr (list registers) command provides a list of accessible registers and their contents. See the section "Data Viewing and Modification Commands" in this chapter for more information. For example: >p $sp\x $sp = 0x68023208 For more information on the HP-PA registers, refer to the HP Precision Architecture and Instruction Reference Manual and the HP Procedure Calling Conventions Manual. * $result References the return value from the last procedure called from the command line. $short and $long are used as other ways of viewing $result. Where possible, $result takes on the type of the procedure. $result is only meaningful if an integer value is returned. * $lang Allows you to view and modify the current source language flag for expression evaluations. Valid values for $lang are COBOL, FORTRAN, Pascal, C, and default. For example, if $lang is set to C, the debugger expects HP C syntax, regardless of the language you are debugging. When $lang is set to "default", any language expression syntax is expected to be the same as the source language of the procedure currently being viewed. * $line Displays the current source line number (the next statement to be executed). * $malloc Allows you to see the amount of memory (in bytes) currently allocated by the debugger for its own use. This does not reflect memory-use of the program being debugged. * $step Allows you to see and change the number of machine instructions the debugger steps through while in a non-debuggable procedure, before setting an uplevel breakpoint and free-running to it. (this is where a breakpoint is set immediately after the return location in the non-debuggable procedure's caller). This situation occurs only when the program is executing in a single step or assertion mode. Entering Expressions An expression is a symbolic or mathematical representation. Expressions consist of variables, constants and operators, or any syntactically correct combination of these items. The HP Symbolic Debugger evaluates user expressions as if they are part of the high-level language being debugged and, therefore, uses the same operators and assignment rules as the high-level language. See Appendices B, C, D, and E for a list of operators that you can use with each language. Note that the symbolic debugger tries as much as possible to let you write expressions with the same syntax as the current language. You can change the current language by setting the value of the special variable $lang. By default, this variable is set to the language of the program you are debugging. The $in operator, a special unary operator, evaluates to true (1) if the operand is a debuggable procedure and if $pc (the current child process program location) is in that procedure; otherwise, $in is false (0). For example, $in load_month_table is true if the child process is currently suspended in load_month_table. Also, $addr, the unary operator for retrieving the address of a variable and $sizeof, another unary operator for retrieving the byte size of a variable, are available for all languages. The rules in each language for character and string constants are as follows: * For HP COBOL II, HP FORTRAN 77 and HP Pascal, string constants are represented by one or more characters, enclosed by single quotation marks ( ' ) or double quotation marks ( " ). * For HP C, single quotation marks enclose single characters for character constants. Double quotation marks enclose zero or more characters for string constants. * Character and string constants can contain standard backslashed escapes as understood by the HP C compiler, including those shown in table 4-1. Table 4-1. Escape Sequences --------------------------------------------------------------------------------------------- | | | | Character | Description | | | | --------------------------------------------------------------------------------------------- | | | | backspace | \b | | | | --------------------------------------------------------------------------------------------- | | | | form feed | \f | | | | --------------------------------------------------------------------------------------------- | | | | carriage return | \r | | | | --------------------------------------------------------------------------------------------- | | | | horizontal tab | \t | | | | --------------------------------------------------------------------------------------------- | | | | vertical tab | \v | | | | --------------------------------------------------------------------------------------------- | | | | backslash | \\ | | | | --------------------------------------------------------------------------------------------- | | | | single quote | \' | | | | --------------------------------------------------------------------------------------------- | | | | double quote | \" | | | | --------------------------------------------------------------------------------------------- | | | | bit pattern | \nnn (octal digits) | | | | --------------------------------------------------------------------------------------------- | | | | new line | \n | | | | --------------------------------------------------------------------------------------------- * Expressions can also contain the symbolic constants listed in table 4-2. Table 4-2. Symbolic Constants --------------------------------------------------------------------------------------------- | | | | Language | Constants | | | | --------------------------------------------------------------------------------------------- | | | | HP COBOL II | SPACES | | | | | | ZEROS | | | | --------------------------------------------------------------------------------------------- | | | | HP Pascal | NIL | | | | | | MAXINT | | | | | | MININT | | | | | | TRUE | | | | | | FALSE | | | | --------------------------------------------------------------------------------------------- | | | | HP FORTRAN 77 | .TRUE. | | | | | | .FALSE. | | | | --------------------------------------------------------------------------------------------- | | | | HP C | NONE | | | | --------------------------------------------------------------------------------------------- If you do not have an active child process, you can only evaluate expressions containing constants. Floating point constants must be of the form: [e] [E] [d] digits.digits[D] digits [l] [L] [+] [-] For example, any of the following is in the correct form: 1.0 3.14e8 26.62D-31 One or more leading digits is required to avoid confusion with . (dot). A decimal point and one or more following digits is required to avoid confusion for some command formats. If the exponent does not exactly fit the pattern shown, it is not taken as part of the number, but as separate tokens. The d and D exponent forms are allowed for compatibility with HP FORTRAN 77. The l and L exponents forms are allowed for compatibility with HP Pascal. In the absence of a suffix character, the constant is assumed to be of type double (8 byte IEEE real). Expressions approximately follow the HP C language rules of promotion. In other words, char, short, and int become long and float becomes double. If either operand is a double, floating math is used. If either operand is unsigned, unsigned math is used. Otherwise, normal (integer) math is used. Results are then cast to proper destination types for assignments. If a floating point number is used with an operator that does not normally permit it, the number is cast to long and used that way. For example, the HP C binary number ~ (bit invert) applied to the constant 3.14159 is the same as ~3. Note that = means assign in all languages but HP Pascal and HP COBOL II; to test for equality, use .EQ. for HP FORTRAN 77 and == for HP C. In HP Pascal, = is a comparison operator; use := for assignments. For example, suppose you invoked the debugger on a C program, then set $lang to Pascal using this command: p $lang = Pascal If you want to return to HP C, you must use the := operator as follows: p $lang := C If you invoked the debugger on an HP COBOL II program, then you would use the move command as follows to return to HP Pascal: p move Pascal to $lang You can dereference any constant, variable, or expression result using the HP C * operator. If the address is invalid, an error is given. Type casting is allowed. For simple types, the syntax is identical to HP C. For example: (short) size (double *) mass_ptr These casts are limited to char, short, long, int, unsigned, float, double, approximate combinations of these keywords, and single level pointer types. Also supported are structure and union pointer type dereferences. For example: bat_ptr = &bat (struct fob) &bat (struct fob) bat_ptr Both of these casts treat bat as a struct of type fob during printing. Structure and union pointer casts can only include the keyword struct or union and an appropriate tag. No pointers (*) are allowed. The argument of the cast is simply treated as an address. Whenever an array variable is referenced without giving all its subscripts, the result is the address of the lowest element referenced. For example consider the following declared arrays: HP FORTRAN 77 x(5,6,7) HP Pascal x[1..5,2..6,3..7] HP C x[5][6][7] Referencing it simply as x is the same as the following: HP FORTRAN 77 x(1,1,1) HP Pascal x[1,2,3] HP C x If a not-fully-qualified array reference appears on the left side of an assignment, the value of the right-hand expression is stored into the element at the address specified. String constants are stored in a buffer in the xdbend.lib.sys file which you link with your program. The debugger starts storing strings at the beginning of this buffer, and moves along as more assignments are made. If the debugger reached the end of the buffer, it goes back and reuses it from the beginning. This does not usually cause any problems. However, if you use very long strings, or if you assign a string constant to a global pointer, problems could arise. Entering Procedure Calls You can include calls to procedures in expressions. You can call any executable procedure from the command line whether or not it was compiled with debugger information. You can use the lp (list procedures) command to list procedures in an executable program file. The following command evaluates an expression that calls the procedure ref and uses its return value: p $xyz = $abc*(3 + ref (ghi - 1, jkl, "Hi Folks")) An argument list must follow each procedure call, even if it is empty. When a procedure is called, the following might occur: * The HP Symbolic Debugger has one active command line at a time. During command line procedure calls, breakpoints reached during program execution are treated as usual (by suspending execution as specified). If execution stops in a called procedure, the remainder of the old command line is ignored and you are informed of this. * If you try to call a procedure when the child process is not active, then a child process is started by the debugger. This process is similar to using the single step command after starting the debugger. Window Mode Commands Window mode commands let you control what is displayed on the screen. The window mode commands are: * fr (floating point registers) * gr (general registers) * sr (special registers) * td (toggle disassembly) * ts (toggle screen) * u (update) * U (Update) * w (window) The source window displays source lines in a program. In disassembly mode, the top five lines of the screen show the floating point, general or special registers (the register window) followed by assembly language instructions (the assembly window). In split-screen mode, the top part of the screen displays source code followed by the corresponding assembly language instructions. fr (floating point registers) {fr } {floating point registers} Displays the HP-PA floating point registers in the register window when the debugger is in disassembly mode. Each register appears as a two-word pair (two sets of eight hexadecimal digits). When the value of a register changes, that register is highlighted until after the next command. Use the special variables $f0 through $f15 to modify these registers.
CAUTION Modification of floating point registers is not recommended during normal debugger usage.
For more information about the HP-PA floating point registers, see appendix F "Registers Displayed by HP Symbolic Debugger in Disassembly Mode" or refer to the HP Precision Architecture and Instruction Reference Manual. gr (general registers) {gr } {general registers} Displays the HP-PA general registers in the register window when the debugger is in disassembly mode. When the value of a register changes, that register is highlighted until after the next command. Use the debugger's special variables $r0 through $r31 (or equivalent usage names such as $arg3) to modify these registers. When displaying the general registers or the floating point registers, the line dividing the registers from the assembly code displays the current space number, pc offset, privilege level, sar and psw. The psw is displayed as a string of letters, with each letter representing one flag bit in the psw. For example, b stands for branch taken trap and n stands for nullify. A lower case letter indicates that the bit is OFF while upper case indicates it is ON. You cannot modify the sar or psw registers. For more information about the HP-PA general registers, see appendix F "Registers Displayed by HP Symbolic Debugger in Disassembly Mode" or refer to the HP Precision Architecture and Instruction Reference Manual. sr (special registers) {sr } {special registers} Displays the special registers (space and control) when the debugger is in disassembly mode. When the value of a special register changes, that register is highlighted until after the next command. You cannot modify the special registers. For more information about the HP-PA special registers, see appendix F "Registers Displayed by HP Symbolic Debugger in Disassembly Mode" or refer to the HP Precision Architecture and Instruction Reference Manual. td (toggle disassembly) {td } {toggle disassembly} Toggles the source window between disassembly mode and source mode. When in disassembly mode, this command displays the assembly language instructions that correspond to the source code as well as one of the three sets of registers (floating point, general or special). When in disassembly mode, the single step command steps one machine instruction at a time (rather than one source statement at a time). The assembly language display of each instruction consists of: the source line number, the address in hexadecimal, the address in the form of the nearest label plus the offset and the actual symbolic assembly instruction and operands. ts (toggle screen) {ts } {toggle screen} Toggles the source window between all source or all assembly and split-screen mode. In split-screen mode, the source window displays both source code and corresponding assembly instructions. Single stepping occurs at either the source statement or the assembly instruction level, depending on the part of the split-screen in which you are single stepping. The stepping mode is displayed in the line separating the source and assembly windows. u (update) {u } {update} Updates the source and location windows to show the current location of the user program. This command is useful in an assertion. For example, this command: a {u} will continuously update the screen to show the execution of the program as it runs. U (Update) {U } {Update} Clears the screen of data and redraws the screen. Use this command if the screen gets corrupted by a system-wide announcement that overwrites your session. w (window) {w } number {window} If your terminal supports windowing, this command changes the size of the source window to the number of lines that you specify. Enter a number from 1 to 21 (the default is 15). Changing the size of the source window also changes the size of the command window. If your terminal does not support windowing, this command prints the specified number of lines surrounding the current line. If no number is specified, the last number used with the w (window) command is used again. You can press RETURN to repeat this command. The next specified number of lines will be displayed. File Viewing Commands The file viewing commands let you view program source code. The file viewing commands are: * + * - * / * ? * D (Directory) * ld (list directories) * lf (list files) * L (Location) * n (next) * N (Next) * v (view) * V (View) * va (view address) + + [number] Moves forward in the current file the specified number of lines (or the specified number of instructions in disassembly mode). If you do not enter a number, the next line (or instruction) becomes the current line (or instruction). You can press a RETURN to repeat this command. If your terminal supports windowing, a new group of lines are displayed. If it does not support windowing, only the new current line and its line number are displayed. - - [number] Moves the specified number of lines (or the specified number of instructions in disassembly mode) backward in the current file and updates the windows. The default is one line (or instruction) before the current line (or instruction). You can press RETURN to repeat this command. If your terminal supports windowing, a new group of lines (or instructions) are displayed. If it does not support windowing, only the new current line and its line number are displayed. / / [string] Searches forward in the file for the specified string. Searches wrap around the end of the file. If you do not enter a string, the last one that you entered is used again. The string must be literal; wild cards are not supported. You can select case sensitivity for string searches with the tc (toggle case) command. Initially, searches are case insensitive. ? ? [string] Searches backward in the current file for a specific pattern. Searches wrap around the beginning of the file. If you do not enter a string, the last search string is used again. The string must be literal; wild cards are not supported. You can select case sensitivity for string searches with the tc (toggle case) command. Initially, searches are case insensitive. D (Directory) {D } "dir" {Directory} Adds the directory that you specify to the list of directory search paths for source files. You can add more that one directory, but only one can be added at a time. Directories are searched in the order that they are added. ld (list directories) {ld } {list directories} Lists all the alternate directories that are searched when the debugger tries to locate the source files. lf (list files) {lf } [string] {list files} Lists all source files containing executable statements that were compiled to build the executable file. Code address ranges are shown for each file. Only files containing executable code are shown. If a string is specified, only those files beginning with this string are listed. This command also lists any include files containing executable code with their code addresses. A file can appear several times if it contains include files. An example of the output is: 0: STDIO.PUB.C 0x00001834 to Ox00002524 1: TREE1.SRC.PROJECT 0x00002530 to 0x00003210 2: TREEGLOBS.PUB.PROJECT 0x00003344 to 0x00004002 3: TREE2.NEWSRC.PROJECT 0x00004040 to 0x00006832 L (Location) {L } {Location} Displays in the command window the current file, procedure, line number and the source text for the current point of execution. This command allows you to determine where you are in the program and is useful when included in an assertion or breakpoint command list. For example: >L doproc.c: eval_q: 8: if (qp != NULL) { You cannot press RETURN to repeat this command. n (next) {n } {next} Repeats the previous search (/ or ?) command. N (Next) {N } {Next} Repeats the previous search (/ or ?) command, searching in the opposite direction. v (view) {v } [location] {view} Displays one source window forward from the current source window. One line from the previous window is preserved for context. If your terminal does not support windowing, only the new source line is displayed. A location can be a particular line, procedure, or any text file, whether used in the program or not. For COBOL, a location can also be a paragraph or section. Using the location option causes the specified location to become the current location, and the source at the specified location is then displayed in the source window. The source location window is adjusted accordingly. If a procedure (proc) name is specified for the location, the procedure's first executable line becomes the current line. You can press RETURN to repeat this command. If a location was given, subsequent RETURN's move forward from that point.
NOTE Filenames entered with the v (view) command cannot be qualified by a path name. This means the debugger must be able to determine where the file is either by using the -d option when running the debugger or by using the D (Directory) command. Note that the debugger uses the same pathnames for finding source as were used during compilation.
V (View) {V } [depth] {View} Displays the text for the procedure at the depth on the program stack that you specify. If you do not enter a depth, the current active procedure is used. This command is normally used to view the current point of suspension when the current viewing location is elsewhere in the program. If your terminal supports windowing, the new lines are displayed in the window. Pressing RETURN lets you view successive windows. If your terminal does not support windowing, the current line (including its line number and description) is displayed. Pressing RETURN lets you view the next line in sequence. va (view address) {va } address {view address} Displays in the source window assembly code at the specified address. A specified address can be an absolute address or symbolic code label with an optional offset (for example, _start + 0x20). This command is used in disassembly mode only.