NAME

xdb − C, FORTRAN, and Pascal Symbolic Debugger

SYNOPSIS

xdb [−d dir] [−r file] [−p file] [−P process ID] [−L] [−i file] [−o file] [−e file] [−S num] [objectfile [corefile]]

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 and Modification 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
SYMBOL TABLE DEPENDENCIES
DIAGNOSTICS
WARNINGS
DEPENDENCIES
AUTHOR
FILES
SEE ALSO
EXTERNAL INFLUENCES

DESCRIPTION

Xdb is 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 with zero or more of its component modules compiled with debug options turned on (that is, enabled by the −g flag of cc(1), fc(1), or pc(1)). The support module (/usr/lib/end.o for the series 300, /usr/lib/xdbend.o for the series 800) must be included as the last object file linked, except for libraries included with the −l option to ld(1). The default for objectfile is a.out. 

Corefile is a core image from a failed execution of objectfile.  The default for corefile is core. 

Options

−d dir Specify an alternate directory for source files.   Alternate directories are searched in the order given. If a source file is not found in any alternate directory, the current directory is searched last. When searching for the source file <file> in an alternate directory <altdir>, xdb first attempts to open <altdir>/<dirname>/<basename>. If this fails, xdb attempts to open <altdir>/<basename> (see basename(1)).

−r file Specify a record file, which is invoked immediately for overwrite, but not for append (see Record and Playback Commands below). 

−p file Specify a playback file, which is invoked immediately (see Record and Playback Commands below). 

−P process ID Specify the process ID of an existing process that the user wishes to debug (see Adopting an Existing Process below). 

−L Force the line-oriented interface, even if xdb can support the window-oriented interface on the terminal type specified by environment variable TERM. 

−i file Redirect standard input to the child process from the designated file or character device. 

−o file Redirect standard output from the child process to the designated file or character device. 

−e file Redirect standard error from the child process to the designated file or character device. 

−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 the objectfile. 

There can only be one objectfile and one corefile per debugging session (activation of the debugger).  The program (objectfile) is not invoked as a child process until you give an appropriate command (see the Job Control Commands section below).  The same program may be restarted, as different child processes, many times during one debugging session. 

At startup, xdb executes commands from the file .xdbrc, 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

Xdb 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 xdb 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, xdb looks first for the environment variables LINES and COLUMNS.  If these environment variables are not found, xdb 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 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 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 "window" interface. 

CONVENTIONS

The debugger remembers the current file, procedure, line, and data location that you have been viewing (not necessarily executing) most recently.  Many commands use these current locations as defaults, and many commands set them as a result.  Keep this in mind when deciding what a command 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 "command [location] [command-arguments] [command-list]". Numeric modifiers 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 ";". 

These are common modifiers and other special notations:

(A | B | C) Any one of A or B or C is required. 

[A | B | C] Any one of A or B or C is optional. 

command-list A series of debugger commands, separated by ";", entered on the command line or saved with a breakpoint or assertion.  Semicolons are ignored (as commands) so they can be freely used as command separators.  Commands may be grouped with "{}" for the "a", "b", "if", "i" (the abbreviated "if" command), and "!" commands.  In all other cases commands inside "{}" are ignored. 

count The number of repetitions specified for a command. 

depth 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."

expr Any expression, but with limitations stated below. 

file A file name. 

format A style for printing data (see Data Viewing Commands below). 

line A number that refers to a particular line in a file. 

