NAME

pdbx, dbx − parallel debugger

SYNOPSIS

pdbx [ −i ] [ −u ] [ −a ] [ −c file ] [ −D ] [ −I dir ]...  [ execfile ]

[ coredump ]]

pdbx [ −i ] [ −u ] [ −a ] [ −c file ] [ −D ] [[ −I dir ]...  −O execfile ]

[ −Q execfile ]...  [ −C coredump ]... 

DESCRIPTION

Pdbx is a tool for source-level debugging and execution of both conventional and parallel programs under DYNIX.  Currently, you can use pdbx to source-level debug FORTRAN, Pascal, C, and, on Symmetry systems, C++ programs.  The machine-level facilities of pdbx can be used for any executable program.  Pdbx is based on the UNIX 4.3bsd debugger, dbx, and performs almost identically to UNIX 4.3bsd dbx when used to debug conventional one-process, one-program applications.  You can invoke pdbx as either pdbx or dbx.  Both names are links to the same program; however, forks and signals are handled appropriately for parallel debugging when pdbx is invoked as pdbx.  Refer to the Pdbx User’s Manual for a list of differences between UNIX 4.3bsd dbx and pdbx, and for differences dependent on invocation. 

Use the first form of the pdbx command when debugging an application that consists of one or more processes running the same program.  Use the second form when debugging applications that consist of multiple programs (e.g., client/server applications or processes that exec); each −O option specifies a program to debug. 

execfile is an executable object file produced by the FORTRAN, Pascal, C, or C++ compiler when the −g option is specified on the compiler command line.  It contains a symbol table that includes the names of all the source files translated by the compiler to create it.  These files are available for perusal while using the debugger. 

If a file named core exists in the current directory, or one or more coredump files are specified, you can use pdbx to examine the state of the program when it faulted. 

If a file named .dbxinit exists in the current directory, the debugger commands in .dbxinit are executed.  Pdbx also checks for a .dbxinit in your home directory if one does not exist in the current directory. 

When invoked, pdbx processes command line options and .dbxinit information, and then prompts and waits for a command.  Pdbx supports the following command line options:

−i Force the debugger to act as though standard input is a terminal (e.g., prompt for commands). 

−u Preserve the case of identifiers for FORTRAN and Pascal programs.  The Sequent Pascal and FORTRAN V3.2 compilers translate identifiers to uppercase only.  Sequent C and Sequent ATS C compilers always preserve the case of identifiers.  ATS FORTRAN converts all identifiers to lowercase, unless the −case option is specified.  If ATS FORTRAN was invoked with the −case option, invoke pdbx with the −u option to preserve case sensitivity. 

−a Run all processes asynchronously (i.e., in the background).  As soon as pdbx starts a process running, it prompts immediately for another command.  No process may read from the terminal. 

−c file Execute the pdbx commands in file before reading from standard input. 

The −D option is available on Symmetry systems only.  It supports the debugging of C++ source code.  Pdbx translates cfront-mangled names to the original C++ versions after reading the program symbols.  This allows the C++ names in the source code to be used while debugging instead of the mangled names generated by cfront.  The pdbx command demangle performs the same function as this option and can be included in .dbxinit. 

−I dir Add dir to the list of directories that are searched when looking for a source file.  Normally, pdbx looks for source files in the current directory and in the directory where execfile is located.  You can add a directory to the search path with the use command.  When you specify more than one object file, each −I option applies to the program specified by the next −O option. 

−O execfile Identifies execfile as a program to debug.  If there is only one program, invoke pdbx without the −O option (use the first form of the pdbx command). 

−Q execfile Identifies execfile as a program not to debug.  This is similar to the −O option, except that it specifies a program that has minimal debugging information.  Use this option when the size of a program limits the amount of memory space available for debugging information. 

−C coredump Identifies coredump as a core file to analyze.  Use the −C option when there is more than one program or more than one core file.  The position of the −C option relative to the −O option on the command line is not important; pdbx matches each core file with the appropriate object file. 

