Prism 7.0 Software Reference Manual
|    
|
| Prism 7.0 Software Reference Manual
|
|
|
Command Reference |
This reference manual gives, in alphabetical order, the syntax and reference description of every command in the Prism programming environment. This information is also available online:
TABLE 4 lists the commands discussed in this manual.
You can redirect the output of most Prism commands to a file by including an @
(at sign) followed by the name of the file on the command line. For example,
where @ where.output
puts the output of the where command into the file where.output in your current working directory within the Prism environment.
You can also redirect output of a command to a window by using the syntax commandname on window, where window can be
|
Note - You cannot redirect the output of the commands edit, make, and sh. |
When viewing multiprocess or multithreaded programs (including single-process programs with multiple threads), the Prism environment provides a method by which certain commands can take a set of processes or threads, or both, called a pset, as a qualifier. Note that psets are not available when viewing nonthreaded scalar programs.
Commands that take a pset qualifier are listed in TABLE 1. The format for commands taking a pset qualifier is
command pset [pset_name | pset_definition] |
where pset_definition can include pset names (predefined or user-defined names), process numbers, thread numbers, expressions composed of combinations of such specifiers, and snapshots of all or part of such psets; see the define pset command for a discussion of how to define a pset. For a detailed description of psets, see the Prism User's Guide.
Place the pset qualifier after any arguments to the command, but before the optional on window syntax that specifies the window to which output is directed (see Redirecting Output). A command with a pset qualifier applies only to the processes (and threads) in the set. If you omit the qualifier, the command applies to the processes (and threads) in the current set.
The commands listed in TABLE 1 can take a pset qualifier.
In summary, using the Prism environment, you can:
Prism documentation describes, primarily, the multiprocess (MP) mode of the Prism environment. The documentation distinguishes the MP mode from the scalar mode, which you can use to view nonthreaded scalar programs. The scalar mode does not support some features found in the MP mode, such as psets. For further information on the scalar mode, see the appendix in the Prism User's Guide.
The Prism environment includes several commands that provide information about threads in the currently loaded program. These commands are described in TABLE 2.
The states of threads and light-weight processes (LWPs) are described in TABLE 3.
TABLE 4 lists all the commands in the Prism environment in alphabetical order and provides brief descriptions. It is followed by the complete command reference, also in alphabetical order.
Searches forward or backward for a regular expression in the current source file.
/regexp ?regexp |
|
Note - regexp may be any regular expression, as described in the man page regexp(5). |
Use the / command to search forward in the current source file for the regular expression you specify. The / command searches from line n+1 forward, wrapping after it passes the end of the file. If the expression is found, the source pointer moves to the line that contains the expression, and the line is echoed in the history region of the command window.
The ? command works in the same way, except that it searches backward from line n-1 in the source file, wrapping after it passes the beginning of the file.
Using / or ? updates the current line, affecting subsequent executions of the list command. The list command resets the starting line for / and ?. For further information, see list.
The / or ? commands with no arguments search for the next (or previous) occurrence of the last-used regular expression. Both / and ? wrap around if no match is found.
If the regular expression is not found, the Prism environment displays the message
No match.
in the history region of the command window.
|
Note - Because the scope pointer may be modified by this command, subsequent expression evaluation uses the resulting scope pointer for symbol resolution. |
Prints to the screen the contents of the specified memory address.
address, address/[mode] [pset pset_name | pset_definition] address | register/[count] [mode] |
Use this command to print the contents of memory or of a register. If two addresses are separated by commas, the Prism environment prints the contents of memory starting at the first address and continuing to the second address. If you specify a count, the Prism environment prints count locations, starting from the address you specify.
If the address is . (period), the Prism environment prints the address that follows the most recently printed address.
Specify a symbolic address by preceding the name with an & (ampersand). For example,
&x/
prints the contents of memory for variable x.
The address you specify can be an expression made up of other addresses and the operators +, -, and indirection (unary *). For example,
0x1000+100/
prints the contents of the location 100 addresses above address 0x1000.
Specify a register by preceding its name with a dollar sign. For example,
$f0/
prints the contents of the f0 register. See TABLE 6 for a list of supported registers. If you specify count with a register, that number of registers is printed, starting with the specified register.
The mode argument specifies how memory is to be printed; if it is omitted, the Prism environment uses the previous mode that you specified. The initial mode is X. Supported modes are listed below.
Supported UltraSPARC registers are listed below.
|
Floating-point registers state (SPARC V8 plus only, or higher) |
|
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Converts a value to the specified base.
value=base |
Use the value=base command to convert the value you specify to the base you specify. The value can be a decimal, hexadecimal, or octal number. Precede hexadecimal numbers with 0x; precede octal numbers with 0 (zero). The base can be D (decimal), X (hexadecimal), or O (octal). The Prism environment prints to the screen the converted value in the command window.
0x100=D 256 256=X 0x100 0x100=O 0400 0400=X 0x100 |
Sets up an alias for a command or string.
alias alias new-name command alias new-name [(parameters)] "string" |
Use the alias command to set up an alias for a command or string. When commands are processed, the Prism environment first checks if the word is an alias for either a command or a string. If it is an alias, the Prism environment 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, issue the command:
alias rr rerun
To define an alias called b that sets a breakpoint at a particular line, issue the command:
alias b(x) "stop at x"
You can then issue the command b(12), which the Prism environment expands to:
stop at 12
The Prism environment sets up some aliases for you automatically. Issue alias with no parameters to list the current set of aliases.
Issue the unalias command to remove an alias.
Assigns the value of an expression to a variable or array.
assign lval = expression [pset pset_name | pset_definition] |
Use the assign command to assign the value of expression to lval. lval can be any value that can go on the left-hand side of a statement in the language you are using, such as a variable or a Fortran array section. The Prism environment performs the proper type coercions if the right-hand side does not have the same type as the left-hand side.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
assign x = 1
If x is an array, 1 is assigned to each element.
To add 2 to each element of array2 and assign these values to array1:
assign array1 = array2 + 2
Note that array2 and array1 must be conformable.
Attaches to a running process or job.
attach pid | jid |
Use the attach command to attach to the running process with process ID pid or to the running job with job ID jid.
You can use the attach command to attach to an executable without issuing a prior load command. You can simply attach to the process ID or job ID. For example,
The attach command will clean up the current session before attaching to the jid specified in the command.
The attach command does not accept multiple job IDs.
However, if the job ID specified is a result of a MPI_Comm_spawn_multiple(), multiple Prism sessions will get created.
You can attach through the shell command line when you launch the Prism environment. To attach at startup, use the following syntax:
% prism - pid | jid | jid_list
where you use the dash (-) instead of the name of the executable and the name jid_list is a list of job IDs.
Use the detach command to detach a process running within the Prism environment.
Calls a procedure or function.
call procedure (parameters) [pset pset_name | pset_definition] |
Use the call command to call the specified procedure or function at the current stopping point in the program. The Prism environment executes the procedure as if the call to it had occurred from the current stopping point. Breakpoints within the procedure are ignored, however.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Tells the Prism environment to catch the specified Solaris signal.
catch [number | signal_name] [pset pset_name | pset_definition] |
The Prism environment can intercept Solaris signals before they are sent to the program. Use the catch command to tell the Prism environment to catch the signal you specify. When the Prism environment receives the signal, execution stops, and the Prism environment prints a message. A subsequent cont from a naturally occurring signal that is caught causes the signal to be propagated to signal handlers in the program (if any); if there is no handler for the signal, the program terminates -- in other words, the program proceeds as if the Prism environment were not present.
By default, the Prism environment catches all signals except SIGHUP, SIGEMT, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH; use the ignore command to add other signals to this list.
Specify the signal by number or by name. Signal names are case-insensitive, and the SIG prefix is optional.
Issue catch without an argument to list the signals that the Prism environment is set to catch.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Changes the current working directory.
cd [directory] |
Use the cd command to change your current working directory in the Prism environment to directory; with no arguments, cd makes your login directory the current working directory.
The cd command is identical to its Solaris counterpart. See your Solaris documentation for more information.
Continues execution of a target program.
cont [number | signal_name] [pset pset_name | pset_definition] |
Use the cont command to continue execution of the process from the point at which it stopped. If you specify a Solaris signal, either by name or by number, the process continues as though it received the signal. Otherwise, the process continues as though it had not been stopped.
You can use the default alias c for this command.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Continues execution and then waits for the members of the current pset to finish execution. The contw command is available only in the MP Prism environment.
contw [number | signal_name] [pset pset_name | pset_definition] |
The contw command is an alias for
cont; wait
Issuing the command continues execution of the process from the point at which it stopped, then waits for the members of the current pset to finish execution. Most Prism commands are unavailable during this time.
If you specify a Solaris signal, either by name or by number, the process continues as though it received the signal. Otherwise, the process continues as though it had not been stopped.
This command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Associates a core file with the loaded program.
core corefile |
Use the core command to associate the specified core file with the program currently loaded in the Prism environment. The Prism environment reports the error that caused the core dump and sets the current line to the location at which the error occurred. You can then work with the program within the Prism environment -- for example, you can print the values of variables. You cannot continue execution from the current line, however.
The core command is not available in the MP Prism environment. Instead, you must specify the name of the process core file on the shell command line, after the name of the program executable. For example,
% prism a.out core
See the Prism User's Guide for more information.
Makes the next member of the cycle pset the current set. The cycle command is available only in the MP Prism environment.
cycle |
Use the cycle command in the MP Prism environment to cycle through the members of the cycle pset. The cycle pset is by default equivalent to the current set; you can set it to some other set via the define pset command.
In a nonthreaded program, issuing the cycle command sets the current process to the next one in the current pset. In threaded programs, it sets the current thread to the next valid thread in the current process, and steps to the next process when appropriate. This provides a convenient way of looking at each individual member within a pset.
This example defines a pset, makes it current, then cycles through its members, making each one the current set in turn:
(prism all) define pset foo 0:3 (prism all) pset foo (prism foo) cycle (prism 1) cycle (prism 2) cycle (prism 3) cycle (prism 0) |
Creates a named pset. The define pset command is available only in the MP Prism environment.
define pset name definition |
Use the define pset command to create a pset with the membership you specify.
You can give a pset any name except the predefined names all, running, error, interrupted, break, stopped, done, current, and cycle. The name must begin with a letter; it may contain any alphanumeric character plus the dollar sign and underscore.
For the definition, specify any of the following, singly or in combination:
If a variable is not active in a process, the Prism environment prints an error message and does not execute the command. To ensure that the command is executed, use the intrinsic isactive in the pset definition. The expression isactive(variable) returns true if variable is on the stack for a process or is a global. If variable is not fully qualified, it must be within the scope of the current process.
If the Prism environment tries to evaluate a process that is running, the evaluation fails and the command is not executed. To avoid this, use the intersection of the predefined set stopped and the expression you want to evaluate. For example,
define pset xon stopped && {isactive(x) && (x .NE. 0)} |
This command defines a pset xon consisting of processes that are stopped and in which x is active and not equal to 0.
You cannot use this command in an event action.
Use the command delete pset to delete a pset that you have created using define pset.
To create a pset foo containing the processes 0, 4, and 7:
define pset foo 0, 4, 7
To define a pset odd containing the odd-numbered processes
between 1 and 31:
define pset odd 1:31:2
To define a pset quux that contains processes that are members of either pset foo or pset bar:
define pset quux foo | bar
To define a pset noty that consists of all processes that are stopped except those in which y is equal to 1:
define pset noty stopped - {y == 1}
To define a pset, snap1, containing every process and thread (at the time of the snapshot) in all except thread 1 of process 1:
(prism all) define pset snap1 snapshot (all - 1.1) |
Removes one or more events from the event list.
delete all | ID [ID...] |
Use the delete command to remove the events corresponding to the specified ID numbers (obtained by issuing the show events command). Use the all argument to delete all existing events. Deleting the events also removes them from the event list in the Event Table.
You can use the default alias d for this command.
Deletes a user-defined pset. The delete pset command is available only in the MP Prism environment.
delete pset pset_name |
Use the delete pset command to delete the pset pset_name. If you have created events that apply to this pset, the events continue to exist. Their printed representation, however, is changed so that it shows the processes that were members of the pset at the time you deleted the set.
You cannot include the delete pset command in an event action.
Use the command define pset to create a pset.
Detaches a process or job running within the Prism environment.
detach |
Use the detach command to detach the process or job that is currently running within the Prism environment. The process or job must be stopped before it can be detached. Once detached, the process or job continues to run in the background, but it is no longer under the control of the Prism environment.
The detach command only applies to the Prism session where it is invoked. If you issue the detach command in a primary session, it is not propagated down to secondary sessions.
For information about debugging multiple sessions, sessions spawned using calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see the Prism User's Guide.
Use the attach command to attach to a running process or job.
Use the kill command to terminate the process or job to which the Prism environment is attached.
disable event_ID [event_ID ...] |
Use the disable command to disable the events with the specified ID numbers (obtained by issuing the show events command). Disabled events are kept in the event list, but they no longer affect execution. Use the enable command to re-enable events. This can be more convenient than deleting events and then redefining them.
Displays the values of one or more variables or expressions.
[where (expression)] display[/radix] expression [, expression ...] [pset pset_name | pset_definition] |
Use the display command to display the value(s) of the specified variable(s) or expression(s). The display command prints the values to the screen immediately and creates a display event, so that the values are updated automatically each time the program stops execution.
The optional where expression provides a mask for the elements of the parallel variable or array being displayed. The mask can be any expression that evaluates to true or false for each element of the variable or array. Elements whose values evaluate to true are considered active; elements whose values evaluate to false are considered inactive. If values are displayed in the command window, values of inactive elements are not printed. If values are displayed graphically, the treatment of inactive elements depends on the type of representation you choose.
The optional /radix syntax specifies the radix to be used in displaying the value(s). Possible settings of /radix are described in TABLE 7.
The default radix setting is decimal, unless you have overridden the default via the set $radix command.
Redirection of output to a window via the on window syntax works slightly differently for display (and print) from the way it works for other commands.
If you don't send output to the command window (the default), separate windows are created for each variable or expression that you display. Note that displaying to a window other than the command window creates a visualizer for the data.
display x on dedicated display y on dedicated |
create two dedicated windows, one for each variable; the two windows are updated separately.
Also, by specifying as representation with the on window option, you can select the visualizer representation shown. For example:
display x on dedicated as colormap display y on dedicated as histogram |
To display the contents of a register, precede the name of the register with a dollar sign. For example,
display $pc on dedicated
displays the contents of the program counter register.
Supported UltraSPARC registers are listed in TABLE 8.
|
Floating-point registers state (SPARC V8 plus only, or higher) |
|
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To display the sum of the elements of the array foo:
display sum(foo)
To display (in a dedicated window) the values of foo that are not equal to 0:
where (foo .ne. 0) display foo on dedicated as text
Moves the symbol lookup context down one level in the call stack.
down [count] |
Use the down command to move the current function down the call stack (that is, toward the current stopping point in the program) count levels. If you omit count, the default is one level.
Issuing down repositions the source window at the new current function.
After a series of down commands, the Prism environment attempts to preserve the level when the current process changes.
Prints the names and values of local variables.
dump [function |...] |
Use the dump command to print the names and values of all the local variables in the function or procedure you specify. If you omit function, the Prism environment uses the current function. If you specify a period (.), dump follows all stack frames from the current one back to main and prints the names and values of all local variables in the functions in the stack.
|
Note - The dump command is not available in the MP Prism environment. |
edit [filename | procedure] |
Use the edit command to invoke an editor. With no arguments, the editor is invoked on the current file. If you specify filename, it is invoked on that file. If you specify procedure, it is invoked on the file that contains that procedure or function, positioning the cursor at the start of the procedure.
The editor that is invoked depends on the setting of the Prism resource Prism.editor. If this resource is not set, the Prism environment uses the setting of the EDITOR environment variable. If neither is set, the default editor is vi.
You cannot redirect the output of this command.
You can use the default alias e for this command.
Enables previously disabled events.
enable event_ID [event_ID ...] |
Use the enable command to enable the event with specified ID numbers (obtained by issuing the show events command). Use the disable command to disable events. Disabled events are kept in the event list, but they no longer affect execution. Use the enable command to re-enable events. This can be more convenient than deleting events and then redefining them.
Updates the membership of a variable pset. The eval pset command is available only in the MP Prism environment.
eval pset pset_name |
Use the eval pset command to update the membership of the variable pset set_name. You create a variable pset by issuing the define pset command and specifying a condition to be met. For example, to define a pset foo that consists of all stopped processes in which x is active and is greater than zero:
define pset foo stopped && {isactive(x) && (x>0)}
The membership of such a set can change as a program executes. To update its membership, issue the command:
eval pset foo
If the evaluation fails (for example, because a process that was previously stopped is now running, and you didn't include the stopped && syntax in your pset definition), the membership of the pset does not update.
|
Note - The isactive intrinsic requires that its variable either must be fully qualified or it must be within the scope of the current process. |
Runs the executable program in the foreground. The fg command is available only in the commands-only version of the MP Prism environment, or if you are using the graphical interface of the Prism environment without an Xterm for I/O.
fg |
Use the fg command to bring your executable program into the foreground. When executing a message-passing program in the commands-only interface of the MP Prism environment, the program starts up in the background. Bring the program into the foreground if it needs to read terminal input. You cannot execute Prism commands while the program is executing in the foreground.
To have the program run in the background again and regain the (prism) prompt, type Ctrl-Z.
Changes or displays the current source file.
file [filename] |
Use the file command to set the current source file to filename. If you do not specify a file name, file prints the name of the current source file.
Changing the current file causes the new file to be displayed in the source window. The scope pointer (-) in the line-number region moves to the current file to indicate the beginning of the new scope that the Prism environment uses in identifying variables.
When file is invoked with an absolute file name, the Prism environment searches for filename as specified. When invoked with a relative file name, the Prism environment searches first in the directory where filename was compiled. Then, if filename is not found, the Prism environment attempts to locate filename using the current-use list. For further information, see use.
|
Note - Because the scope pointer may be modified by this command, subsequent expression evaluation uses the resulting scope pointer for symbol resolution. |
Changes or displays the current procedure or function.
func [function] |
Use the func command to set the current procedure or function to function. If you do not specify a procedure or function, func prints the name of the current function.
Changing the current function causes the file containing it to be displayed in the source window; this file becomes the current file. The scope pointer (-) in the line-number region moves to the current function to indicate the beginning of the new scope that the Prism environment uses in identifying variables.
Invoking func with an invalid function name leaves the scope pointer unchanged.
The func command causes the function frame to be set to the first instance of the specified function, if any, on the expression stack. For example, assume that the function on the top of the stack, function bar, is not optimized. All of bar's local variables are accessible. Issuing the Prism command:
func foo
causes foo to become the first instance of foo on the stack. If foo is optimized, then the only accessible variables are global variables. No local variable of foo is accessible and none of the local variables of function bar are visible (because of scope change), so none of bar's variables are accessible. In other words, variables that were previously accessible are no longer accessible after issuing the command:
func foo
|
Note - The set of accessible variables is a subset of the set of visible variables. |
help [commands | command_name] |
Use the help command to get help about Prism commands.
Use the commands option to display a list of Prism commands. Specify a command name to display reference information about that command.
Issuing help with no arguments displays a brief help message.
You can use the default alias h for this command.
Removes a pane from a split source window.
hide file_extension |
Use the hide command to remove one of the panes in a split source window. The pane that is removed contains the code specified by the file extension you supply as the argument to the command.
Use the show command to create a split source window. For more information about the show command, see show.
The hide command is not meaningful in the commands-only interface of the Prism environment.
To remove the pane containing the assembly code for the loaded program, issue this command:
hide .s
To remove the pane containing Fortran 77 source code, issue this command:
hide .f
Tells the Prism environment to ignore the specified Solaris signal.
ignore [number | signal_name] [pset pset_name | pset_definition] |
The Prism environment can intercept Solaris signals before they are sent to the program. Use the ignore command to tell the Prism environment to ignore the specified signal. If the signal is ignored, the Prism environment sends it to the program and allows the program to continue running without interruption; the program can then react to the signal as though the Prism environment were not there. By default, the Prism environment catches all signals except SIGHUP, SIGEMT, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH; use the catch command to catch these signals as well.
Specify the signal by number or by name. Signal names are case-insensitive, and the SIG prefix is optional.
Issue ignore with no arguments to list the signals that the Prism environment ignores.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Suspends execution on processes. The interrupt command is available only in the MP Prism environment.
interrupt [pset pset_name | pset_definition] |
Use the interrupt command to suspend execution on processes.
The interrupted processes become members of the predefined pset interrupted.
Without a pset qualifier, interrupt suspends execution on the processes in the current pset. With a pset qualifier, interrupt suspends execution on the processes in the set you specify. See Psets: Processes and Threads for more information on pset qualifiers.
To interrupt the execution of the members of the predefined pset running:
interrupt pset running
To interrupt the execution of process 5:
interrupt pset 5
Kills a process or job running within the Prism environment.
kill |
Use the kill command to terminate the process or job that is currently running within the Prism environment.
If you issue a kill command in a primary Prism session, the command will propagate to the secondary Prism sessions. That is, the Prism environment will shut down the secondary Prism sessions and the debuggees.
For information about debugging multiple sessions, sessions spawned using calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see the Prism User's Guide.
Lists lines in the current source file or specified routine.
list [source_line_number [, source_line_number]] list routine |
Use the list command to list lines in the current file. The source window is repositioned. The command also affects the scope that the Prism environment uses for resolving names. By default, the lines are displayed in the command window.
With no arguments, list lists the next 10 lines starting with the current line.
If you specify line numbers, the lines are listed from the first line number through the second.
If you specify a procedure or function, list lists 10 lines starting with the first statement in the procedure or function.
In the commands-only interface of the Prism environment, list changes the current source line (but not the current execution line) to the last line displayed. Subsequent list commands (or search commands, for further information, see /regexp, ?regexp) begin from the new current line.
In the graphical mode of the Prism environment, the current source line is indicated by a dash (-) and the current execution line is indicated by an angle bracket (>). If the current source line is the same as the current execution line, that line is indicated by an asterisk (*).
You can use the default alias l (lowercase letter "L") for this command.
You can repeat this command by pressing Enter.
|
Note - Because the scope pointer may be modified by this command, subsequent expression evaluation uses the resulting scope pointer for symbol resolution. |
Loads an executable program into the Prism environment.
load filename |
The load command loads the file specified by filename into the Prism environment. The file must be an executable program compiled with the appropriate debugging switch.
When you execute load, the name of the program appears in the Program field of the main Prism window, and the source code that contains the main function of the program is displayed in the source window.
Use the reload command to reload the program currently loaded in the Prism environment.
log @ filename log @@ filename log off |
Use the log command to create a log file, filename, of your commands and the Prism environment's responses.
Use the @@ form of the command to append the log to an already existing file.
Use log off to turn off logging.
Lists all lightweight processes (LWPs) in the set of processes that belong to the current (or specified) pset.
lwps [pset pset_name | pset_definition] |
Use the lwps command to display a list of all lightweight processes belonging to the current (or specified) pset.
This command requires the MP Prism environment. If used with a pset qualifier, it applies to the processes (not threads) with members belonging to the pset you specify. If used without a pset qualifier, it applies to the processes with members belonging to the current pset.
For information about LWP states, see TABLE 3.
make [option...] |
Use the make command to execute the make utility to update and regenerate one or more programs. You can specify any arguments that are valid in the Solaris version of make.
By default, the Prism environment uses the standard Solaris make, /bin/make. You can change this by using the Customize utility or by changing the setting of the Prism resource Prism.make.
You cannot redirect the output of this command.
Displays the contents of MPI message queues.
mpimsgs [send | recv | urecv] [verbose] [pset pset_name | pset_definition] |
send - Allows you to examine the message queue for Posted Sends.
recv - Allows you to examine the message queue for Posted Receives.
urecv - Allows you to examine the message queue for Unexpected Receives.
verbose - Displays additional details about the communicator and dumps the contents of each message.
pset - Using the pset option, you can specify the message queues you wish to view by choosing a set of processes. If you do not use the pset option, the current pset is used by default. However, among the members of the specified pset, only the message queues of the processes that are stopped are displayed. For more information about psets, see Psets: Processes and Threads.
Use the mpimsgs command to display message queues created by a Sun MPI program. The Prism environment displays the messages in the output window, sorting the messages by rank. The fields of each message are displayed, including message size, tag, to (or from), comm (communicator), protocol, and data type.
Specify the verbose option to display more details about the communicator and to display the contents of the message.
A typical message with the verbose option enabled,
Executes one or more source lines, counting functions or procedures as single statements.
next [n] [pset pset_name | pset_definition] |
Use the next command to execute the next n source lines, stepping over procedures and functions. If you do not specify a number, next executes the next source line.
You can use the default alias n for this command.
You can repeat this command by pressing Enter.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Executes one or more machine instructions, stepping over procedure and
function calls.
nexti [n] [pset pset_name | pset_definition] |
Use the nexti command to execute the next n machine instructions, stepping over procedures and functions. If you do not specify a number, nexti executes the next machine instruction.
You can repeat this command by pressing Enter.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Prints the values of one or more variables or expressions.
[where (expression)] print[/radix] expression [, expression ...] [pset pset_name | pset_definition] |
Use the print command to print to the screen the values of the specified variable(s) or expression(s).
The optional where expression provides a mask for the elements of the parallel variable or array being printed. The mask can be any expression that evaluates to true or false for each element of the variable or array. Elements whose values evaluate to true are considered active; elements whose values evaluate to false are considered inactive. If values are printed in the command window, values of inactive elements are not printed. If values are printed graphically, the treatment of inactive elements depends on the type of representation you choose.
The optional /radix syntax specifies the radix to be used in printing the value(s). Possible settings of /radix are described in TABLE 9.
The default radix is decimal, unless you have overridden the default via the
set $radix command.
Redirection of output to a window via the on window syntax works slightly differently for print and display from the way it works for other commands.
If you don't send output to the command window (the default), separate windows are created for each variable or expression that you print. Note that printing to a window other than the command window creates a visualizer for the data.
print x on dedicated print y on dedicated |
create two dedicated windows, one for each variable; the two windows are updated separately.
Also, by specifying as representation when you use the on window option, you can select the visualizer representation shown. For example:
print x on dedicated as colormap print y on dedicated as histogram |
To print the contents of a register, precede the name of the register with a dollar sign. For example,
print $pc on dedicated
prints the contents of the program counter register.
Supported UltraSPARC registers are listed in the following table.
|
Floating-point registers state (SPARC V8 plus only, or higher) |
|
You can use the default alias p for the print command.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To print the maximum value of the array a:
print maxval(a)
To print in a dedicated window the values of a that are greater than 3:
where (a > 3) print a on dedicated as text
Displays currently set environment variables.
printenv [variable] |
Use the printenv command to display the value of the specified environment variable. If you omit variable, the command prints the values of all environment variables that are currently set.
The Prism environment's printenv command is identical to its Solaris C shell counterpart. See your Solaris documentation for more information.
Sets or displays the current process (or thread) of the current pset. The process command is available only in the MP Prism environment.
process [process_number] |
Use the process command to change the current process (or thread) of the current pset to process_number. If you omit the argument, process displays the current process of the current pset. By default, the lowest numbered process in the pset is the default process; in threaded programs, the lowest numbered thread in the lowest numbered process in the current pset is the current thread. (The current process, among other functions, determines the scope used in interpreting the names of variables.) If you omit the argument, process displays the current process of the current pset.
You cannot include this command in event actions.
To change the current thread from thread 4 to thread 3:
(prism 1.4) process 1.3 (prism 1.3) |
In the following example, as a result of changing the current pset, the current thread changes from thread 3 of process 1 to thread 5 of process 2:
Note that the current pset now includes threads 5 and 6 of processes 2 through 7.
Sets or displays the current pset. Controls which threads are visible or hidden in the psets of multithreaded programs. The pset command is available only in the MP Prism environment.
pset [pset_name | pset_definition][-hide | -unhide pset_expression] |
Use the pset command to change the current pset. You can either specify the name of a pset or the definition of a pset. See define pset for an explanation of how to define a pset.
The (prism) prompt changes to reflect the new current set.
Use the -hide pset_expression argument to specify the set of threads to be hidden from view in the Prism environment. Hidden threads never appear in any pset. Debugging commands have no effect on hidden threads. By default, threads 2, 3, and 4 are hidden. These are auxiliary threads created by any program linked with libthread.so. They are rarely of interest to programmers.
Use the -hide argument without pset_expression to show the set of currently hidden threads.
Use the -unhide pset_expression argument to specify the set of threads to be made visible from the set of currently hidden threads.
The -hide and -unhide arguments are valid only when debugging a multithreaded program.
Use the snapshot argument in pset_definition to set the current pset--which would otherwise change during program execution--to a constant value (in a multithreaded program). For further information about constant and unbounded psets, see the Prism User's Guide.
With no arguments specified, pset displays the membership of the current process set.
You cannot include the pset command in an event action.
This example changes the current pset a couple of times and displays its membership:
This example sets the current pset to contain every process and thread (at the time of the snapshot) in all except process 1 and its number 1 thread:
(prism all) pset snapshot (all - 1.1) |
Because you have used the snapshot argument, all threads except 1.1 become the current pset. Unless you explicitly change the current pset (for example, by issuing another pset command), the current pset will continue to have the same members, even though new threads have been created.
Displays the execution status of pset members. The pstatus command is available only in the MP Prism environment.
pstatus [pset_name | pset_definition] |
Use the pstatus command to display the execution status of the members of the pset you specify. See define pset for a discussion of how to define a pset. If you issue pstatus with no arguments, it displays the execution status of the members of the current pset. Pset members that have the same status are grouped together.
Adds a Prism command to the tear-off region of the main window of the Prism graphic user interface.
pushbutton label command |
Use the pushbutton command to create a customized button in the tear-off region. The button will have the label you specify; clicking on it will execute the command you specify. The label must be a single word. The command can be any valid Prism command, along with its arguments.
To remove a button created via the pushbutton command, either enter tear-off mode and click on the button, or issue the untearoff command, using label as its argument.
Changes you make to the tear-off region are saved when you leave the Prism environment.
This command is not available in the commands-only interface of the Prism environment.
This command creates a button labeled printfoo that executes the command print foo on dedicated:
pushbutton printfoo print foo on dedicated
Displays the path name of the current working directory.
pwd |
Use the pwd command to display the path name of the current working directory in the Prism environment.
The Prism environment's pwd command is identical to its Solaris counterpart. See your Solaris documentation for more information.
quit [-all] |
Issue the quit command to immediately leave the Prism environment. Note that, unlike its menu equivalent, quit does not ask you if you are sure you want to quit.
When issued in the primary Prism session (of a multiple session), the quit command does not propagate down to the secondary sessions unless you issue the command with the -all option.
If the job was run by the primary Prism session, the command quit -all will kill the debuggees in the primary as well as the secondary Prism sessions and close all the Prism sessions.
If you attached to the job in the primary Prism session, then quit -all will leave the debuggees running and close all the Prism sessions.
The -all option is valid only in the primary Prism session.
The quit entry on the Prism File menu is the same as the Prism (command-line) quit command. To quit all Prism sessions, you must type
For information about debugging multiple sessions, sessions spawned using calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see the Prism User's Guide.
Reloads the currently loaded program.
reload |
Use the reload command to reload the program currently loaded in the Prism environment.
Reruns the currently loaded program, using arguments previously passed to the program.
rerun [args] [< filename] [> filename] |
Use the rerun command to execute the program currently loaded in the Prism environment. If you do not specify args, rerun uses the argument list previously passed to the program. Otherwise, rerun is identical to the run command. You can specify any command-line arguments as args, and you can redirect input or output using < or > in the standard Solaris manner.
When you issue the rerun command in a primary Prism session, the Prism environment will clean up any the secondary Prism sessions spawned by that session. That is, the Prism environment will shut down the secondary Prism sessions and the debuggees.
For information about debugging multiple sessions, sessions spawned using calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see the Prism User's Guide.
Steps out to the caller of the current function.
return [count] [pset pset_name | pset_definition] |
Use the return command to execute the current function, then return to its caller.
If you specify an integer as an argument, return steps out the specified number of levels in the call stack.
return is a synonym for stepout.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Executes the currently loaded program.
run [args] [< filename] [> filename] |
Use the run command to execute the program currently loaded in the Prism environment. Specify any command-line arguments as args. You can also redirect input or output using < or > in the standard Solaris manner.
When you issue the run command in a primary Prism session, the Prism environment will clean up any the secondary Prism sessions spawned by that session. That is, the Prism environment will shut down the secondary Prism sessions and the debuggees.
For information about debugging multiple sessions, sessions spawned using calls to MPI_Comm_spawn() or MPI_Comm_spawn_multiple(), see the Prism User's Guide.
You can use the default alias r for this command.
Chooses the master pane in a split source window.
select file_extension |
Use the select command to choose the "master pane" when the source window is split into more than one pane. The master pane will contain the code with the file extension you specify as the argument to select.
The Prism environment interprets unqualified line numbers in commands in terms of the source code in the master pane. It also uses the master pane to determine the source code and language to use in displaying messages, events, the call stack, and so on.
Scrolling through the master pane causes the slave pane to scroll to the corresponding location. You can scroll the slave pane independently, but this does not cause the master pane to scroll.
When used in the commands-only interface of the Prism environment, select determines the programming language used to display messages, events, and so on.
To make the pane containing the loaded program's assembly code the master pane:
select .s
To select the pane containing the Fortran 77 source code to be the master pane:
select .f
Defines abbreviations and sets values for variables.
set variable = expression |
Use the set command to define other names (typically abbreviations) for variables and expressions. The names you choose cannot conflict with names in the program loaded in the Prism environment; they are expanded to the corresponding variable or expression within other commands. For example, if you issue this command:
set x = variable_with_a_long_name
print x
print variable_with_a_long_name
In addition to print and display, the whatis, whereis, and which commands recognize variables set using the set command. For example, issuing the command whatis x after issuing the set command above produces this response:
user-set variable, x = variable_with_a_long_name
In addition, you can use the set command to set the value of certain internal variables used by the Prism environment. These variables begin with a $ so that they will not conflict with the names of user-set variables. You may change the settings of these internal variables:
Issue the set command with no arguments to display your current settings.
Issue the unset command to remove a user-defined setting.
Displays or sets an environment variable.
setenv [variable [setting]] |
Use the setenv command to set an environment variable within the Prism environment. With no arguments, setenv displays all current settings.
Environment variables become defined or undefined in the Prism environment at the moment that setenv or unsetenv is executed. The program to be debugged inherits the Prism environment at the moment that the target program is executed. For this reason, changes to the Prism environment by setenv and unsetenv do not affect any other processes that are already running.
Although the Prism environment, and any programs executed within it, inherits its environment from the shell that created it, the setenv and unsetenv commands do not affect the shell that started the Prism environment, or the Prism executable itself.
The Prism environment's setenv command is identical to its Solaris C shell counterpart. See your Solaris documentation for more information.
Passes a command line to the shell for execution.
sh [command_line] |
Use the sh command to execute a Solaris command line from a shell; the response is displayed in the history region. If you don't specify a command line, the Prism environment invokes an interactive shell in a separate window. The setting of your SHELL environment variable determines which shell is used; if it isn't set, the C shell is used.
You cannot redirect the output of this command.
Splits the source window to display the file with the specified extension.
show file_extension |
Use the show command to split the source window and display the assembly code, or the version of the source code with the specified extension, in the new pane.
The show command is not meaningful in the commands-only interface of the Prism environment.
Use the hide command to cancel the display of the assembly code or source-code version and return to a single source window.
To display the assembly code for the loaded program, issue this command:
show .s
show events [processnumber] [on windowname] |
Use the show events command to print the event list. The list includes an ID for each command; you use this ID when issuing the delete command to delete an event from the event list. You can use the enable and disable commands to control whether specified events in the event list affect execution. See the enable, delete, and disable commands for further information.
show events on ded brings up the Event Table window, just as though you selected the Event Table option from the Events menu.
If you use the optional argument processnumber, the show events command reports only for the process number specified. If processnumber is not specified, all events are displayed.
|
Note - The show events command does not accept a pset qualifier. |
You can use the default alias j for this command.
Displays the contents of a pset. This command is available only in the MP Prism environment.
show pset [pset_name | pset_definition] |
Use the show pset command to display the contents of the pset you specify. (See the define pset command for a discussion of how to define a pset.) With no arguments, show pset displays the contents of the current pset.
To display the contents of the pset stopped:
show pset stopped The set contains the following processes: 0:3. |
Displays information about all psets. This command is available only in the MP Prism environment.
show psets |
Use the show psets command to display information about all currently defined psets. The output includes each set's definition, members, and current process. The sets listed include user-named sets, predefined sets, and sets that the user has defined but not named.
In either the graphical interface, or in the commands-only interface of the Prism environment started with the -CX option, issuing the command show psets on dedicated displays the Psets window.
Here is sample output from a show psets command:
source filename |
Use the source command to read in and execute Prism commands from filename. This is useful if, for example, you have redirected the output of a show events command to a file, thereby saving all events from a previous session.
In the file, the Prism environment interprets lines beginning with # as comments. If \ is the final character on a line, the Prism environment interprets it as a continuation character.
status |
Use the status command to display the event list. The list includes an ID for each command; you use this ID when issuing the delete command to delete an event. You can use the enable and disable commands to control whether specified events in the event list affect execution. See the enable, delete, and disable commands for further information.
status is a synonym for the show events command.
You can use the default alias j for this command.
Executes one or more source lines.
step [n] [pset pset_name | pset_definition] |
Use the step command to execute the next n source lines, stepping into procedures and functions. If you do not specify a number, step executes the next source line.
You can use the default alias s for this command.
You can repeat this command by pressing Enter.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Executes one or more machine instructions.
stepi [n] [pset pset_name | pset_definition] |
Use the stepi command to execute the next n machine instructions, stepping into procedures and functions. If you do not specify a number, stepi executes the next machine instruction.
You can repeat this command by pressing Enter.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Steps out to the caller of the current function.
stepout [count] |
Use the stepout command to execute the current function, then return to its caller. If you specify an integer as an argument, stepout steps out the specified number of levels in the call stack.
return is a synonym for stepout.
stop [var | at line | in func] [if expression] [{cmd; cmd ...}] [after n] [silent | disabled] [pset pset_name | pset_definition] |
Use the stop command to set a breakpoint at which the program is to stop execution. You can abbreviate this command to st.
The first option listed in the synopsis (var | at line | in func) must come first on the command line; you can specify the other options, if you include them, in any order.
var is the name of a variable. Execution stops whenever the value of the variable changes. If the variable is an array or a parallel variable, execution stops when the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a location.
at line stops execution when the specified line is reached. If the line is not in the current file, use the form "filename":line_number, using quotation marks around the file name.
in func stops execution when the specified procedure or function is reached. Note that the Prism environment uniformly treats main (the program's entry point) and MAIN (the main subroutine of the Fortran program) as separate and distinct entities. stop in MAIN will consistently give you different results than stop in main.
if expression specifies the logical condition, if any, under which execution is to stop. The logical condition can be any expression that evaluates to true or false. Unless combined with the at line syntax, this form of stop slows execution considerably.
{cmd; cmd ...} specifies the actions, if any, that are to accompany the breakpoint. Put the actions in braces. The actions can be any Prism commands; if you include multiple commands, separate them with semicolons.
after n specifies how many times a trigger condition (for example, reaching a program location) is to occur before the breakpoint occurs. The default is 1. If you specify both a condition and an after count, the Prism environment checks the condition first.
silent allows you to create the event and gives the event the same attribute as if you had specified y in the silent field of the Event Table of the Prism graphic interface. disabled allows you to create the event, but the event is disabled as if you had specified n in the enabled field of the Event Table of the Prism graphic interface.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To stop execution the tenth time in the function foo, print a, and execute the where command:
stop in foo {print a; where} after 10
To stop execution at line 17 of file bar if a is equal to 0:
stop at "bar":17 if a == 0
To stop execution whenever the value of a changes:
stop a
To stop execution the third time a equals 5:
stop if a .eq. 5 after 3
Sets a breakpoint at a machine instruction.
stopi [var | at addr | in func] [if expression] [{cmd; cmd ...}] [after n] [silent | disabled] [pset pset_name | pset_definition] |
Use the stopi command to set a breakpoint at a machine instruction.
The first option listed in the synopsis (var | at addr | in func) must come first on the command line; you can specify the other options, if you include them, in any order.
var is the name of a variable. Execution stops whenever the value of the variable changes. If the variable is an array or a parallel variable, execution stops when the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a location.
at addr stops execution when the specified address is reached.
in func stops execution when the specified procedure or function is reached. Note that the Prism environment uniformly treats main (the program's entry point) and MAIN (the main subroutine of the Fortran program) as separate and distinct entities. stop in MAIN will consistently give you different results than stop in main.
if expression specifies the logical condition, if any, under which execution is to stop. The logical condition can be any expression that evaluates to true or false. Unless combined with the at addr syntax, this form of stopi slows execution considerably.
{cmd; cmd ...} specifies the actions, if any, that are to accompany the breakpoint. The actions can be any Prism commands; if you include multiple commands, separate them with semicolons.
after n specifies how many times a trigger condition (for example, reaching a program location) is to occur before the breakpoint occurs. The default is 1. If you specify both a condition and an after count, the Prism environment checks the condition first.
silent allows you to create the event and gives the event the same attribute as if you had specified y in the silent field of the Event Table of the Prism graphic interface. disabled allows you to create the event, but the event is disabled as if you had specified n in the enabled field of the Event Table of the Prism graphic interface.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To stop execution at address 1000 (hex):
stopi at 0x1000
To stop execution at address 500 (hex) if a is equal to 0:
stopi at 0x500 if a == 0
Shows information about a specified (by address) synchronization object (mutex lock).
sync -info [addr] [pset pset_name | pset_definition] |
Shows information about the specified (by address) synchronization object (mutex lock), such as which thread it blocks or which thread owns the locks.
This command requires the MP Prism environment. If used with a pset qualifier, it applies to the threads in each of the processes with members belonging to the pset you specify. If used without a pset qualifier, it applies to the threads in each of the processes with members belonging to the current pset.
Lists all synchronization objects (mutex locks) for the last-stopped thread in processes with members in the current (or specified) pset.
syncs [pset pset_name | pset_definition] |
Lists all synchronization objects (and their addresses) known to libthread.
This command requires the MP Prism environment. If used with a pset qualifier, it applies to the threads in each of the processes with members belonging to the pset you specify. If used without a pset qualifier, it applies to the threads in each of the processes with members belonging to the current pset.
Places a menu selection in the tear-off region.
tearoff "selection" |
Use the tearoff command to add a menu selection to the tear-off region of the main window of the Prism environment. Put the selection name in quotation marks. Case and blank spaces don't matter, and you can omit the three dots that indicate that choosing the selection displays a dialog box. If the selection name is available in more than one menu, put the name of the menu you want in parentheses after the selection name.
Use the untearoff command to remove a menu selection from the tear-off region.
Changes you make to the tear-off region are saved when you leave the Prism environment.
This command is not available in the commands-only interface of the Prism environment.
To put the File selection in the tear-off region:
tearoff "file"
To put the Print selection from the Events menu in the tear-off region:
tearoff "print (events)"
Displays information about the last-stopped thread on each process with members in the current (or specified) pset.
thread [-option] [pset pset_name | pset_definition] |
Use the thread command to view information about the last-stopped thread.
If you omit the pset specification, thread displays the ID of the last-stopped thread.
For information about thread states, see TABLE 3.
This command requires the MP Prism environment. If used with a pset qualifier, it applies to the last-stopped thread in each of the processes with members belonging to the pset you specify. If used without a pset qualifier, it applies to the last-stopped thread in each of the processes with members in the current pset.
Displays a list of threads belonging to the processes in the current pset.
threads [-all] [-mode all | filter] [pset pset_name | pset_definition] |
Use the threads command to view a list of threads belonging to the processes in the current pset.
The options of the threads command are:
This command requires the MP Prism environment. If used with a pset qualifier, it applies to the threads in each of the processes with members belonging to the pset you specify. If used without a pset qualifier, it applies to the threads in each of the processes with members belonging to the current pset.
trace [var | at line | in func] [if expression] [{cmd; cmd ...}] [after n] [silent | disabled] [pset pset_name | pset_definition] |
Use the trace command to print tracing information when the program is executed. In a trace, the Prism environment prints a message in the command window when a program location is reached, a value changes, or a condition becomes true; it then continues execution.
The first option listed in the synopsis (var | at line | in func) must come first on the command line; you can specify the other options, if you include them, in any order.
var is the name of a variable. The value of the variable is displayed whenever it changes. If the variable is an array or a parallel variable, values are displayed if the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a location.
at line specifies that the line is to be printed immediately prior to its execution. If the line is not in the current file, use the form "filename":line_number, placing the file name between quotation marks. You can also specify a line number without the at; the Prism environment will interpret it as a line number rather than a variable.
in func causes tracing information to be printed only while executing inside the specified procedure or function.
if expression specifies the logical condition, if any, under which tracing is to occur. The logical condition can be any expression that evaluates to true or false. Unless combined with the at line syntax, this form of trace slows execution considerably.
{cmd; cmd ...} specifies the actions, if any, that are to accompany the trace. Put the actions in braces. The actions can be any Prism commands; if you include multiple commands, separate them with semicolons.
after n specifies how many times a trigger condition (for example, reaching a program location) is to occur before the trace occurs. The default is 1. If you specify both a condition and an after count, the Prism environment checks the condition first.
When tracing source lines, the Prism environment steps into procedure calls if they have source associated with them. It "nexts" over them if they do not have source. See next for more information.
silent allows you to create the event and gives the event the same attribute as if you had specified y in the silent field of the Event Table of the Prism graphic interface. disabled allows you to create the event, but the event is disabled as if you had specified n in the enabled field of the Event Table of the Prism graphic interface.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To do a trace, print the value of a, and execute the where command at every source line:
trace {print a; where}
To trace line 17 if a is greater than 10:
trace at 17 if a .gt. 10
trace "bar":20
tracei [var | at addr | in func] [if expression] [{cmd; cmd ...}] [after n] [silent | disabled] [pset pset_name | pset_definition] |
Use the tracei command to trace machine instructions when the program is executed.
The first option listed in the synopsis (var | at addr | in func) must come first on the command line; you can specify the other options, if you include them, in any order.
var is the name of a variable. The value of the variable is displayed whenever it changes. If the variable is an array or a parallel variable, values are displayed if the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a location.
at addr causes a message to be displayed immediately prior to the execution of the specified address.
in func causes tracing information to be displayed only while executing inside the specified procedure or function.
if expression specifies the logical condition, if any, under which tracing is to occur. The logical condition can be any expression that evaluates to true or false. Unless combined with the at addr syntax, this form of tracei slows execution considerably.
{cmd; cmd ...} specifies the actions, if any, that are to accompany the trace. Put the actions in braces. The actions can be any Prism commands; if you include multiple commands, separate them with semicolons.
after n specifies how many times a trigger condition (for example, reaching a program location) is to occur before the trace occurs. The default is 1. If you specify both a condition and an after count, the Prism environment checks the condition first.
When tracing instructions, the Prism environment follows all procedure calls down.
silent allows you to create the event and gives the event the same attribute as if you had specified y in the silent field of the Event Table of the Prism graphic interface. disabled allows you to create the event, but the event is disabled as if you had specified n in the enabled field of the Event Table of the Prism graphic interface.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To trace the instruction at address 1000 (hex) the third time it is reached:
tracei 0x1000 after 3
To trace the instruction at address 500 (hex) if a is equal to 0:
tracei 0x500 if a == 0
Specifies the data type of a Sun Scalable Scientific Subroutine Library (Sun S3L) array handle, allowing the Prism environment to display and visualize S3L arrays of as many as seven dimensions.
type datatype variable |
Use the type command to notify the Prism environment that a specified program variable is an S3L array descriptor, and to specify the specific basic data type of the S3L array. Basic data types are int, float, double, complex8, and complex16. Before using the type command, the Prism environment recognizes the array handle as a simple variable. In Fortran 77 and Fortran 90, the array handle is a variable of type integer*8. In C, the array handle is type S3L_array_t.
The basic type used in the type command must match the basic type of the S3L array in the program.
Once you have specified the correct data type, the Prism environment can display the S3L array using the print command.
To visualize a with one of the Prism visualizers:
(prism all) print a on dedicated
To gather information on where the elements of a are distributed:
(prism all) print layout(a) on dedicated
To assign a value to one or more elements of a:
(prism all) assign a(2,3) = 5.0
unalias name |
Use the unalias command to remove the alias with the specified name. Issue the alias command with no arguments to obtain a list of your current aliases.
unset name |
Use the unset command to delete the setting associated with name. See the set command for a discussion of setting names for variables and expressions.
Do not use the unset command to unset any of the Prism internal variables (variable names beginning with $).
If you use the set command to set this abbreviation for a variable name:
set fred = frederick_bartholomew
then you can unset it as follows:
unset fred
In this example, after issuing the unset command, you can no longer use fred as an abbreviation for frederick_bartholomew.
Unsets an environment variable.
unsetenv variable |
Use the unsetenv command to remove the specified environment variable.
Environment variables become defined or undefined in the Prism environment at the moment that setenv or unsetenv is executed. The program to be debugged inherits the Prism environment at the moment that the target program is executed. For this reason, changes to the Prism environment by setenv and unsetenv do not affect any processes that are already running.
Although the Prism environment, and any programs executed within it, inherits its environment from the shell that created it, the setenv and unsetenv commands do not affect the shell that started the Prism environment, or the Prism environment itself.
The Prism environment's unsetenv command is identical to its Solaris C shell counterpart. See your Solaris documentation for more information.
Removes a button from the tear-off region.
untearoff "label" |
Use the untearoff command to remove a button from the tear-off region of the main window of the Prism environment. Put the button's label in quotation marks. Case and blank spaces don't matter, and you can omit the three dots that indicate that clicking the button displays a dialog box. If the tear-off region includes more than one button with the same label, include the name of the selection's menu in parentheses after the label.
Changes you make to the tear-off region are saved when you leave the Prism environment.
This command is not available in the commands-only interface of the Prism environment.
To remove the Load button from the tear-off region:
untearoff "load"
To remove the button that executes the Print selection from the Events menu:
untearoff "print (events)"
Moves the symbol lookup context up one level in the call stack.
up [count] |
Use the up command to move the current function up the call stack count levels (that is, away from the current stopping point in the program toward the main procedure). If you omit count, the default is one level.
Issuing up repositions the source window at the new current function.
After a series of up commands, the Prism environment attempts to preserve the level when the current process changes.
Adds a directory to the list of directories to be searched when looking for source files.
use [directory] |
Issue the use command to add directory to the front of the list of directories the Prism environment is to search when looking for source files. This is useful if you have moved a source file since compiling the program, or if for some other reason the Prism environment can't find a file. If you do not specify a directory, use prints the current list.
No matter what the contents of the directory list is, the Prism environment always searches first in the directory in which the program was compiled.
Save the value of a variable or expression to a file.
varsave "filename" expression |
Use the varsave command to save the value of the variable or expression specified by expression to the file filename. You can subsequently restore the values in filename via the varfile intrinsic (except in the MP Prism environment) and compare them with another version of the variable or expression via the Diff or Diff With selection from a visualizer's Options menu.
To save the value of the variable alpha in the file alpha.data (in your current working directory within the Prism environment):
varsave "alpha.data" alpha
To save the results of the expression alpha*2 in the file with the path name
/u/kathy/alpha2.data:
varsave "/u/kathy/alpha2.data" alpha*2
Waits for a process or processes to stop execution. The wait command is available only in the MP Prism environment.
wait [every | any] [pset pset_name | pset_definition] |
Use the wait command to tell the Prism environment to wait for the specified process or processes to stop execution before accepting commands that affect other processes (for example, commands that start or stop execution). A process is considered to have stopped if it has entered the done, break, interrupted, or error state.
This command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Use the form wait or wait every to wait for every process in the pset to stop execution. The default is wait every.
Use the form wait any to wait for any running process in the pset to stop execution.
You can end the wait by doing one of the following:
Displays the declaration of a name.
whatis [struct | class | enum | union] name [pset pset_name | pset_definition] |
Use the whatis command to display information about a specified name in the program.
The Prism environment displays type information using the syntax of the source language (the language of the definition, not the declaration). In programs written in a mixture of Fortran and C, the Prism environment displays each declaration in the appropriate language.
When a keyword (struct, class, enum, or union) is present, the Prism environment treats name as a type name. The keyword resolves ambiguities where there are types and variables with the same name.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
To display information about Name (by default, the declaration is assumed to be the declaration of a variable, not a type):
(prism) whatis Name Name *Name; |
Use the struct keyword to ask about a type. In this example there are two types spelled Name. One Name is a typedef:
(prism) whatis struct Name More than one identifier 'Name'. Select one of the following names: 0) Cancel 1) `a.out`whatis.c`struct Name 2) `a.out`whatis.c`Name > 2 typedef struct Name Name; |
Sets a breakpoint. The when command is similar to the stop command.
when [var | at line | in func | stopped] [if expr] [{cmd [; cmd ...]}] [after n] |
Use the when command to set a breakpoint at which the program is to stop execution.
The first option listed in the synopsis (var | at line | in func | stopped) must come first on the command line; you can specify the other options, if you include them, in any order.
var is the name of a variable. Execution stops whenever the value of the variable changes. If the variable is an array or a parallel variable, execution stops when the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a location.
at line stops execution when the specified line is reached. If the line is not in the current file, use the form "filename":line_number, placing the file name between quotation marks.
in func stops execution when the specified procedure or function is reached.
stopped specifies that the actions associated with the command occur every time the program stops execution.
if expr specifies the logical condition, if any, under which execution is to stop. The logical condition can be any expression that evaluates to true or false. Unless combined with the at line syntax, this form of when slows execution considerably.
{cmd; cmd ...} specifies the actions, if any, that are to accompany the breakpoint. Put the actions in curly braces. The actions can be any Prism commands; if you include multiple commands, separate them with semicolons.
after n specifies how many times a location is to be reached before the breakpoint occurs. The default is 1. If you specify both a condition and an after count, the Prism environment checks the condition first.
To print the value of a in a dedicated window whenever execution stops:
when stopped {print a on dedicated}
where [count] [pset pset_name | pset_definition] |
Use the where command to print out a list of the active procedures and functions on the call stack. With no argument, where displays the entire list. If you specify count, where displays the specified number of functions.
The where command reports all active stack frames that have a stack pointer. The where command does not report routines that have no frame pointer and routines that have been inlined.
You can use the default alias t for this command.
In the graphical mode of the Prism environment, the command where on dedicated displays a Where graph, a dynamic call graph of the program.
When issued in the MP Prism environment, this command can take a pset qualifier. If used with a qualifier, it applies to the pset you specify. If used without a qualifier, it applies to the current pset. See Psets: Processes and Threads for more information on pset qualifiers.
Displays the full qualification of all the symbols matching a given identifier.
whereis identifier |
Use the whereis command to display a list of the fully qualified names of all symbols whose name matches identifier. The symbol class (for example, procedure or variable) is also listed.
Use the whatis command on the fully qualified names to determine their types.
whereis x
variable: `a.out`foo.c`foo`x
Displays the fully qualified name of an identifier.
which identifier |
Use the which command to display the fully qualified name of identifier. This indicates which (of several possible) variables or procedures by the name identifier the Prism environment would use at this point in the program (for example, in an expression). The fully qualified name includes the file name or function name with which the identifier is associated.
Use the whatis command on the fully qualified names to determine their types.
For more information on fully qualified names, see the Prism User's Guide.
| Prism 7.0 Software Reference Manual
| 817-0089-10 |
|
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.