location A particular line in a file (and its corresponding address in the user’s program if there exists executable code for that line).  location has the following general forms:

    line
    file [ : line ]
    proc [ : proc [ . . . ] ]  [ : ( line | #label ) ]

number A specific, constant number (e.g. "9", not "4+5").  Floating point (real) numbers may be used any place a constant is allowed. 

proc A procedure (or function, or subroutine) name. 

var A variable name. 

Variable Name Conventions

Variables are referenced exactly as they are named in your source file(s).  Case sensitivity is controlled by the "tc" command. 

If you are interested in the value of some variable var, there are a number of ways of getting it, depending on where and what it is:

var Search the stack for the most recent instance of the current procedure.  If found, see if var is a parameter or local variable of that procedure.  If not, search for a global variable named var. 

proc:var Search the stack for the most recent instance of proc.  If found, see if it has a 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 var. 

. Dot is shorthand for the last thing you viewed (see the Data Viewing Commands section below).  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 unconventional ways, like changing the second highest byte of a long without changing the rest of the long.  Dot may be treated like any other variable. 

NOTE:  "." is the name of this magic location.  If you use it, it is dereferenced like any other name.  If you want the address of something that is, say, 30 bytes farther on in memory, do not say ".+30".  That would take the contents of dot and add 30 to it.  Instead, say "&.+30", which adds 30 to the address of dot. 

Special variables are names for things that are not normally directly accessible.  Special variables include:

$var The debugger has room in its own address space for a number of user-created special variables.  They are all of type long, and do not take on the type of any expression assigned to them.  Names are defined when they are first seen.  For example, saying "p $xyz = 3∗4" creates special symbol "$xyz", and assigns to it the value 12.  Special variables may be used just like any other variables.  Names are limited to 100 characters. 

$pc, $sp, $r7, etc. 
These are the names of the program counter, the stack pointer, the CPU general registers, etc. To find out which names are available on your system, use the "lr" (list registers) command.  All registers act as type integer. 

$result This is used to reference the return value from the last command line procedure call.  Where possible, it takes on the type of the procedure.  $short and $long are available as alternate ways of looking at $result. 

$signal This lets you see and modify the current child process signal number. 

$lang 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 which variables are displayed.  Values that can be assigned to $lang are "C", "FORTRAN", "Pascal" and "default" ("default" means use whatever language the current procedure is written in). 

$print 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 (environment 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). 

$line This lets you see and modify the current source line number, which is also settable with a number of different commands. 

$malloc This lets you see the current amount of memory (bytes) allocated at run-time for use by the debugger itself. 

$step 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 breakpoint and free-running to it.  Setting it to a small value can improve debugger performance at the risk of taking off free-running after missing the up-level break for some reason. 

To see all the special variables, including the predefined ones, use the "ls" (list specials) command. 

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 first executable statement in that procedure. 

Expression Conventions

Every expression has a value, even simple assignment statements, as in C. 

Integer constants may begin with "0" for octal or "0x" or "0X" for hexadecimal.  If followed immediately by "l" or "L", they are forced to be of type long.  Likewise, "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[e|E|d|D|L|l[+|-]digits][f|F|l|L], for example, "1.0", "3.14e8f", or "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 token(s). The "d" and "D" exponent forms are allowed for compatibility with FORTRAN.  The "l" 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).  The suffixes "l" and "L" cause the value to be evaluated as type "long double" (16-byte IEEE real).  Unless a direct assignment is made, float and long double types are converted to type double before the expression is evaluated. 

Character constants must be entered in ” and are treated as integers.  C string constants must be entered in "" and are treated like "char *" (e.g. pointer to char).  FORTRAN and Pascal strings may be enclosed in either ” or "".  Character and string constants may 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 truncated to size of the destination type (either 1 or 4  bytes). "\<newline>" is not supported, neither in quotes nor at the end of a command line. 

The  prefix  character  "L"  can  be  used  to  denote  wide character or string  constants  (wchar_t).  Use of the  prefix  will  cause  the value to be  mapped  to its wide-character   equivalent   before  being  stored (see multibyte(3C)).  If  an unmappable value is encountered, it is stored unconverted. 

Expressions are composed of any combination of variables, constants, and operators.  The debugger recognizes the language of the object file (that is, a.out), and switches to its language-specific operators.  The user can also create a composite program, built of two or more supported languages, and debug without regard to which parts are comprised of which language.  The global variable $lang is set as necessary by the debugger, based on the symbol table data supplied with the object file. The $lang variable can be set to "C", "FORTRAN", "Pascal" or "default". 

If no active child process and no corefile exist, 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 does not 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 "~3". 

Note that "=" means "assign" except for Pascal; to test for equality, use "==" for C, or ".EQ." for FORTRAN.  In Pascal, "=" is a comparison operator; use ":=" for assignments.  For example, if you invoke the debugger, then set "p $lang = Pascal", you must say "p $lang := C" to return to C. 

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 main(). 

You can attempt to dereference any constant, variable, or expression result using the C "∗" operator.  If the address is invalid, an error is given. 

Type casting is allowed. For simple types, the syntax is identical to C.  For example:

(short) size
(double *) mass_ptr

These casts are limited to char, short, long, int, unsigned, float, double, appropriate combinations of these keywords, and single level pointer types. Also supported are structure and union pointer type dereferences. For example:

bar_ptr = &bar
(struct foo) &bar
(struct foo) bar_ptr

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[5][6][7]" in C, "x(5,6,7)" in FORTRAN, or "x[1..5,2..6,3..7]" in Pascal.  Referencing it simply as "x" is the same as just "x" in C, the address of "x(1,1,1)" 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(1,1,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. 

String constants are stored in a buffer in the file /usr/lib/xdbend.o on the series 800 or /usr/lib/end.o on the series 300, which you link with your program.  The debugger starts storing strings at the beginning of this buffer, and The capacity of this buffer is 512 bytes.  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 does not 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

Procedures may be invoked from the command line, even within expressions.  For example:

p 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 procedure 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) may 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 program for a new process). 

You can call any procedure that is in your objectfile, even if it is not debuggable (was not compiled with debug on).  For example, assume that you reference "printf()" in your program, so the code for it is in your objectfile.  Then you can enter on the command line:

p printf ("This works! %d %c\n", 9, ′?′);

To determine what procedures are available, do a list labels command ("ll"). 

COMMANDS

The debugger has a large number of commands for viewing and manipulating the program being debugged.  They are explained below, grouped by functional similarity. 

The command line editing and history features from ksh(1) are available during command input (see ksh(1)). The environment variables XDBEDIT, EDITOR, or VISUAL are checked (in that order) to determine which of the three available editing modes (vi, emacs, or gmacs) is used.  The command history file is specified by the environment variable XDBHIST, and its size is derived from HISTFILE.  If any of these environment variables is not set, the default is the same as with ksh(1) except that XDBHIST defaults to "$HOME/.xdbhist".

Window Mode Commands

These commands control what is displayed in the source window, in addition the "td" command determines whether single stepping is at the source statement level or the assembly instruction level.  The source window has three different modes.  In source mode, the window is filled with source lines from the user program.  In disassembly mode, the top five lines of the source window displays one of several sets of registers (see the "gr", "fr" and "sr" commands), and the remainder of the window displays assembly language instructions.  In split screen mode, the top half of the window displays source code, while the bottom half displays the corresponding assembly instructions. 

td Toggle disassembly mode.  When in disassembly mode, the source window displays one of several sets of registers (see "gr", "fr" and "sr") and the code in assembly language.  In addition, the single step command steps one assembly instruction at a time rather than a source statement at a time.  The assembly language display consists of the source line number, the address in hex, the address in the form of nearest label plus offset, and the assembly instruction.  If the debugger is already in split screen mode, then the "td" command changes the level of single stepping, but has no change on the display other than the mode displayed in the line separating the source statements from the assembly instructions. 

ts Toggle split-screen mode.  When in split-screen mode, the source window is half source code and half assembly instructions.  In split screen mode, the "td" command still toggles the debugger between symbolic (or source) mode and assembly mode, as indicated by the line separating the source from the assembly.  The only difference is whether single stepping is at the source statement or assembly instruction level. 

gr Display the general 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. General registers may be modified by using the debugger special variables.  When displaying the general registers or the floating point registers, the line dividing the registers from the assembly code displays certain special processor registers. Some registers are displayed as a string of letters, each letter representing a bit in the register.  A lowercase letter indicates that the bit is off, uppercase means on. 

fr Display the floating point registers when the debugger is in assembly (non-split-screen) mode.  On a series 300 having multiple floating point processors, you will be asked which set of registers you want to display.  When the value of a register changes, that register is highlighted until after the next command.  On the series 800, these registers may be modified by using the debugger special variables $f0 through $f31 (Note that the register display indicates sixteen 64-bit registers, while there are 32 32-bit floating point register special variables), not all floating point registers are writeable. 

w [size] Set the size of the source viewing window.  It is normally set to 15 lines for a 24 line terminal.  If the line oriented interface is being used, this command prints size lines centered around the current location. 

u Update the screen to reflect the current location.  This command is best used as part of an assertion (see Assertion Control Commands). 

U Redraw the screen. This is used when the screen is corrupted. 

File Viewing Commands

These commands may change the current viewing position, but they do not affect the next statement to be executed in the child process, if any. 

v View the source one window forward from the current source window.  One or two lines from the previous window are preserved for context.  If the line oriented interface is in use only the next source line is displayed. 

v [location] View the source at the specified location, placing it in the center of the window.  If the line oriented interface is in use only the source line location is displayed. 

V [depth] View the current procedure at depth depth on the stack in the source window.  If not specified the depth defaults to zero, which is where the program is currently stopped. 

va [address] View the assembly code at address in the source window.  Address is an expression that may include constants and code labels (ex. _start + 0x20) This command is useful only when in disassembly mode. 

L Display the file name, procedure name, line number, and the current source statement corresponding to the object code being executed or examined.  This allows you to determine where you are in the program, and is most useful in assertion and breakpoint command lists. 

+[lines] Move to lines (default one) lines after the current line. 

-[lines] Move to lines (default one) lines before the current line. 

/[string] Search forward through the current file, from the line after the current line, for string. 

?[string] Search backward for string, from the line before the current line. 

Searches wrap around the end or beginning of the file, respectively.  If string is not specified, the previous one is used.  Wild cards and regular expressions are not supported; string must be literal. 

n Repeat the previous "/" or "?" command using the same string as previously. 

N The same as "n", but the search goes in the opposite direction as specified by the previous "/" or "?" command. 

Display Formats

A format is of the form "[∗][count]formchar[size]".

"∗" means "use alternate address map" (only supported on the series 300). 

Count is the number of times to apply the format style formchar.  It must be a number. 

Size is the number of bytes to be formatted for each count, and overrides the default size for the format style.  It must be a positive decimal number (except short hand notations, see below).  Size is disallowed with those formchars where it makes no sense.

For example, "p abc\4x2" prints, starting at the location of "abc", four two-byte numbers in hexadecimal. 

The formats which print numbers allow an uppercase character to be used instead, for the same results as appending "l" (see below).  For example, "O" prints in long octal.  The following formats are available:

n Print in the "normal" format, based on the type.  Arrays of char and pointers to char are interpreted as strings, and structures are fully dumped. 

(d | D) Print in decimal (as integer or long). 

(u | U) Print in unsigned decimal (as integer or long). 

(o | O) Print in octal (as integer or long). 

(x | X) Print in hexadecimal (as integer or long). 

(b | B) Print a byte in decimal (either way). 

c Print a character. 

C Print a wide-character.  Attempts  conversion to the external character-set (as determined by the locale category LC_CTYPE)      before      printing;     see multibyte(3C). 

(e | E) Print in "e" floating point notation (as float, double, or long double) (see printf(3S)). Remember that floating point expressions are always doubles! Some floating point values represent non-numeric values. Refer to ecvt(3c).

(f | F) Print in "f" floating point notation (as float, double, or long double). 

(g | G) Print in "g" floating point notation (as float, double, or long double). 

a Print a string using expr as the address of the first byte. 

w Print a wide-character string using expr as the address of the first element.  Attempts conversion to the external character set before printing. 

W Print a wide-character string using expr as the address of a pointer to the first element.  Attempts conversion to the external character set before printing.  This is the same as saying "∗expr\w", except for arrays. 

s Print a string using expr as the address of a pointer to the first byte.  This is the same as saying "∗expr\a", except for arrays. 

t Show the type of expr (usually a variable or procedure name).  For true procedure types you must actually call the procedure, e.g.  "def (2)\t". 

p Print the name of the procedure containing address expr. 

S Do a formatted dump of a structure.  Note that expr must be the address of a structure, not the address of a pointer to a structure. 

There are some short hand notations for size:

b 1 byte (char). 

s 2 bytes (short). 

l 4 bytes (long). 

D 8  bytes  (double).  Can  only  be used  with floating-point formats. 

L 16  bytes  (long  double).  Can  only be used with floating-point formats. 

These can be appended to formchar instead of a numeric size.  For example, "abc\xb" prints one byte in hexadecimal. 

If you view an object with a size (explicitly or implicitly) less than or equal to the size of a long, the debugger changes the basetype to something appropriate for that size.  This is so "." (dot) works correctly for assignments. For example, "abc\c2" sets the type of "." to short.  One side effect is that if you look at a double using a float format, dot loses accuracy or has the wrong value. 

The value of the $print special variable affects the default format for character types as follows:  for "ascii" mode the default format is "x" for unsigned char and wchar_t types.  In "native" and "raw" modes, the defaults for unsigned char and wchar_t are "c" and "C" respectively.  Likewise, "s" and "W" are used for pointers to unsigned char and wchar_t. 

Data Viewing and Modification Commands

p expr If expr does not look like anything else (such as a command), it is handled as if you had typed "p expr\n" (print expression in normal format).  Note that modification of variables is done by using the assignment operator in the expression (ex. "p foo = 7" in C or FORTRAN, or "p foo := 7" in Pascal). 

p expr\format Print the contents (value) of expr using format.  For example, "abc\x" prints the contents of "abc" as an integer, in hexadecimal. 

p expr?format Print the address of expr using format.  For example, "abc?o" prints the address of "abc" in octal. 

p -[[\] format] Back up to the preceding memory location (based on the size of the last thing displayed).  Use format if supplied, or the previous format if not.  Note that no "\" is needed after the "-". 

p +[[\] format] Go forward to the following memory location (based on the size of the last thing displayed).  Use format if supplied, or the previous format if not.  Note that no "\" is needed after the "+". 