Compiling Programs for Use with Pdbx Specifying the −g option as an argument on the fortran(1), cc(1), CC(1), or pascal(1) command line causes the compiler to produce symbolic information for pdbx.  If you explicitly invoke ld (1) to link your program, you must include the −lg option in the ld command line.  Depending on the compiler, the symbolic information is encoded in the symbol table of the object file, or placed in a separate file with the extension .dbg.  When pdbx is invoked on an object file objfile, it will read the symbolic information in the file objfile.dbg (if such a file exists) as well as the symbolic information in objfile. 

Multiple .dbg files can be concatenated (with cat(1)) into objfile.dbg. 

For C++ programs, as long as the source code is compiled with the −g command line option, pdbx correlates object code with the original C++ source instead of the C source code generated by cfront. 

Code compiled with the −g option cannot be optimized using the compiler’s −O option.  Debugging Multiprocess Applications Pdbx can control multiple processes and their descendants (child processes).  When a process is created (e.g., by means of the run command), it is assigned a process number.  The first process created is process number 1, and the process created most recently by pdbx is referred to as the current process.  Certain pdbx commands operate on the current process by default, but you can direct pdbx to operate on a specified process or on all processes.  You can list process numbers using the pdbx ps command, and the current process designation can be changed using the % command. 

To run a process in the background, append an ampersand (&) to the command that starts the process running (e.g., run, cont, step).  pdbx will prompt for another command without waiting for the process to stop.  Execution and Tracing Commands

run [execfile] [args] [< filename] [> filename] [&]

rerun [execfile] [args] [< filename] [> filename] [&]
Start executing execfile, passing args as command line arguments.  You can use redirection in the usual manner.  When you enter the rerun command without arguments, the previous argument list is passed to the program; otherwise it is identical to run.  run and rerun terminate any existing processes before creating the process to execute.  NOTE: You must specify the execfile parameter when more than one execfile was specified when pdbx was invoked; otherwise it must be omitted. 

release %procnum
Release the specified process from pdbx control and continue execution without further debugger control.  Child processes that call setuid can be released immediately after being stopped by a fork to allow debugging of the parent to continue. 

create [execfile] [args] [< filename] [> filename]
Create a process as with run, but do not run the process and do not terminate any existing processes.  The created process can be run using the cont command. 

terminate [%n]

terminate all
Terminate the specified process (defaults to the current process). The ps command does not list terminated processes. 

ps [%n]
Report the status, process id, and parent process of process n. If no process is specified, print a list of all processes, indicating the status of each. For core dumps, ps reports which type of signal caused the program to abort. 

%n Change the current process to process n . 

trace [procid] [in procedure] [if condition]

trace [procid] source-line-number [if condition]

trace [procid] procedure [in procedure] [if condition]

trace [procid] expression at source-line-number [if condition]

trace [procid] variable [in procedure] [if condition]

Print trace information during program execution.  Use the delete command to turn tracing off.  For multiprocess applications, the optional procid parameter specifies which process to trace (defaults to all processes associated with the current source file).  A procid of the form %n directs pdbx to trace process n .  A procid of the form %execfile directs pdbx to trace all processes created from execfile .  The next argument describes what to trace. If it is a source-line-number, the line is printed just before execution.  Source line numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon (e.g., "mumble.c":17).  If the argument is a procedure or function name, every time it is called, information is printed telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it’s a function, the value it is returning is also printed. If the argument is an expression with an at clause, the value of the expression is printed just before the identified source line is executed.  If the argument is a variable, the name and value of the variable are printed whenever it changes. Execution is substantially slower during this form of tracing. If no argument is specified, all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. The clause “in procedure” restricts tracing information to be printed only while executing inside the given procedure or function.  condition is a Boolean expression and is evaluated prior to printing the tracing information; if it is false, the information is not printed. 

stop [procid] if condition

stop [procid] at source-line-number [if condition]

stop [procid] in procedure [if condition]

stop [procid] variable [if condition]

stop all
Stop execution when the given line is reached, a procedure or function is called, a variable is changed, or the condition is true. stop all immediately stops all running processes; all other forms of the stop command set a breakpoint.  For multiprocess applications, the optional procid parameter specifies which process the breakpoint applies to.  By default, the breakpoint is set in all processes created from the current program, and only the process that encounters the breakpoint is stopped.  A procid of the form %n specifies that the breakpoint applies only to process n. If the procid is all, all processes are stopped if any process encounters the breakpoint.  A procid of the form %execfile specifies that the breakpoint applies to each process created from execfile .  If a process is running, the stop command does not take effect in that process until it is stopped. 

