shtrace (1) --- trace activity in command interpreter 02/22/82 _U_s_a_g_e shtrace { on | debug | all | value | | cl | command_line | cn | compound_node | ex | execution | fn | function | it | iteration | lo | location | ls | linked_strings | nd | node | | ou | onunit | pd | port_descriptor | sr | sv_restore | ss | single_step | sv | sv_save } _D_e_s_c_r_i_p_t_i_o_n 'Shtrace' is a debugging aid intended for those who maintain the Subsystem, particularly its command interpreter. Because of its value in debugging shell programs, it has been released for general use, with the warning that it may change without notice. In essence, 'shtrace' prints the status of a command line or its environment as the command is processed by the shell. Since this involves many operations, there are many potential "checkpoints" within the command interpreter. The 'shtrace' options are intended to pick out the most vital points along a command's path from entry to execution. Each option is specified as a single character-string argument, which, except for special cases, may be abbreviated with a two-character mnemonic. These options are as follows: command_line (cl) The command line is printed as it is read, without processing. (The output from this and other options is preceded by a number in brackets, e.g. [2.1]; the integer part is the lexic level of the command (the number of command inputs currently active), while the fractional part is the node number of the node within its network.) compound_node (cn) The command line is printed after compound nodes have been replaced by temporary command files. function (fn) The command line is printed after all function calls have been evaluated. iteration (it) shtrace (1) - 1 - shtrace (1) shtrace (1) --- trace activity in command interpreter 02/22/82 The command line is printed after all iteration groups have been expanded. execution (ex) The network about to be executed is printed. No compound nodes, functions, or iterations will appear in this version of the command. node (nd) The node about to be executed is printed, along with its arguments. single_step (ss) Just before a network is executed, the command interpreter will stop, prompt for input with the string "continue?", and wait for a reply from the user. Inputs beginning with "n" or "N" cause execution to be terminated; other inputs cause processing of commands to be continued. (This option is most useful when used in conjunction with the "command_line" option.) port_descriptor (pd) The port descriptor table used by the shell to assign files to the standard input and output ports is dumped in symbolic format. Along with a mnemonic for each standard port is printed the file unit associated with it and the source or destination of the data (file or pipe). sv_save (sv) This option causes the shell variables and their values to be printed whenever they are saved on disk (e.g., when a 'stop' or 'save' command is executed). sv_restore (sr) This option causes the shell variables and their values to be printed whenever they are loaded from disk (e.g., when the Subsystem is started by the 'swt' command). linked_strings (ls) Whenever garbage collection takes place in the linked string storage area, a summary of the memory structure is printed. location (lo) Following the execution of each node, the full pathname of the command just executed is printed. | onunit (ou) | Whenever the shell's default onunit is invoked, | the condition that was raised is printed. In addition to these options, there are three "shorthand" shtrace (1) - 2 - shtrace (1) shtrace (1) --- trace activity in command interpreter 02/22/82 options for specifying common combinations. The "on" option turns on the "node" and "execution" traces; "debug" turns on "node", "execution", and "single_step"; "all" turns on all traces available. All traces may be turned off by executing 'shtrace' with no arguments. 'Shtrace' prints on standard output one an octal integer reflecting the last state of the trace control variable, suitable for saving in a shell variable or otherwise record- ing for later use. The special option "value" may be used to simply print the current value of the control variable without changing it. If an octal integer is given as an argument to 'shtrace', that bit pattern is assigned to the trace control variable. Thus, a user's trace options may be changed and then reset to their original state. _E_x_a_m_p_l_e_s shtrace on shtrace shtrace cn ss pd set old_shtrace = [shtrace nd] shtrace [old_shtrace] _S_e_e _A_l_s_o dump (1), _U_s_e_r_'_s _G_u_i_d_e _f_o_r _t_h_e _S_o_f_t_w_a_r_e _T_o_o_l_s _S_u_b_s_y_s_t_e_m _C_o_m_m_a_n_d _I_n_t_e_r_p_r_e_t_e_r shtrace (1) - 3 - shtrace (1)