1 10/17/84  trace_stack, ts
 2 
 3 Syntax as a command:  ts {-control_args}
 4 
 5 
 6 Function: prints a detailed explanation of the current process stack
 7 history in reverse order (most recent frame first).  For each stack
 8 frame, all available information about the procedure that established
 9 the frame (including, if possible, the source statement last executed),
10 the arguments to that (the owning) procedure, and the condition
11 handlers established in the frame are printed.
12 
13 
14 Control arguments:
15 -brief, -bf
16    suppresses listing of source lines, arguments, and handlers.  It is
17    incompatible with -long.
18 -depth N, -dh N
19    dumps only N frames.
20 -long, -lg
21    prints octal dump of each stack frame.
22 -stack_ptr PTR, -sp PTR
23    starts tracing from stack frame at PTR, where PTR is a virtual
24    pointer acceptable to cv_ptr_.  PTR points to the stack frame at
25    which tracing is to begin.
26 
27 
28 Notes: This command is most useful after a fault or other error
29 condition.  If you invoke trace-stack after such an error, the machine
30 registers at the time of the fault are also printed, as well as an
31 explanation of the fault.  The source line in which it occurred can be
32 given if you compile the object segment with the -table option.
33 
34 For a discussion of the Multics stack frame, see the Programmer's
35 Reference Manual.
36 
37 
38 Notes on output format: When you invoke trace_stack with no
39 -stack_ptr, it first searches backward through the stack for a stack
40 frame containing saved machine conditions as the result of a signaled
41 condition.  If such a frame is found, tracing proceeds backward from
42 that point; otherwise, tracing begins with the stack frame preceding
43 trace_stack.
44 
45 If a machine-conditions frame is found and you didn't supply -brief,
46 trace_stack repeats the system error message describing the fault,
47 source line, and faulting instruction and a listing of the machine
48 registers at the time the error occurred.
49 
50 
51 The command then performs a backward trace of the stack, for N frames
52 if you gave the -depth argument or else until the beginning of the
53 stack is reached.
54 
55 For each stack frame trace_stack prints the offset of the frame, the
56 condition name if an error occurred in the frame, and the
57 identification of the procedure that established the frame.  If the
58 procedure is a component of a bound segment, the bound segment name and
59 the offset of the procedure within the bound segment are also printed.
60 
61 
62 Unless you supply -brief, trace_stack then locates and prints the
63 source line associated with the last instruction executed in the
64 procedure that owns the frame (i.e., either a call forward or a line
65 that encountered an error).  The source line can be printed only if the
66 procedure has a symbol table and if the source for the procedure is
67 available in your working directory.  If the source line cannot be
68 printed, trace_stack prints a comment explaining why.
69 
70 Next, trace_stack prints the machine instruction last executed by the
71 procedure that owns the current frame.  If the machine instruction is a
72 call to a PL/I operator, the command also prints the name of the
73 operator.  If the instruction is a procedure call, trace_stack
74 suppresses the octal printout of the machine instruction and prints the
75 name of the procedure being called.
76 
77 
78 Trace_stack then lists the arguments supplied to the procedure that
79 owns the current frame and also lists any enabled condition, default,
80 and cleanup handlers established in the frame.
81 
82 If you select -long, the command then prints an octal dump of the stack
83 frame, with eight words per line.