STACKTRACE CEDAR 10.1 StackTrace A quick debugging aid Copyright 1989, 1992 Xerox Corporation. All rights reserved. Abstract: StackTrace provides a simple command to print a nicely-formatted backtrace of the current or a given thread. It is most useful as called from the Commander's uncaught-signal handler. StackTrace also provides a ThreadsList command (aka TLS), which gives information on the scheduling state of threads. Created by: Linda Howe and Bill Jackson Maintained by: Keywords: stack trace, debugging XEROX Xerox Corporation Palo Alto Research Center 3333 Coyote Hill Road Palo Alto, California 94304 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 List thread 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: [Dbg Fzn ] [,sp:] [,pc:] 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. 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 NewlineDelimiter (cedardoc) styleMark LastEditedJ e1?Nb N 'N!/N  NI boilerplate qo sheadIblockQIitemRfi2CRRv RR z1 VRRRRRRhlRRRRRR7 5RR R  CLIindent?@RR  Idefault23QQ T~ *QYQi