l [proc[:depth]] List all parameters and local variables of the current procedure (or of proc, if given, at the specified depth, if any).  Data is displayed using "\n" format, except that all arrays and pointers are shown simply as addresses, and only the first word of any structure is shown. 

l (a | b | d | z) List all assertions, breakpoints, directories (where to search for files), or zignals (signal actions). 

l (c | f | g | l | m | p | r | s) [string]
List all common blocks in the current procedure, files (source files which built objectfile), global variables, labels (program entry points known to the linker), macros, procedure names, registers, or special variables (except registers).  If string is present, only those things with the same initial characters are listed. 

Stack Viewing Commands

t [depth] [ \format]
Trace the stack for the first depth (default 20) levels.  Use the format if specified. For procedures that are not compiled with symbolic debug, xdb displays the name of the procedure, and in parentheses, a best guess at the procedure parameters. For the series 300, it is five integers. For the series 800, it is the first four words of the parameter spill area.  Note that the procedure might not have spilled the four argument registers (the values might still be in the argument registers, or might have been moved to some other registers), and therefore the values printed by xdb are not guaranteed to be the correct values of the first four words of the procedure’s argument list. 

T [depth] [ \format]
The same as "t", but local variables are also displayed, using "\n" format (except that all arrays and pointers are shown simply as addresses, and structures as first words only). Use the format if specified. 

Job Control Commands

The parent (debugger) and child (objectfile) processes take turns running. The debugger is only active while the child process is stopped due to a signal, including hitting a breakpoint, or terminated for whatever reason.

r [arguments] Run a new child process with the given argument list (if any).  The existing child process, if any, is terminated first.  If no arguments are given, the ones used with the last "r" command are used again (none if "R" was used last). 

Arguments can contain "<" and ">" for redirecting standard input and standard output.  ("<" does an open(2) of file descriptor 0 for read-only; ">" does a creat(2) of file descriptor 1 with mode 0666). Redirection can also be done with ">>" and ">&".  Arguments can contain shell variables and metacharacters, quote marks, or other special syntax.  The remainder of the input-line following the "r" command is used as the argument-list, so it cannot be enclosed in a command list ("{}").  Thus, "r" cannot be used within a breakpoint, assertion, or "if" command. 

R Run a new child process with no argument list. 

k Terminate (kill) the current child process if it exists. 

c [location] Continue from a breakpoint ignoring the signal.  Set a temporary breakpoint at the specified location. 

C [location] Continue just like "c", but allow the signal (if any) to be received.  This is fatal to the child process if it does not catch or ignore the signal!  Set a temporary breakpoint at the specified location. 

s [count] Single step 1 (or count) statements. Successive carriage-returns repeat with a count of 1.  If count is less than one, the child process is not stepped.  Note that the child process continues with the current signal, if any!  (You can set "$signal = 0" to prevent this.) 

If you accidentally step down into a procedure you do not care about, use the "bu" command to set a temporary up-level breakpoint, and then continue using "c". 

S [count] Single step like "s", but treat procedure calls as single statements (do not follow them down).  If a breakpoint is hit in such a procedure, or in one that it calls, its commands are executed.  This is usually all right, but beware if there is a "c" command in that breakpoint’s command list! 

The debugger has no knowledge about or control over child processes forked in turn by the process being debugged.  Also, it gets very confused (leading to "Bad access" messages) if the process being debugged executes a different program via exec(2).

Child process output may be (and usually is) buffered.  Hence it may not appear immediately after you step through an output statement such as printf(3S). It may not appear at all if you kill the process.

Breakpoint Commands

The debugger provides a number of commands for setting and deleting breakpoints.  Associated with a breakpoint are three attributes:

address All the commands which set a breakpoint are simply alternate ways to specify the breakpoint address.  The breakpoint is then encountered whenever address is about to be executed, regardless of the path taken to get there.  Only one breakpoint at a time of a particular type may be set at a given address.  Setting a new breakpoint at address replaces the old one of the same type, if any. 

count The number of times the breakpoint is encountered prior to recognition.  A count is of the form \<expr>, \<expr> p (p for permanent, the default), or \<expr> t (t for temporary).  count decrements with each encounter.  Each time count goes to zero, the breakpoint is recognized.  If the breakpoint is permanent, count is reset to the original count.  If the breakpoint is temporary, once count goes to zero, the breakpoint is recognized, then deleted. 

A count of zero is used internally by the debugger and means that the breakpoint is deleted when the child process next stops for any reason, whether it hit that breakpoint or not.  Commands saved with such breakpoints are ignored.  Normally you never see these sorts of breakpoints. 

Note that once a breakpoint exists, the count can then be modified only by the "bc" command. 

commands Actions to be taken upon recognition of a breakpoint before waiting for command input.  These are separated by ";" and may be enclosed in "{}" to delimit the list saved with the breakpoint from other commands on the same line.  If the first character is anything other than "{", or if the matching "}" is missing, the rest of the line is saved with the breakpoint. 

Saved commands are not parsed until the breakpoint is recognized.  If commands are nil then, after recognition of the breakpoint, the debugger just waits for command input. 

The debugger has only one active command line at a time.  When it begins to execute breakpoint commands, the remainder (if any) of the old command line is discarded, with notice given. 

Each breakpoint is individually active or suspended, and there is an overall breakpoint mode.  If any breakpoint is added or activated, or if all breakpoints become suspended, the global mode follows suit. 

Here are the breakpoint commands:

lb List all breakpoints in the format "num: count: nnn  proc: ln: contents", followed by "{commands}", for example:

1:
count: 1t  sortall: 12: abc += 1;
   {t;i\D}

2:
count: 5  fixit: 29: def = abc >> 4;
   {Q;if ∗argv == −1 {"Oops"}{c}}

The leftmost number is an index number for use with the "db" (delete) command. 

b [location] [\count] [commands]
Set a permanent breakpoint at the current location (or at location).  Set the count number of times through breakpoint.  When the breakpoint is hit, commands are executed.  If there are none, the debugger pauses for command input.  If immediate continuation is desired, finish the command list with "c" (see breakpoint 2 in the example above). 

db [number] Delete breakpoint number number.  If number is absent, delete the breakpoint at the current line, if any.  If there is none, the debugger executes a "lb" command instead. 

db * Delete all breakpoints (including "procedure" breakpoints). 

bp [commands] Set permanent breakpoints at the beginning (first executable line) of every debuggable procedure.  When any procedure breakpoint is hit, commands are executed. 

It is permissible to set other permanent or temporary breakpoints at the same locations as these "procedure entry" breakpoints.  If a procedure and non-procedure  breakpoint are both hit at the same location, the non-procedure breakpoint has priority.  It is not possible to alter the "count" of a procedure entry breakpoint.  Procedure entry breakpoints must be activated and deleted as a group; it is not possible to set or delete individual ones. 

Procedure entry breakpoints are useful for procedure stepping and tracing.  For example, the command

    bp Q;t 1;c

sets up procedure tracing by printing the current procedure at each breakpoint. 

bpx [commands]
Set permanent breakpoints at the exit (final executable statement) of every debuggable procedure. When any procedure exit breakpoint is hit, commands are executed. 

bpt [commands]
Set permanent breakpoints at the entry and exit (first and final executable statements) of every debuggable procedure. The commands if any, are associated with the entry breakpoint. Commands for the exit breakpoint are "Q;L;c" for the series 300, and "Q;p $ret0;c" for the series 800. 

dp
Delete all "procedure entry" breakpoints. All breakpoints set by commands other than "bp" will remain set. 

Dpx
Delete all "procedure exit" breakpoints. All breakpoints set by commands other than "bpx" will remain set. 

Dpt
Delete all "procedure trace" breakpoints. All breakpoints set by commands other than "bpt" will remain set. 

abc commands
Define a global breakpoint command that will be executed whenever any breakpoint is hit (normal, procedure, procedure exit, or procedure trace).

dbc
Delete the global breakpoint command.

bb [depth] [\count] [commands]
Set a breakpoint at the beginning (first executable line) of the procedure at the given stack depth.  If depth is not specified, it uses the current procedure, which might not be the same as the one at depth zero. 

bx [depth] [\count] [commands]
Set a breakpoint at the exit (last executable line) of the procedure at the given stack depth.  If depth is not specified, it uses the current procedure, which might not be the same as the one at depth zero.  The breakpoint is set at a point such that all returns of any kind go through it. 

bu [depth] [\count] [commands]
Set an up-level breakpoint. The breakpoint is set immediately after the return to the procedure at the specified stack depth (default one, not zero).  A depth of zero means "current location", e.g. "bu 0" is a way to set a temporary breakpoint at the current value of $pc. 

bt [(depth | proc)] [\count] [commands]
Trace the current procedure (or procedure at depth, or proc). This command sets breakpoints at both the entrance and exit of a procedure. By default, the entry breakpoint commands are "Q;2t;c", which shows the top two procedures on the stack and continues.  The exit breakpoint is always set to execute "Q;L;c" on the series 300, and "Q;p $ret0;c" on the series 800. 

If depth is given, proc must be absent or it is taken as part of commands.  If depth is missing but proc is specified, the named procedure is traced.  If both depth and proc are omitted, the current procedure is traced, which might not be the same as the one at depth zero. 

If commands are present, they are used for the entrance breakpoint instead of the default shown above. 

ba address [\count] [commands]
Set a breakpoint at the given code address. Note that address can be the name of a procedure or an expression containing such a name.  Of course, if the child process is stopped in a non-debuggable procedure, or in prologue code (before the first executable line of a procedure), things may seem a little strange. 

bc number count
Set the count of breakpoint number to count. 

sb [num]
Suspend breakpoint number num. If no breakpoint number is given, suspend the breakpoint at the current line. 

sb *
Suspend all breakpoints.

ab [num]
Activate breakpoint number num. If no breakpoint number is given, activate the breakpoint at the current line. 

ab *
Activate all breakpoints.

tb
Toggle the overall  breakpoints  mode between active and suspended. 

The next three commands are not strictly part of the breakpoint group, but are used almost exclusively as arguments to breakpoints or assertions. 

if [expr] {commands}[{commands}]
If expr evaluates to a non-zero value, the first group of commands (the first "{}" block) is executed, else it (and the following "{", if any) is skipped.  In general, all other "{}" blocks are always ignored (skipped), except when given as an argument to an "a", "b", or "!" command.  The "if" command is nestable, and may be abbreviated to "i". 

Q If the "Quiet" command appears as the first command in a breakpoint command list, the usual announcement of "proc: line: text" is not made.  This allows quiet checks of variables, etc. to be made without cluttering the screen with unwanted output.  The "Q" command is ignored if it appears anywhere else. 

"any string you like"
Print the given string, which may have the standard backslashed character escapes in it, including "\n" for newline.  This command is useful for labeling output from breakpoint commands. 

Assertion Control Commands

Assertions are lists of commands that are executed before every statement.  This means that, if there is even one active assertion, the program is single stepped at the machine instruction level.  In other words, it runs very slowly.  The primary use for assertions is tracking down nasty bugs, such as when someone corrupts a global variable.  Some examples follow the command descriptions. 

Each assertion is individually active or suspended, and there is an overall assertions mode.  If any assertion is added or activated, or if all assertions become suspended, the global mode follows suit. 

a commands Create a new assertion with the given command list, which is not parsed until it is executed.  As with breakpoints, the command list may be enclosed in "{}" to delimit it from other commands on the same line.  Use the "la" command to list all current assertions and the overall mode. 

aa number Activate assertion number. 

aa * Activate all assertions. 

da number Delete assertion number. 

da * Delete all assertions. 

sa number Suspend assertion number. 

sa * Suspend all assertions. 

ta Toggle the overall assertions mode between active and suspended. 

x [mode] Force an exit from assertions mode.  If mode is absent, or if it evaluates to zero, exit immediately.  Otherwise, finish executing the current assertion first.  If any assertion executes an "x" command, the child process stops and the assertion doing the "x" is identified. 

The debugger has only one active command line at a time.  When it begins to execute assertion commands, the remainder (if any) of the old command line is discarded, with notice given. 