status [> filename]
Print the currently active tracepoints and breakpoints.

delete cmdnumber ...
Cancel the tracepoints or breakpoints associated with cmdnumber .  Use the status command to print the current tracepoints and breakpoints, and their associated command numbers. 

catch [signal]

ignore [signal]
Start or stop trapping a signal before it is sent to the program. This is useful when a program being debugged handles signals such as interrupts. A signal may be specified by number or by a name (e.g., SIGINT). Signal names are case insensitive and the “SIG” prefix is optional. By default all signals are trapped except SIGCONT, SIGCHILD, SIGALRM and SIGKILL. When entered without parameters, catch lists the signals and events that will be caught, and ignore lists the signals and events that will be ignored. 

catch event

ignore event
Catch or ignore the specified event, which may be fork, exec, or exit.  By default, execs and exits are caught and forks are ignored.  If you direct pdbx to catch forks, the child process is stopped immediately after a fork, but the parent is not stopped.  If you direct pdbx to catch execs, the process is stopped just before the new program begins execution.  If you direct pdbx to catch exits, the process is stopped just before it is removed by the system; no matter how you resume execution of the process, it will exit. 

signal [procid] signal
Send the specified signal to the specified process (defaults to the current process). procid may be all or %n. 

cont [procid] [signal] [to source-line-number] [&]
Continue execution from where it stopped. For multiprocess applications, the optional procid parameter specifies which process to continue (defaults to the current process).  procid may be all or %n.  If a signal is specified, the process continues as though it received the signal (any signal previously caught is canceled). A signal of zero indicates that execution should continue as if the process had never been stopped. Otherwise, the process is continued with whatever signal was just received. If the process has multiple signals pending, the signal parameter overrides only the signal that was caught.  If the optional source-line-number parameter is specified, execution continues until the specified source line is executed, then stops. 

step [procid] [&]
Execute one source line. Any signal previously caught is canceled. For multiprocess applications, the optional procid parameter specifies which process to execute.  procid may be all or %n. 

next [procid] [&]
Execute up to the next source line. Any signal previously caught is canceled. procid may be all or %n.  The difference between next and step is that if the line contains a call to a procedure (or function), the step command will stop at the beginning of that procedure, while the next command will stop after completion of the procedure. 

return [procedure]
Continue until a return to procedure is executed, or until the current procedure returns if none is specified. 

call procedure()

call procedure(parameters)
Execute the object code associated with the named procedure or function.

window [%n] on ttyname
Make ttyname the debugging window for process n. This command can be used to simplify the debugging of multiprocess applications by providing a different control terminal for each process. The specified process (defaults to the current process) will be used as the current process when interpreting commands from ttyname. If a process is explicitly specified, ttyname will be used for the specified process’s standard input, standard output, standard error, and debugger messages.  ttyname must specify an ordinary terminal with login disabled.  ttyname may be a complete device name (e.g., “/dev/ttyp9”) or its two-character suffix (e.g., “p9”).  To use this command, you must have either BSS/PC-Shells (available on Balance systems only) or multiple terminals. 

Printing Variables and Expressions Names are resolved first using the static scope of the current function, then using the dynamic scope if the name is not defined in the static scope. If static and dynamic searches do not yield a result, an arbitrary symbol is chosen and the message [using qualified name] is printed.  This may be overridden by qualifying an identifier with a block name, e.g., “module.variable”.  A module consists of the subroutines and data inside a source file, and is named by the file name without the .c, .C, .cc, .f, or .p suffix. 

The Sequent Pascal and FORTRAN V3.2 compilers translate identifiers to uppercase only.  Sequent C and Sequent ATS C compilers always preserve the case of identifiers.  ATS FORTRAN converts all identifiers to lowercase (unless the FORTRAN command line option −case is specified).  Specifying −u when invoking pdbx preserves the case of identifiers for FORTRAN and Pascal programs. 

Expressions are specified with a C-like syntax.  Indirection can be denoted using either a prefix “∗” or a Pascal-style postfix “^”, and array expressions are subscripted by brackets ([ ]).  The field reference operator (“.”) can be used with pointers as well as records, so a period can be used in place of the C operator “->” (but “->” is also supported). 

For C++ programs, use the Pdbx demangle command (Symmetry systems only) to distinguish overloaded C++ names. This command causes subsequent Pdbx commands to display names as they appear in the source code. Refer to the −D option and the DYNIX C++ Release Notes for more information on the demangle command. 

For multiprocess applications, an expression of the form n:expr yields the value of expr when interpreted in the context of process n .  Process n must be stopped when the expression is evaluated.  If the n: prefix is omitted, the current process is used. 

Types of expressions are checked; the type of an expression may be overridden by using the syntax (expression)\type-name.  When there is no corresponding named type, the special constructs &type-name and $$tag-name can be used to represent a pointer to a named type or C structure tag. 

assign variable = expression
Assign the value of the expression to the variable.

dump [procedure] [> filename]
Print the names and values of variables in the given procedure, or the current one if none is specified. If procedure is “.”, pdbx dumps all active variables. 

print expression [, expression] ...
Print the values of the specified expressions.

print fpustack
Display control and data register information for the 80387 floating-point coprocessor. The print fpustack command is available on Symmetry systems only. 

func [procedure]
Change the current function. If none is specified, print the current function. Changing the current function with func implicitly changes the current source file to the one that contains the function; it also changes the current scope used for name resolution. 

up [count]

down [count]
Move the current function up or down the stack count levels.  The default count is 1.  up moves toward the main program; down moves toward the most recently called procedure.  The use of up or down does not change the current source file. 

whatis name
Print the declaration of the given name, which may be qualified with block names as above.

which identifier
Print the full qualification of the given identifier, i.e., the outer blocks with which the identifier is associated.

where [%n]
Print a list of the active procedures for the specified process (defaults to the current process).

whereis identifier
Print the full qualification of all the symbols in the current program whose names match the given identifier. The order in which the symbols are printed is not meaningful.

Accessing Source Files

/regular expression[/]

?regular expression[?]
Search forward or backward in the current source file for the given pattern.

edit [filename]

edit procedure-name
Invoke an editor on filename or the current source file if none is specified.  If you specify the name of a procedure or function, the editor is invoked on the file that contains it.  The environment variable
EDITOR should be set to the name of the desired editor — e.g., /usr/ucb/vi . 

file [[%execfile] sourcefile]
Change the current source file name to sourcefile.  If none is specified, the current source file name is printed.  If an object file is specified, pdbx searches for sourcefile in the source directories listed for the specified program. 

list [source-line-number [, source-line-number]]

list procedure
List the lines in the current source file from the first line number to the second inclusive. If no lines are specified, the next 10 lines are listed. If the name of a procedure or function is given, pdbx lists a 10-line window centered around the first statement of the specified procedure or function.  The default number of lines to list is specified by the debugger variable $listwindow, which can be set using the set command. 

use [%execfile] [directory ...]
Set or display the list of directories to be searched when looking for source files. If an object file is specified, the use command applies to the indicated program. 

Command Aliases and Variables

alias name cmdname

alias name “cmdstring”

alias name (parameter [, parameter] ...) “cmdstring”

alias [name]
Define an alias for the specified command name or command string. If no command name or string is specified, display the definition of the specified alias, or of all aliases if none is specified. When commands are processed, pdbx first checks to see if the word is an alias for either a command or a string.  If it is an alias, pdbx treats the input as though the corresponding string (with values substituted for any parameters) had been entered.  For example, use the following command to define an alias rr for the command rerun :

alias rr rerun

To define an alias called b that sets a stop at a particular line enter the following:

alias b(x) “stop at x”

Subsequently, the command b(12) will expand to stop at 12 . 

set [name [= expression]]
The set command defines or displays values for debugger variables.  The names of these variables cannot conflict with names in the program being debugged, and are expanded to the corresponding expression within other commands.  The following variables have special meanings:

$fpasingle
When set, pdbx displays values in floating-point registers as single-precision numbers. 

$fpustackall (Symmetry systems only)
When set, pdbx displays nonzero floating-point stack entries even when they are in the empty state (80387 FPU only). 

$hexchars

$hexints

$hexstrings
When set, pdbx prints out characters, integers, or character pointers, respectively, in hexadecimal. 

$hexin

