User Commands
STANDARDS CONFORMANCE cd: SVID2, XPG2, XPG3
VARIABLES
HOME CDPATH
default working directory directories to search for directory.
SEE ALSO
pwd(l), sh(l), chdir(2).
EXTERNAL INFLUENCES
International Code Set Support
Single- and multi-byte character code sets are supported.
STANDARDS CONFORMANCE cd: SVID2, XPG2, XPG3
CDB(l) Series 300 Only CDB(1)
NAME
cdb, fdb, pdb - C, FORTRAN, Pascal symbolic debugger SYNOPSIS
cdb [-d dir] [-r file] [-p file] [-P process ID] [-L] [-i file] [-0 file] [-e file] [-5 num]
[objectfile [corefile]]
£db [ cdb options ] pdb [ cdb options ] TABLE OF CONTENTS
DESCRIPTION USER INTERFACE
Environment
Window Oriented Interface Line Oriented Interface CONVENTIONS
Notational Conventions Variable Name Conventions Expression Conventions Procedure Call Conventions COMMANDS
Window Mode Commands File Viewing Commands Display Formats Data Viewing Commands Stack Viewing Commands Job Control Commands Breakpoint Commands Assertion Control Commands Signal Control Commands Record and Playback Commands Macro Definition Commands Miscellaneous Commands ADOPTING AN EXISTING PROCESS DIAGNOSTICS
WARNINGS AUTHOR FILES SEE ALSO
EXTERNAL INFLUENCES DESCRIPTION
Cdb, [db, and pdb are alternate names for a source level debugger for C, HP FORTRAN, and HP Pascal programs. It provides a controlled environment for their execution.
Objectfile is an executable program file having zero or more of its component modules compiled with the -g option of cc(l), [c(l), or pc(l). The support module /usr/lib/end.o must be included as the last object file in the list of those linked, except for libraries included with the -1 option to ld(l) (done automatically with -g option). The default for objectfile is a.out.
Corefile is a core image from a failed execution of objectfile. The default corefile is core.
Options
130 (Section 1) - 1 - HP-UX Release 7.0: September 1989
COB(1) Series 300 Only COB(1)
-d dir Specify dir as an alternate directory where source files are located. If a source file is not found in any alternate directory, the current directory is searched last.
-r file Specify a record file which is invoked immediately (for overwrite, not for append). See the section below entitled Record and Playback Commands for a description of this feature.
-p file Spedfy a playback file which is invoked immediately. See the section below entitled Record and Playback Commands for a description of this feature.
-p process ID Specify the process ID of an existing process that you wish to debug (see Adopting an Existing Process below).
-L Use the line-oriented interface even if the debugger can support the window-oriented interface on the terminal type specified by $TERM.
-i file Redirect standard input to the child process from the designated file.
- 0 file Redirect standard output from the child process to the designated file.
-e file Redirect standard error from the child process to the designated file.
-S num Set the size of the string cache to num bytes (default is 1024, which is also the minimum). The string cache holds data read from objectfile.
Only one objectfile and one corefile are allowed per debugging session. The program (objectfile) is not invoked as a child process until an appropriate job control command is given (see Job Control Commands below). The same program can be restarted many times as different child processes during a single debugging session.
At startup, cdb executes commands from the file .cdbrc (.fdbrc for FORTRAN and .pdbrc for Pascal) if it exists in the user's home directory as specified by the environment variable HOME.
This debugger is a complex, interactive tool whose many capabilities are often limited only by your imagination. However, the debugger is also only a "window" to the world of the program being debugged and the system on which it runs. If something puzzling happens, consult a manual that describes the program or the system to better understand the behavior.
USER INTERFACE Environment
Cdb reads the environment variable TERM to determine the applicable terminal type and user interface. The locale category LC_CTYPE, which defaults to the 'C' locale, is used to determine the character-set and semantics to be used when reading or writing character and string data.
Window Oriented Interface
This user interface is only supported on HP terminals with memory-lock. The top of the screen is a "window" into the current source file and the bottom of the screen is for the debugger and user program input and output. Separating the two areas is a line (in inverse video) indicating the current file, procedure, and line number. Within the source file window, a ">,, points to the current location (which might not be the location at which the user program is currently stopped).
To determine the number of lines and columns, the debugger looks first for the environment variables LINES and COLUMNS. If these environment variables are not found, the debugger uses the line and column information from the /usr/lib/terminfo file for the terminal type found in the environment variable TERM.
Note that a $TERM setting of 'hp' implies that the terminal supports memory-lock, which is not true of some HP terminals (such as the HP2621). For this and other cases, the debugger attempts to provide a window-oriented interface even if the terminal itself does not provide the
CDH(l) Series 300 Only CDHO)
necessary capabilities. For such situations, the debugger can be forced into the line oriented interface mode by invoking it with the -L command line option.
Line Oriented Interface
This is the user interface currently supported on HP terminals without memory-lock and on all non-HP terminals. This interface does not use windows. The source file is displayed one line at a time, but some commands compensate by supplying more information than with the "win-dow" interface.
CONVENTIONS
The debugger remembers the current file, procedure, line, and data location that you have been viewing (although not necessarily executing) most recently. Many commands use these current locations as defaults, and set them as a result. Keep this in mind when deciding what a com-mand does in any particular situation.
For example, if you stop in procedure "abc", then view procedure "def", then ask for the value of local variable "xyz", the debugger assumes that the variable belongs to procedure "def".
Notational Conventions
Most commands are of the form "[modifier] command [options]". Numeric modifiers before and after commands can be any numeric expression. They need not be just simple numbers. A blank is required before any numeric option. Multiple commands on one line must be separated by "i".
These are common modifiers and other special notations:
(A I B I C) Anyone of A or B or C is required. commands inside "{},, are ignored.
The number of repetitions specified for a command.
A stack depth, as printed by the "t" command. The top procedure is at a depth of zero. A negative depth acts like a depth of zero. Stack depth usually means
"exactly at the specified depth ", not "the first instance at or above the specified depth".
Any expression, but with limitations stated below.
A file name.
A style for printing data. Used with Data Viewing Commands.
A number that refers to a particular line in a file. numbers can be used anywhere a constant is allowed.
- 3 - HP-UX Release 7.0: September 1989
CDB(t)
proc var
Series 300 Only
A procedure, function, or subroutine name.
A variable name. parameter or local variable named var, as before.
proc.depth.var Use the instance of proc that is at depth depth (exactly), instead of the most recent instance. This is very useful for debugging recursive procedures where there are multiple instances on the stack.
:var Search for a global (not local) variable named either var or _var, in that order.
Dot is shorthand for the last thing you viewed. It has the same size it did when you last viewed it. For example, if you look at a long as a char, then "."
is considered to be one byte long. This is useful for treating things in uncon-ventional ways, like changing the second highest byte of a long without changing the rest of the long. Dot can be treated like any other variable.
NOTE: "." is the name of this magic location. If you use it, it is dereferenced
Names are limited to 100 characters.
$pc, $fp, $sp, $dO, etc.
$long are available as alternate ways of looking at $result.
This lets you see and modify the current child process signal number.
This lets you see and modify the current language. The current language determines the operators that can be used in expressions, and the format in
CDB(l)
"FORTRAN", "Pascal" and "default" ("default" means use whatever language the current procedure is written in).
Alters the behavior of the "print" command when printing character data.
Values that can be assigned are "ascii", "native", and "raw". Default is
"ascii". "Ascii" causes all non-ASCII characters to be displayed as octal-escapes. "Native" causes unprintable characters, as determined by the locale category (environemnt variable) LC_CTYPE, to be displayed as octal-escapes.
"Raw" causes all bytes to be output unaltered. This also affects the default display format for character types (see Display Formats).
This lets you see and modify the current source line number, which is also sett-able with a number of different commands.
This lets you see the current amount of memory (bytes) allocated at run-time for use by the debugger itself.
This lets you see and modify the number of machine instructions the debugger will step while in a non-debuggable procedure before setting an up-level effectively constitute a single floating point accelerator instruction will be treated as a single instruction for machine level single-stepping and display.
If $fpa is set to a non-zero value, $fpa_reg indicates which address register is used in floating point accelerator instruction sequences. A 0 corresponds to register aD, 1 to at etc. The default value is 2.
To see all the special variables, including the predefined ones, use the "Is" (list specials) com-mand.
You can also look up code addresses with proc#line
which searches for the given procedure name and line number (which must be an executable line within proc) and uses the code address of that line. Just referring to a procedure proc by name uses the code address of the entry point to that procedure.
Expression Conventions
Every expression has a value, even simple assignment statements, as in C. "Naked" expression values (those which aren't command modifiers) are always printed unless the next token is ";"
(command separator) or "},, (command block terminator). Thus breakpoint and assertion com-mands are normally silent. To force an expression result to be printed, follow the expression with "In" (print in normal format).
Integer constants might begin with "0" for octal or "Ox" or "OX" for hexadecimal (the forms are equivalent). If followed immediately by "I" or "L", they are forced to be of type long. like-wise, "U" and "U" force the type to unsigned. "ul" or "UL" corresponds to unsigned long. If no suffix is used, the smallest type in which the value will fit is used.
Floating point constants must be of the form digits.digits[eIEldIDILII[+I-]digits][fIF], for example, "1.0", "3.14e8f", or "26.62D-31". One or more leading digits is required to avoid
134 (Section 1) - 5 - HP-UX Release 7.0: September 1989
CDB(l) Series 300 Only CDB(1)
confusion with "." (dot). A decimal point and one or more following digits is required to avoid confusion for some command formats. If the exponent doesn't exactly fit the pattern shown, it is not taken as part of the number, but as separate token(s). The "d" and "D" exponent forms are allowed for compatibility with FORTRAN. The "1" and "L" exponent forms are allowed for compatibility with Pascal.
In the absence of a suffix character, the constant is assumed to be of type "double" (8-byte IEEE real). The suffixes "f" and "F" cause the value to be evaluated as type "float" (4-byte IEEE real). Unless a direct assignment is made, float types are converted to type double before the expression is evaluated.
Character constants must be entered in " and are treated as integers. String constants must be entered in 1111 and are treated like "char
*"
(Le. pointer to char). Character and string constants can contain the standard backslashed escapes understood by the C compiler and the echo(1) command, including "\a", "\b", "\f", "\n", "\r", ,,\t", "\?", "\\", ,,\ ''', "\nnn", and"\xnnn ... ". In the case of hex-escapes, the longest possible value is evaluated and then trun-cated to size of the destination type (1 byte). "\<newline>" is not supported,.neither in quotes nor at the end of a command line.
Expressions are composed of any combination of variables, constants, and C operators. If the debugger is invoked as cdb, the C operator "sizeof" is also available. If the debugger is invoked as [db, FORTRAN operators are also available and FORTRAN meanings take precedence where there is a conflict. The same is true for Pascal if the debugger is invoked as pdb. The user may create a composite program built from two or more of the supported languages. The
$lang variable may be set to "default" so that the debugger recognizes the language for the code currently being debugged.
If there is no active child process and no corefile, you can only evaluate expressions containing constants.
Expressions approximately follow the C rules of promotion, e.g. 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 doesn't normally permit it, the number is cast to long and used that way. For example, the C binary operator "-,, (bit invert) applied to the constant "3.14159" is the same as 11-3".
Note that "=" means "assign" except for Pascal; to test for equality, use "==" or ".EQ." for FORTRAN. In Pascal, "=" is a comparison operator; use ":=" for assignments. For example, if you invoke the debugger as cdb, then set "$lang = Pascal", you must say "$lang := C" to return to C.
Use "/ /" for division, instead of "/", to distinguish from display formatting (see Data Viewing Commands).
The special unary operator "$in" (not to be confused with debugger local variables) evaluates to 1 (true) if the operand is an address inside a debuggable procedure and $pc (the current child process program location) is also in that procedure, else it is 0 (false). For example, "$in main"
is true if the child process is stopped in mainO.
If the first expression on a line begins with "+" or "_", use "0" around it to distinguish from the "+" and "-" commands (see Data Viewing Commands). Parentheses might also be needed to distinguish an expression from a command it modifies.
You can attempt to dereference any constant, variable, or expression result using the C
"*"
operator. If the address is invalid, an error is given.
CDB(l) Series 300 Only
Type casting is allowed. For simple types, the syntax is identical to C. For example:
(short) size (double *) mass_ptr
CDB(l)
These casts are limited to char, short, long, int, unsigned, float, and double, appropriate com-binations of these keywords, and singie ievei pointer types. Aiso supported are structure and union pointer type dereferences. For example:
bacptr = &bar (struct foo) &bar (struct foo) bacptr
Both of these casts treat "bar" as a struct of type "foo" during printing. Structure and union casts may 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 an array declared as
"x[S][6][7]" in C, "x(S,6,7)" in FORTRAN, or "x[l..S;2 .. 6,3 .. 7]" in Pascal. Referencing it simply as
"x" is the same as just "x" in C, the address of "x(I,I,I)" in FORTRAN, or the address of
"x[1,2,3]" in Pascal. Referencing it as "x[4]" is the same as "& (x[4][0][0])" in C, the address of
"x(I,I,4)" in FORTRAN, or the address of "x[4,2,3]" in Pascal.
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.
Array indices are not checked against declared bounds.
String constants are stored in a magic buffer in the file /usr/lib/end.o, 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 reaches the end of the buffer, it goes back and reuses it from the beginning. In general this doesn't cause any problems. However, if you use very long strings, or if you assign a string constant to a global pointer, problems could arise.
Procedure Call Conventions
136
Procedures can be invoked from the command line, even within expressions. For example:
xyz = $abc
*
(3+
def (ghi - 1, jkl, "Hi Mom"»calls procedure "def" when its value is needed in the expression.
Any breakpoints encountered during command line procedure invocation are handled as usual.
However, the debugger has only one active command line at a time. If it stops in a called pro-cedure for any reason, the remainder (if any) of the old command line is discarded with notice given.
If you attempt to call a procedure when there is no active child process, one is started for you as if you gave a single-step command first. Unfortunately, this means that the data in corefile (if any) might disappear or be reinitialized.
If you send signal SIGINT (e.g., hit the BREAK key) while in a called procedure, the debugger aborts the procedure call and returns to the previous stopping point (the start of the main pro-gram for a new process).
You can call any procedure that is in your objectfile, even if it is not debuggable (was not com-piled with debug on). For example, assume that you reference "printfO" in your program, so the code for it is in your objectfile. Then you can enter on the command line:
printf ("This works! %d %c\n", 9, '?');
If you wonder what procedures are available, do a list labels command ("11").
(Section 1) - 7 - HP-UX Release 7.0: September 1989
CDB(1) Series 300 Only CDB(l) default is the same as with ksh(l) except that CDBHIST defaults to n$HOMEj.cdbhist n.
Window Mode Commands code, and the bottom half is the corresponding assembly instructions.
td Toggle disassembly mode. When in disassembly mode, the source window displays source code and half assembly instructions.
Display general registers when the debugger is in assembly (non-split screen) mode. When the value of a register changes, the register is highlighted until after the next command is executed. These registers can be modified by using the debugger special variables $dO through $a7. When displaying the general registers or floating point registers, the line dividing the registers from the assembly code displays corresponding special registers. For registers containing flags, each flag is represented by a letter. A lowercase letter indicates that the flag is off, while uppercase means on. '
Display floating point registers when the debugger is in assembly (non-split screen) mode. When the value of a register changes, that register is highlighted until after the next command. If more than one set of floating-point registers exist, you will be queried about which you want displayed.
Scroll the floating-point register display forward four lines.
Scroll the floating-point register display back four lines.
Set the size of the source viewing window. It is normally set to fifteen lines for a twenty-four line terminal.
Update the screen to reflect the current location. This command is best used as part of an assertion: the assertion a u will show step-by-step progress through the program.
Clear and redraw the screen.
File Viewing Commands
These commands might change the current viewing position, but they do not affect the next statement to be executed in the child process, if any.
These commands might change the current viewing position, but they do not affect the next statement to be executed in the child process, if any.