NAME

pdbx, dbx − parallel debugger

SYNOPSIS

pdbx [ −r ] [ −i ] [ −u ] [ −a ] [ −c file ] [ −I dir ] ... [ objfile [ coredump ]] pdbx [ −r ] [ −i ] [ −u ] [ −a ] [ −c file ] [[ −I dir ] ...  −O objfile ] [ −Q objfile ] ... [ −C coredump ] ... 

DESCRIPTION

Pdbx is a tool for source level debugging and execution of both conventional and parallel programs under DYNIX.  Pdbx is an enhanced version of the UNIX 4.2bsd dbx debugger, and can be invoked as either pdbx or dbx. Both names are links to the same program; however, forks and signals are handled differently, depending on how the debugger is invoked. When used to debug conventional one-process, one-program applications, pdbx performs almost identically to UNIX 4.2bsd dbx. Refer to the DYNIX Pdbx Debugger User’s Manual for a list of differences from UNIX 4.2bsd dbx and differences dependent on invocation . 

The objfile is an executable object file produced by a compiler with the −g flag specified to produce symbol information.  Currently, cc(1), pascal(1), and fortran(1) produce the appropriate source information.  The machine level facilities of pdbx can be used on any program. 

The object file contains a symbol table that includes the names of all the source files translated by the compiler to create it.  These files are available for perusal while using the debugger. 

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

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

If the file .dbxinit exists in the current directory, then the debugger commands in .dbxinit are executed.  Pdbx also checks for a .dbxinit in the user’s home directory if there isn’t one in the current directory. 

The command line options and their meanings are:

−r Execute objfile immediately.  If it terminates successfully pdbx exits.  Otherwise the reason for termination will be reported and the user offered the option of entering the debugger or letting the program fault.  Pdbx will read from /dev/tty when −r is specified and standard input is not a terminal. 

−i Force pdbx 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 FORTRAN and Pascal compilers are case insensitive, and translate identifiers to uppercase only.  Normally, Pdbx translates FORTRAN and Pascal identifiers to lowercase only.  If this option is specified, FORTRAN and Pascal identifiers will remain all uppercase. 

−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 the file before reading from standard input. 

−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 objfile is located.  The directory search path can also be set with the use command.  When more than one object file is specified, each −I option applies to the program specified by the next −O option. 

−O objfile
Identifies objfile as a program to be debugged.  If there is only one program, it can be specified without the −O using the first form of the pdbx command shown in the SYNOPSIS. 

−Q objfile
Identifies objfile as a program to not be debugged.  This is similar to the −O option, except that is specifies a program that will have minimal debugging information loaded into pdbx. This option is used 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 be analyzed.  The −C option is useful if there is more than one program or more than one core file.  The position of −C options relative to −O options is not important; pdbx matches each core file with the appropriate object file. 

Unless −r is specified, pdbx just prompts and waits for a command.  Compiling Programs for Use with Pdbx The −g flag given as a command line argument to cc(1), pascal(1), or fortran(1) causes the compiler to produce symbolic information for pdbx.  If you invoke ld(1) directly to link your program, you must include the −lg flag in the ld command line.  For C programs, the symbolic information is encoded in the symbol table of the object file.  For FORTRAN and Pascal programs, the symbolic information is 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. 

If separate compilation is used, several .dbg files will be produced: one for each source file.  These should be concatenated (with cat(1)) into objfile.dbg. 

Code compiled with the −g flag cannot be optimized using the compiler’s −O flag.  Otherwise, the −g flag does not change the code that the compiler generates.  Debugging Multiprocess Applications Pdbx can control multiple processes and their descendants. When a process is created (e.g., via the run command), it is assigned a process number.  The first process created is 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 can operate on a specified process (e.g., “%2”) or on all processes.  Process numbers can be listed 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 [objfile] [args] [< filename] [> filename] [&]

rerun [objfile] [args] [< filename] [> filename] [&]
Start executing objfile, passing args as command line arguments; < or > can be used to redirect input or output in the usual manner.  When rerun is used without any arguments, the previous argument list is passed to the program; otherwise it is identical to run.  Run and rerun terminate any existing processes before creating the process to be run.  NOTE: The objfile parameter must be included if more than one objfile was specified when pdbx was invoked; otherwise it must be omitted. 