Certain commands ("r", "R", "c", "C", "s", "S", and "k") are not allowed while assertions are running.  They must appear after the "x", if at all. 

A useful assertion might be:

a u

This "walks" the program (traces execution) until "something" happens (e.g., you hit the BREAK key). 

Another example:

a L; if(xyz > (def − 9) ∗ 10) {ta; x 1; c} {p abc −= 10}

This assertion prints the line just executed, then checks the condition.  If it is false, "abc" is decremented by 10.  If it is true, assertions are suspended, assertion mode is exited, and the program continues at normal speed.  Without the number after the "x" command, the "c" command is not executed. 

Another example:

a if (abc != $abc) {p $abc = abc;p  abc\d; if (abc > 9) {x}}

This command sets up an assertion to report the changing value of some global variable ("abc"), and stop if it ever exceeds some value.  It uses a debugger local variable ("$abc") to keep track of the old value of "abc". 

Signal Control Commands

The debugger catches all signals bound for the child process before the child process sees them.  (This is a function of the ptrace(2) mechanism.) For many signals, this is a reasonable thing to do. Most processes are not set up to handle segmentation errors, etc. However, some processes do quite a bit with signals and the constant need to continue from a signal catch can be tedious.

z [signal] [i][r][s][Q]
Modifies the "zignal" (signal) handling table. Signal is a valid signal number (the default is the current signal).  The options (which must be all one word) toggle the state of the appropriate flag:  ignore, report, or stop.  If "Q" is present, the new state of the signal is not printed. 

Use the "lz" command to list the current handling of all signals.  Note that just "z signal" with no options tells you the state of the selected signal. 

For example, assuming a start up state of (do not ignore, do not report, do not stop), the command "z 14 sr" sets the alarm clock signal to stop (but still do not ignore) and report that it occurred.  Doing "z 14 sr" again toggles the flags back to the original state. 

When the child process stops or terminates on a signal it is always reported, except for the breakpoint signal when the breakpoint commands start with "Q". 

When the debugger ignores a signal, the "C" command then does not know about it, and the signal will not be passed to the child process.  The signal is never ignored when the child process terminates, only when it stops. 

Record and Playback Commands

The debugger supports a record-and-playback feature to recreate program states and record all debugger output.  It is particularly useful for bugs requiring long setups.  Note: The file name can’t be "t", "f", or "c", or begin with a "@". 

The following commands are available:

>file Set or change recordfile to file and turn recording on.  This rewrites file from the start.  Only commands are recorded to this file. 

>>file This is the same, but appends to file instead of overwriting. 

>@file

>>@file Set or change record-all file to file, for overwriting or appending.  The record-all file may be opened or closed independently of (in parallel with) the recordfile.  All debugger standard output is copied to the record-all file, including prompts, commands entered, and command output.  However, child process output is not captured. 

>(t | f | c) Turn recording on ("t") or off ("f"), or close the recording file ("c").  When recording is resumed, it appends after commands recorded earlier.  In this context, ">>" is the same as ">". 

>@(t | f | c)
Turn record-all on, off, or close the record-all file. In this context, ">>@" is the same as ">@". 

tr [@] Toggle recording [record-all]; if ON turn it OFF, if OFF turn it ON. 

> Tell the current recording status.  ">>" does the same thing. 

>@ Tell the current record-all status.  ">>@" does the same thing. 

<file Start playback from file. 

<<file Start playback from file using the single-step feature of playback.  Each command line from the playback file is presented before it is executed.  A simple menu lets you execute ("<cr>") or skip ("S") the line, execute more than one line ("<num>"), continue ("C") or quit ("Q") single stepping, or ask for help ("?"). 

Only command lines read from the keyboard or a playback file are recorded in the recordfile.  For example, if recording is turned on in an assertion, it does not "take effect" until assertion execution stops. 

Command lines beginning with ">", "<", or "!" are not copied to the current recordfile (but they are copied to the record-all file).  You can override this by beginning such lines with blanks. 

NOTE:  The debugger can of course be invoked with standard input, standard output, and/or standard error redirected, independent of record and playback.  If the debugger encounters an end of file while standard input is redirected from anything other than a terminal, it prints a message to standard output and exits, returning zero. 

Macro Definition Commands

def name [replacement-text]
Define name as a macro whose value is replacement-text.  Name can be any string of letters or digits. Replacement-text can be any string of letters, digits, blanks, tabs, or other printing characters, but it cannot be interrupted by a new line. 

undef name Remove the macro definition from name so that name no longer exists as a replacement string macro. As a special case "*" can be entered for number to undefine all macros. 

tm Toggle the state of the macro substitution mechanism between active and suspended. When macro substitution is suspended, the currently defined macros continue to exist, but they are not replaced in the command-line by their definitions. Additional macros may still be defined while macro substitution is suspended. 

Miscellaneous Commands

sm Suspend the "more" (pagination) facility of the debugger output.  This is most useful when breakpoints or assertions are printing a great deal of information to the screen, and you do not want the debugger to keep waiting for you to hit the space bar. 

am Activate the "more" facility to paginate the debugger output. 

<carriage-return>

~ Repeat the last command, if possible, with an appropriate increment, if any.  Repeatable commands are those which print a line, print a window of lines, print a data value, single step, and single step over procedures.  Note that <carriage-return> is saved in a record file as a "~" command. 

! [command-line]
Invoke a shell program. If command-line is present, it is executed via system(3S). Otherwise, the environment variable SHELL gives the name of the shell program to invoke with a −i option, also using system(3S). If SHELL is not found, the debugger executes /bin/sh −i.  In any case, the debugger then waits for the shell or command-line to complete. 

As with breakpoints, command-line may be enclosed in "{}" to delimit it from other (debugger) commands on the same line.  For example,

b 14 {!{date};c}; t; la

sets a breakpoint at line 14 that calls date(1), then continues; then (after setting the breakpoint), the debugger does a stack trace, then lists assertions.

# [text] Flag this text as a comment to be echoed to the command window. The # must appear as the first non-blank character on the line and the remainder of the line is treated as a comment. It is also written to the currently open record file. 