$octin
When set, pdbx expects integers to be entered in hexadecimal or octal, respectively.  If $hexin is set, $octin is ignored. 

$listwindow
The value of this variable specifies the number of lines to list around a function or the number of lines listed when the list command is given without any parameters.  Its default value is 10. 

$noframe (Symmetry systems only)
When set, pdbx does not attempt to follow the chain of call frames on the stack.  This allows access to global variables and register contents in code that does not establish conventional stack frames. 

$nostrict
When set, pdbx relaxes type checking rules for call and assign commands. 

$whichreg
When set, pdbx includes the register name (if any) with the information displayed by the whatis command for the specified variable.  Affects only variables declared as type register.  Valid for C and C++ programs only. 

unalias name
Remove the alias with the given name.

unset name
Delete the debugger variable associated with name. 

Machine Level Commands

tracei [procid] [address] [if cond]

tracei [procid] [variable] [at address] [if cond]
Turn on tracing using a machine instruction address.

stopi [procid] [at] address [if cond]
Stop on accesses to the specified address. stopi at address sets a breakpoint at the machine instruction at the specified address.  stopi address traces changes to the variable at the specified address. 

stepi [procid] [&]

nexti [procid] [&]
Single-step as in step or next, but do a single instruction rather than a source line. 

listi [source-line-number [, source-line-number]]

listi procedure
Same as list, but print the machine instructions that correspond to the specified source lines. 

address, address/ [format]

address / [count] [format]
Print the contents of memory starting at the first address and continuing up to the second address or until count items are printed.  If the address is a period (.), pdbx uses the address that follows the one most recently printed.  The format specifies how values are displayed; if it is omitted, the last specified format is used.  The initial value of format is X .  Pdbx supports the following formats:

i print the machine instruction

d print a short word in decimal

D print a long word in decimal

o print a short word in octal

O print a long word in octal

x print a short word in hexadecimal

X print a long word in hexadecimal

b print a byte in octal

c print a byte as a character

s print a string of characters terminated by a null byte

f print a single precision real number

g print a double precision real number

address = [format]
Print the value of the specified address in the specified format (refer to previous list of supported formats).  For example, the command 0xffff=D prints the decimal equivalent of 0xffff. 

Symbolic addresses are specified by preceding the name with an ampersand (&).  Register names must be preceded by a dollar sign ($).  The Balance register names are r0−r7.  The Symmetry register names are: eax, edx, ecx, ebx, ebp, esi, edi, esp, eip, and eflags; the floating-point registers for the 80387 are st0−st7; and the FPA (Weitek 1167) registers are fp1−fp31.  In addition, the aliases $pc, $fp, and $sp refer to the program counter, frame pointer, and stack pointer, respectively.  Addresses may be expressions made up of other addresses and the operators “+”, “-”, and indirection (unary “∗”). 

Miscellaneous Commands

demangle
Translate C++ mangled names so they match the C++ source code names. The demangle command is available on Symmetry systems only.  See the description of the −D option previously in this man page. 

helpPrint out a synopsis of pdbx commands. 

quitTerminate all processes and exit pdbx.  If quit is entered from a window that was created with the window command, pdbx stops reading commands from that window, and the window is freed for reuse with another process. 

sh [command-line]
Create a new shell and pass it the specified command line shell for execution, or execute a new shell if no command line is specified. The value of the SHELL environment variable determines which shell is used. 

suspend
Suspend pdbx and return control to the shell that invoked it (this command is not supported by the Bourne shell).  The effect of entering this command is analogous to the effect of entering CTRL-Z in a shell.  Any running process continues to run until it hits a breakpoint or receives a signal. 

source filename
Read pdbx commands from the given filename. 

FILES

a.out object file

core core dump file

.dbxinit initial commands

name.dbg symbolic information from some compilations

SEE ALSO

cc(1),  CC(1),  cpp(1),  pascal(1),  fortran(1),  ddt(1)
Sequent Pdbx User’s Manual

COMMENTS

If you have a program consisting of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file.  Since approximately one debugger start-up is done for each link, having the linker (ld) reorganize the symbol information would not save much time, though it would reduce some of the disk space used. 

This problem is an artifact of the unrestricted semantics of #include’s in C.  For example, an include file can contain static declarations that are separate entities for each file in which they are included. 

DYNIX