create [objfile] [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, DYNIX process id, and parent process of process n. If no process is specified, print a numbered list of all processes, indicating the status of each. For core dumps, ps reports which type of signal caused the program to abort. 

%n Make process n the current process. 

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

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

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

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

trace [procid] variable [in procedure/function] [if condition]
Have tracing information printed when the program is executed. A number is associated with the command that is used to turn the tracing off (see the delete command).  For multiprocess applications, the optional procid parameter specifies which process is to be traced (defaults to all processes associated with the current source file).  A procid of the form %n specifies that process n is to be traced.  A procid of the form %objfile specifies that all processes created from objfile are to be traced.  The next argument describes what is to be traced. If it is a source-line-number, then the line is printed immediately prior to being executed.  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.p":17.  If the argument is a procedure or function name, then 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 then the value it is returning is also printed. If the argument is an expression with an at clause, then the value of the expression is printed whenever the identified source line is reached, just before it is executed.  If the argument is a variable, then the name and value of the variable is printed whenever it changes. Execution is substantially slower during this form of tracing. If no argument is specified, then all source lines are printed before they are executed. Execution is substantially slower during this form of tracing. The clause “in procedure/function” 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, then the information is not printed. 

stop [procid] if condition

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

stop [procid] in procedure/function [if condition]

stop [procid] variable [if condition]

stop all
Stop execution when the given line is reached, procedure or function called, variable changed, or condition true. stop all immediately stops all running processes; all other forms of the stop command set some form of 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 %objfile specifies that the breakpoint applies to each process created from objfile .  If a process is running, the stop command does not take effect in that process until it is stopped. 

status [> filename]
Print out the currently active trace and stop commands. 

delete command-number ...
Cancel the traces or stops corresponding to the given numbers. The numbers associated with traces and stops are printed by the status command. 

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 linenumber] [&]
Continue execution from where it stopped. For multiprocess applications, the optional procid parameter specifies which process is to be continued (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 cancelled). 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 linenumber 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 cancelled. 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 cancelled. 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 may specify a BSS/PC-Shells window (see shells(1)) or 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”). 

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.  The name resolution procedure may be overridden by qualifying an identifier with a block name, e.g., “module.variable”.  A module is considered to be the subroutines and data inside a source file, and is named by the file name without “.c”, “.f”, or “.p”.  The FORTRAN and Pascal compilers are case insensitive, so identifiers for these languages must be specified as lowercase only (or uppercase only if the −u option is specified when Pdbx is invoked). 

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

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 “(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 the procedure given is “.”, then all the active variables are dumped.

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

func [procedure/function]
Change the current function. If none is specified then 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.  Up and down do 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 that the identifier is associated with.

where [%n]
Print out 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/function-name
Invoke an editor on filename or the current source file if none is specified.  If a procedure or function name is specified, 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 [[%objfile] sourcefile]
Change the current source file name to sourcefile.  If none is specified then 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/function
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 pdbx set command. 

use [%objfile] [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, then pdbx treats the input as though the corresponding string (with values substituted for any parameters) had been entered.  For example, to define an alias “rr” for the command “rerun”, one can say

alias rr rerun

To define an alias called “b” that sets a stop at a particular line one can say

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:

$hexchars

$hexints

$hexoffsets

$hexstrings
When set, pdbx prints out characters, integers, offsets from registers, 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. 

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/function
Same as list, but print the machine instructions that correspond to the specified source lines. 

address ,address/ [mode]

address / [count] [mode]
Print the contents of memory starting at the first address and continuing up to the second address or until count items are printed.  If the address is “.”, the address following the one printed most recently is used.  The mode specifies how memory is to be printed; if it is omitted, the previous mode specified is used.  The initial mode is “X”.  The following modes are supported:

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 = [mode]
Print the value of the specified address in the specified format.  The address and mode parameters are as defined above.  For example, “0xffff=D” prints the decimal equivalent of 0xffff. 

Symbolic addresses are specified by preceding the name with an “&”.  Registers are denoted by “$rN” where N is the number of the register.  The program counter, frame pointer, and stack pointer are denoted by “$pc”, “$fp”, and “$sp”, respectively.  Addresses may be expressions made up of other addresses and the operators “+”, “-”, and indirection (unary “∗”). 

Miscellaneous Commands

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]
Pass the command line to the shell for execution, or execute a new shell if no command line is specified. The SHELL environment variable determines which shell is used.

suspend
Suspend pdbx, as with CTRL-Z, and return control to the shell that invoked pdbx. 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

.dbxinit initial commands

name.dbg symbolic information from FORTRAN and Pascal

SEE ALSO

cc(1), pascal(1), fortran(1), ddt(1)
DYNIX Pdbx Debugger User’s Manual

COMMENTS

Pdbx suffers from the same “multiple include” malady as did sdb.  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 about one debugger start-up is done for each link, having the linker (ld) re-organize 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