D dirs Adds dirs to the list of additional directory search paths for source files. This command is equivalent to the command-line option -d. 

f ["printf-style-format"]
Set the address printing format using printf(3S) format specifications (not debugger format styles).  Only the first 19 characters are used.  If there is no argument, the format is set to a system-dependent default.  All addresses are assumed to be of type long, so you should handle all four bytes to get something meaningful. 

g line | #label Go to an address in the procedure on the stack at depth zero (not necessarily the same as the current procedure).  This changes the program counter so line or the line #label appears on is the next line to be executed. 

h

help Print the debugger help file (command summary) using more(1).

I Print information (inquire) about the state of the debugger. 

M Print the current text (objectfile) and core (corefile) address maps.

M (t | c) [expr; [expr;...]]
Set the text (objectfile) or core (corefile) address map. The first zero to six map values are set to the exprs given (refer to adb(1) for details on address maps).

q Quit the debugger.  To be sure you do not lose a valuable environment, this command requests confirmation. 

tc Toggle case sensitivity in searches.  This affects everything: file names, procedure names, variables, and string searches! 

ADOPTING AN EXISTING PROCESS

Xdb is capable of adopting and debugging a free-running process.  This is accomplished by invoking xdb with the −P process ID option. 

To adopt a process, the effective user IDs of the debugger and the process to be adopted must match, or the effective user ID of the debugger must be root.  When a process is adopted, it halts, and xdb displays where the program is halted, at which point the program can be debugged.  If the user quits the debugger without killing the process, xdb removes all breakpoints from the process, and allows it to continue running.  If a program is designed to be adopted by xdb when in a certain state (such as an error condition), it is important that the program infinite loop, rather than calling the system routine sleep(). A sleeping program cannot be adopted correctly by xdb.

SYMBOL TABLE DEPENDENCIES

When you try to display a variable which is a FORTRAN format label, a Pascal file-of-text, or a Pascal set, with no display format or with normal format ("\n"), the value is shown as "{format-label}", "{file-of-text}", or "{set}", respectively.  You can use other formats, such as "\x", to display the contents of such variables. 

Procedures in FORTRAN and Pascal may have alias names in addition to normal names.  Aliases are shown by the "lp" (list procedures) command.  They can be used in place of the normal name, as desired. 

The procedure name "_MAIN_" is used as the alias name for the main program (main procedure) in all supported languages.  Do not use it for any debuggable procedures. 

FORTRAN ENTRY points are flagged "ENTRY" by the "lp" command. 

When a compiler does not know array dimensions, such as for some C and FORTRAN array parameters, it uses 0:MAXINT or 1:MAXINT, as appropriate.  The "\t" format shows such cases with "[]" (no bounds specified), and subscripts from 0 (or 1) to MAXINT are allowed in expressions. 

Even though the symbol table supports C structure, union, and enumeration tags, C typedefs, and Pascal types, the debugger does not know how to search for them, even for the "\t" format.  They are "invisible". 

Some variables are indirect, so a child process must exist in order for the debugger to know their addresses.  When there is no child process, the address of any such variable is shown as 0xfffffffe. 

Symbol names in the Value Table are never preceded by underscores, so the debugger never bothers to search for names of that form.  The only time a prefixed underscore is expected is when searching the Linker Symbol Table for names of non-debuggable procedures. 

DIAGNOSTICS

Most errors cause a reasonably accurate message to be given.  Normal debugger exits return zero and error exits return one.  All debugger output goes to standard output except error messages given just before non-zero exits, which go to standard error. 

Debugger errors are preceded by "panic: ", while user errors are not.  If any error occurs during initialization, the debugger then prints "cannot continue" and quits.  If any error happens after initialization, the debugger attempts to reset itself to an idle state, waiting for command input.  If any error occurs while executing a procedure call from the command line, the context is reset to that of the normal program. 

Child process (program) errors result in signals which are communicated to the debugger via the ptrace(2) mechanism. If a program error occurs while executing a procedure call from the command line, it is handled like any other error (i.e. you can investigate the called procedure). To recover from this, or to abort a procedure call from the command line, type DEL, BREAK, ^C, or whatever your interrupt character is. 

WARNINGS

Xdb does not terminate on an interrupt (SIGINT), it jumps to its main loop, and awaits another command. However, this does not imply that sending xdb an interrupt is harmless. It can result in internal tables being left in an inconsistent state that could produce incorrect behavior. 

Code that is not debuggable or does not have a corresponding source file is dealt with in a half-hearted manner.  The debugger shows "unknown" for unknown file and procedure names, cannot show code locations or interpret parameter lists, etc.  However, the linker symbol table provides procedure names for most procedures, even if not debuggable. 

On some systems, if the debugger is run on a shared objectfile you cannot set breakpoints.  (This may only apply if someone else is also executing the program.)  This may be indicated by the error "Bad access" when you attempt to start a child process.  If another person starts running objectfile while you are debugging, they and you may have some interesting interactions. 

If the address given to a "ba" command is not a code address in the child process, strange results or errors may ensue. 

If you set the address printing format to something printf(3S) does not like, you may get an error (usually memory fault) each time you try to print an address, until you fix the format with another "f" command. 

Do not use the "z" command to manipulate the SIGTRAP signal.  If you change its state you had better know what you are doing or be a very good sport! 

If you single step or run with assertions through a call to longjmp (on setjmp(3C)), the child process will probably take off free-running as the debugger sets but never hits an up-level breakpoint.

Do not modify any file while the debugger has it open.  If you do, the debugger gets confused and may display garbage. 

Although the debugger tries to do things reasonably, it is possible to confuse the recording mechanism.  Be careful about trying to play back from a file currently open for recording, or vice versa; strange things can happen. 

Some compilers only issue source line symbols at the end of each logical statement or physical line, whichever is greater.  This means that, if you are in the habit of saying "a = 0; b = 1;" on one line, there is no way to put a breakpoint after the assignment to "a" but before the assignment to "b". 

Some statements do not emit code where you would expect it.  For example, assume:

99:for (i = 0; i < 9; i++) {
100:xyz (i);
101:}

A breakpoint placed on line 99 will be hit only once in some cases.  The code for incrementing is placed at line 101.  Each compiler is a little different; you must get used to what your particular compiler does.  A good way of finding out is to use single stepping to see in what order the source lines are executed. 

The output of some program generators, such as yacc(1), have compiler line number directives in them that can confuse the debugger. It expects source line entries in the symbol table to appear in sorted order. Removal of line directives fixes the problem, but makes it more difficult to find error locations in the original source file. The following script, run after yacc(1) and before cc(1), comments out line number changes in C programs:

sed "/# ∗line/s/^.∗$/\/∗&∗\//" y.tab.c >temp.c

In general, line number directives (or compiler options) are only safe so long as they never set the number backwards. 

The C operators "++", "−−", and "?:" are not available.  The debugger always understands all the other C operators, except "sizeof", if the default language is FORTRAN or Pascal.  Users should use $sizeof which works in any language. 

For FORTRAN, only the additional operators ".NE.", ".EQ.", ".LT.", ".LE.", ".GT.", ".GE." ".OR." ".NOT." ".AND." ".EQV." and ".NEQV." are supported. 

For Pascal, only the operators ":=", "<>", "^", "^." (as in "x^.y"), "and", "or", "not", "div", "mod", "addr", and "sizeof" are added. 

There is no support for FORTRAN complex variables, except as a series of two separate floats or doubles. 

The C operators "&&" and "||" are not short circuit evaluated as in the compiler.  All parts of expressions involving them are evaluated, with any side-effects, even if it’s not necessary. 

The debugger does not understand C pointer arithmetic.  "∗(a+n)" is not the same as "a[n]" unless "a" has an element size of 1. 

Xdb does not support identically-named procedures (legal in Pascal if the procedures are in different scopes).  Xdb will always use the first procedure with the given name. 

There is no support for Pascal packed arrays where the element size is not a whole number of bytes.  Any reference into such an array may produce garbage or a bad access. 

Pascal WITH statements are not understood.  To access any variable you must specify the complete "path" to it. 

The debugger supports call-by-reference only for known parameters of known (debuggable) procedures.  If the object to pass lives in the child process, you can fake such a call by passing "& object", i.e. the address of the object. 

Only the first number of a complex pair is passed as a parameter.  Functions which return complex numbers are are not called correctly; insufficient stack space is allocated for the return area, which can lead to overwriting the parameter values. 

Assignments into objects greater than four bytes in size from debugger special variables, result in errors or invalid results. 

Case-insensitive searches are done in a crude way which equates some non-letters with other non-letters.  For example, "[" and "{" are equal, as are "@" and "`". 

Command lines longer than 1024 bytes are broken into pieces of that size.  This may be relevant if you run the debugger with playback or with input redirected from a file. 

DEPENDENCIES

Series 300
There is no support for C local variables declared in nested blocks, nor for any local overriding a parameter with the same name.  When looking up a local by name, parameters come first, then locals in the order of the closing "}"’s of the block in which they are declared.  When listing all locals, they are shown in the same order.  When there is a name overlap, the address or data shown is that of the first variable with that name.  There is no support for Pascal intermediate variables.  To reference a variable local to an enclosing procedure, you must specify the procedure name and stack depth in the usual way (proc:depth:var).

There is no support for the C types wchar_t and long double. 

Two special variables are available only on Series 300:

$fpa If this is set to a non-zero value, any sequence of machine instructions that constitute a single floating-point accelerator instruction is treated as a single instruction for machine-level single-stepping and display. 

$fpa_reg If $fpa is set to a non-zero value, $fpa_reg indicates the address register used in floating point accelerator instruction sequences.  A 0 corresponds to register a0, 1 to a1, etc.  The default value is 2. 

The following window-mode commands are available only on Series 300:

+r Scroll the floating-point register display forward four lines. 

-r Scroll the floating-point register display back four lines. 

Series 800
All programs are shared executables.  This implies three limitations.  You cannot set breakpoints or single step a program if another process is running it; you will get a "Bad access to child process".  If you are debugging a program, and another process starts to run the same program, either through your process executing a fork(), or another process, such as a shell, executing an exec(), this second process can hit one of your breakpoints and generate a SIGTRAP.  You cannot single step through a call to fork().

sr Display the special registers (space and control registers) when the debugger is in assembly (non-split-screen) mode.  When the value of a register changes, it is highlighted until after the next command.  The control registers cannot be modified. 

To adopt a process running the program a.out, the file a.out must be preprocessed before it is run by issuing the command pxdb a.out.  If the program is run first, pxdb does not get write permission for the a.out file, and the program will have to be aborted. 

AUTHOR

Xdb was developed by HP and Third Eye Software. 

FILES

a.out Default objectfile to debug. 

core Default corefile to debug. 

/usr/lib/xdb.help Text file listed by the "help" command. 

/usr/lib/end.o Object file to link with all debuggable programs. (Series 300 only)

/usr/lib/xdbend.o Object file to link with all debuggable programs. (Series 800 only)

/usr/lib/nls/$LANG/xdb.cat
The xdb message catalog.

$HOME/.xdbrc The xdb startup file. 

SEE ALSO

cc(1), echo(1), ld(1), more(1), creat(2), exec(2), fork(2), open(2), ecvt(3C), printf(3S), system(3S), a.out(4), LANG(5). 

On some systems any of the following may exist:  adb(1), fc(1), pc(1), sdb(1), ptrace(2), core(4), symtab(4), user(4), multibyte(3C). 

EXTERNAL INFLUENCES

Environment Variables

LANG determines the local language equivalent of y for (yes/no) queries.  LANG will also determine the language in which messages are displayed. 

If LANG is not specified or is set to the empty string, a default of "C" (see lang(5)) is used. If any internationalization variable contains an invalid setting, behaves as if all internationalization variables are set to "C". See environ(5).

LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, and their printability, when reading or writing character and string data.  If LC_CTYPE is not specified in the environment or is set to the empty string, the value of LANG is used as the default. 

International Code Set Support

Single- and multi-byte character code sets are supported. 

Hewlett-Packard Company  —  HP-UX Release 7.0: Sept 1989