10/17/84  trace_stack, ts

Syntax as a command:  ts {-control_args}


Function: prints a detailed explanation of the current process stack
history in reverse order (most recent frame first).  For each stack
frame, all available information about the procedure that established
the frame (including, if possible, the source statement last executed),
the arguments to that (the owning) procedure, and the condition
handlers established in the frame are printed.


Control arguments:
-brief, -bf
   suppresses listing of source lines, arguments, and handlers.  It is
   incompatible with -long.
-depth N, -dh N
   dumps only N frames.
-long, -lg
   prints octal dump of each stack frame.
-stack_ptr PTR, -sp PTR
   starts tracing from stack frame at PTR, where PTR is a virtual
   pointer acceptable to cv_ptr_.  PTR points to the stack frame at
   which tracing is to begin.


Notes: This command is most useful after a fault or other error
condition.  If you invoke trace-stack after such an error, the machine
registers at the time of the fault are also printed, as well as an
explanation of the fault.  The source line in which it occurred can be
given if you compile the object segment with the -table option.

For a discussion of the Multics stack frame, see the Programmer's
Reference Manual.


Notes on output format: When you invoke trace_stack with no
-stack_ptr, it first searches backward through the stack for a stack
frame containing saved machine conditions as the result of a signaled
condition.  If such a frame is found, tracing proceeds backward from
that point; otherwise, tracing begins with the stack frame preceding
trace_stack.

If a machine-conditions frame is found and you didn't supply -brief,
trace_stack repeats the system error message describing the fault,
source line, and faulting instruction and a listing of the machine
registers at the time the error occurred.


The command then performs a backward trace of the stack, for N frames
if you gave the -depth argument or else until the beginning of the
stack is reached.

For each stack frame trace_stack prints the offset of the frame, the
condition name if an error occurred in the frame, and the
identification of the procedure that established the frame.  If the
procedure is a component of a bound segment, the bound segment name and
the offset of the procedure within the bound segment are also printed.


Unless you supply -brief, trace_stack then locates and prints the
source line associated with the last instruction executed in the
procedure that owns the frame (i.e., either a call forward or a line
that encountered an error).  The source line can be printed only if the
procedure has a symbol table and if the source for the procedure is
available in your working directory.  If the source line cannot be
printed, trace_stack prints a comment explaining why.

Next, trace_stack prints the machine instruction last executed by the
procedure that owns the current frame.  If the machine instruction is a
call to a PL/I operator, the command also prints the name of the
operator.  If the instruction is a procedure call, trace_stack
suppresses the octal printout of the machine instruction and prints the
name of the procedure being called.


Trace_stack then lists the arguments supplied to the procedure that
owns the current frame and also lists any enabled condition, default,
and cleanup handlers established in the frame.

If you select -long, the command then prints an octal dump of the stack
frame, with eight words per line.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved