StackTraceDoc.tioga
Copyright Ó 1992 by Xerox Corporation. All rights reserved.
Last changed by Pavel on June 22, 1990 8:04 pm PDT
Spreitze, September 13, 1991 6:43 pm PDT
Michael Plass, May 4, 1992 1:32 pm PDT
1. The StackTrace command
Whenever a command generates an uncaught signal, the Commander prompts you to say whether or not you would like to try to debug the problem. One of the allowable responses is ``s'' followed by some arguments. In this case, the Commander invokes the StackTrace command with those arguments. This is the most (only?) useful way to invoke this command.
StackTrace prints out a nicely formatted listing of the stack frames in the current or a given thread. The following options are provided (case is not significant):
-frames n
Print n frames. By default, StackTrace prints 20 frames.
-prefix
Start printing at the very top of the stack. By default, StackTrace doesn't print any frames hotter than the hottest SignalHandler or Raise frame
-allFrames
Print all of the frames on the stack. This overrides the -frames argument.
-pc
Print the program counter associated with each frame. By default, StackTrace suppresses this information. The printed value is the program counter relative to the embedded ``.o'' file.
-fullPc
Print the program counter associated with each frame. By default, StackTrace suppresses this information. All 3 possible interpretations are presented (as `abs/loaded-rel/embedded-rel'): the absolute pc, the pc relative to the loaded file, and the pc relative to the embedded ``.o'' file.
-sp
Print the stack pointer associated with each frame. By default, StackTrace suppresses this information.
-args
Print the values (in hex) of some of the arguments to each frame. StackTrace cannot tell for sure how many arguments there actually, so it may print too many or too few.
-fullProcNames
Print the complete C name of every procedure on the stack. By default, StackTrace strips off any leading underscore and any trailing ``←Pn'' part.
-allDotONames
Often, there are several choices for the name of the ``.o'' file from which a procedure comes. By default, StackTrace prints only the one it thinks is most likely to be correct. The -allDotONames forces StackTrace to print all of the possibilities.
-loadedFile
Print the name of the outermost loaded file containing the pc. By default, StackTrace reveals only the innermost component file (often the UNIX `ld' program, or something similar, is used to package several component .``o'' files into a larger file for improved loading performance.)
-verbose
Turn on all printing options. This is equivalent to the following:
-allFrames -fullProcNames -allDotONames -loadedFile -fullPc -sp
n
Print the stack of frame n. When giving specific threads, you'll probably want to take care to give only threads that aren't executing, as tracing a changing stack can be problematic. StackTrace catches VM.AddressFault, so the usual result will be a trashy listing, rather than an uncaught error.
-
n
Don't print the stack of frame
n. If both
n and -
n are given on the command line, the last one wins. If, at the end of command line processing, no threads are specifically requested, the current thread is printed. If there were a command, say `tls b me', that listed the index of the current thread, the ability to except certain indices could be used to get a list of all processes, other than the current, in a certain state, like this:
% StackTrace -allFrames $(tls b rn ry) -$(tls b me)
2. The ThreadsList command
The ThreadsList command (aka TLS) lists certain basic information for some threads. Those threads can be specified by index or by scheduler state, or allowed to default to `all'. The information is at least thread index, scheduler state, and two bits that indicate whether the thread is `frozen' and whether it has a `debug message' associated with it. The information can also include and stack pointer and/or the program counter.
The arguments are as follows:
f
List threads in scheduler state `free'
ry, rn, m, or c
List threads in scheduler state `ready', `run', `waitingML', or `waitingCV'
o
List threads in unexpected scheduler states
me
List the thread running the command
b
List only indices --- don't indicate scheduler state
sp
List stack pointer of hottest frame
pc
List PC of hottest frame
ptrs
List stack pointer and PC of hottest frame
<n>
List thread <n>
For example:
% tls ptrs ry
0ry,sp:00687B98,pc:004DF03C 1ry,sp:0069EB98,pc:004DF03C 8ry,sp:0073E580,pc:004DF03C 22ry,sp:008822F0,pc:004DF03C
%
The format of an element of the output is:
<index:CARD> [Dbg Fzn <state:{f, ry, rn, m, c, o}>] [,sp:<sp:HexCard>] [,pc:<pc:HexCard>]
The scheduler states are: free, ready, running, waiting on a monitor lock, waiting on a condition variable, and other. A `Dbg' of `*' means the thread has a debug message; and empty `Dbg' means there is no debug message. A `Fzn' of `!' means the thread is frozen; and empty `Fzn' means the thread is not frozen.