10/17/84 trace Syntax as a command: trace {entrypoints} {-control_args} Function: can be used to debug systems of programs, stop execution at any call or return, and measure the resources spent in each program. It helps you isolate which programs might be malfunctioning by tracing calls, returns, argument lists, and signals. A metering mode helps expose inefficient programs by measuring and accumulating real time, virtual CPU time, and page faults spent in each program. The trace facility works with programs written in PL/I, FORTRAN, COBOL, Pascal, and ALM. Arguments: entrypoints represent program entrypoints. You must separate multiple entrypoints by spaces (see "Notes on the syntax of entrypoints"). If you don't use any control arguments, the entrypoints are added to the trace table with the default trace parameters currently in effect. Control arguments (trace parameters): -arguments in|out|on|off, -ag in|out|on|off lists the arguments when the specified entrypoints are traced at call (in), return (out), both (on), or neither (off). Tracing arguments is useful for debugging, but greatly increases the volume of trace information. (Default: initially off) -call COMMAND-LINE executes a command line whenever the specified entrypoints are traced at both call and return, but not at unwind. When COMMAND-LINE contains spaces, quote it. It can't exceed 256 characters. Trace is temporarily disabled while COMMAND-LINE is being executed. Specifying -no_call or -call "" turns off this function. (Default: initially -no_call) -every N, -ev N prevents the specified entrypoints from being traced unless their call count is a multiple of N; for example, -every 10 permits every tenth call to be traced. Specifying -no_every or -every 0 eliminates this constraint. (Default: initially -no_every) -first N, -ft N prevents the specified entrypoints from being traced when their call count is less than N; for example, if an entrypoint's -first is 1000, the first 999 calls are not traced. Specifying -no_first or -first 0 eliminates this constraint. (Default: initially -no_first) -high N prevents the specified entrypoints from being traced when their recursion level is greater than N; for instance, if an entrypoint's -high is 1, no recursive invocations are traced. Specifying -no_high or -high 0 eliminates this constraint. (Default: initially -no_high) -last N, -lt N prevents the specified entrypoints from being traced when their call count is greater than N; for example, -last 1 traces only the first call of each entrypoint. Specifying -no_last or -last 0 eliminates this constraint. (Default: initially -no_last) -low N prevents the specified entrypoints from being traced when their recursion level is less than N; for instance, -low 2 permits only recursive invocations to be traced. Specifying -no_low or -low 0 eliminates this constraint. (Default: initially -no_low) -new_high on|off permits the specified entrypoints to be traced only when their recursion level has reached a new high. It is useful for tracing runaway recursion. (Default: initially off) -no_call turns off the -call function for the specified entrypoints. (Default, initially) -no_every, -nev eliminates the -every constraint for the specified entrypoints. (Default, initially) -no_first, -nft eliminates the -first constraint for the specified entrypoints. (Default, initially) -no_high eliminates the -high constraint for the specified entrypoints. (Default, initially) -no_last, -nlt eliminates the -last constraint for the specified entrypoints. (Default, initially) -no_low eliminates the -low constraint for the specified entrypoints. (Default, initially) -no_stop_every, -nspev eliminates the -stop_every constraint for the specified entrypoints. (Default, initially) -no_stop_low, -nsplow eliminates the -stop_low constraint for the specified entrypoints. (Default, initially) -stop in|out|on|off, -sp in|out|on|off stops execution of the specified entrypoints when they are called (in), when they return (out), both (on), or neither (off). (Default: initially off) -stop_every N, -spev N prevents the specified entrypoints from being stopped unless their call count is a multiple of N; for instance, -stop_every 10 permits every tenth call to be stopped. Execution can be stopped at call, return, or both by specifying -stop in, -stop out, or -stop on. Specifying -no_stop_every or -stop_every 0 eliminates this constraint. (Default: initially -no_stop_every) -stop_low N, -splow N prevents the specified entrypoints from being stopped unless their recursion level is N or greater; for example, -stop_low 2 only stops recursive invocations. Execution can be stopped at call, return, or both by specifying -stop in, -stop out, or -stop on. Specifying -no_stop_low or -stop_low 0 eliminates this constraint. (Default: initially -no_stop_low) -trace in|out|on|off traces the specified entrypoints when they are called (in), when they return (out), both (on), or neither (off). (Default: initially on) Control arguments (global parameters): -alm on|off sets the -alm global parameter on or off. ALM (Assembly Language for Multics) programs sometimes use nonstandard call-return protocols that malfunction when traced, or make trace malfunction. This parameter controls how ALM entrypoints are handled. When -alm is on, they are handled like ordinary entrypoints. When -alm is off, they are ignored by the trace facility, even if they are in the trace table. Initially -alm is off. -automatic on|off, -auto on|off sets the -automatic global parameter on or off. This parameter provides an easy way to trace everything. It automatically adds entrypoints to the trace table when they are first called. Their trace parameters are set to the current defaults. Specifying -automatic on implies -signals on, and specifying -automatic off implies -signals off. If you want automatic mode without signal tracing, specify -automatic on -signals off. Initially -automatic is off. -brief, -bf sets the -brief global parameter, which abbreviates trace messages by excluding the time of the trace event, the caller of the entrypoint being traced, and the meters when the entrypoint returns. This reduces wraparound when the trace is displayed on an 80-column terminal instead of a line printer. Initially -brief is set. -buffer on|off, -buf on|off sets the -buffer global parameter on or off. Specifying -buffer on redirects the trace information to a circular buffer in the process directory. The buffer contains 8192 entries. You can display it with -print_buffer. Buffering is much more efficient than regular tracing, but buffer entries do not have room for argument lists. Initially -buffer is off. -disable, -disa disables trace; for instance, to stop the trace messages, to "freeze" the meters, or to turn trace off when it is not being used. Trace is enabled when you use the trace command for the first time in a process. -enable, -ena reverses the effect of -disable. -long, -lg sets the -long global parameter for full trace messages, which include clock time and meters. This setting is appropriate for a 132-column output device. Initially -brief is set. -loud sets the -loud global parameter, which tells the trace and watch commands to summarize the effect of each command line and warn when trace is disabled. Initially -loud is set. -meter on|off, -mt on|off sets the -meter global parameter on or off. Trace always meters, even if you specify -meter off. Specifying -meter on tells trace to concentrate on metering and skip all trace, stop, and watch checks. The trace_meters command displays and resets the meters. Initially -meter is off. -no_output_file, -nof resets the -output_switch global parameter to its initial value, user_output. -no_output_switch, -nosw resets the -output_switch global parameter to its initial value, user_output. -no_stop_proc, -nspp resets the -stop_proc global parameter to its initial value, the command processor (cu_$cl). -output_file PATH, -of PATH sets the -output_switch global parameter so that the trace is written to the file specified by PATH. The ".trace" suffix is added to PATH if you don't give it; the file is truncated if it already exists, or created if it does not. If the trace was already being written to a file, that file is closed after the new one is opened. Specifying -no_output_file or -output_file "" resets -output_switch to its initial value, user_output. -output_switch SWITCH, -osw SWITCH sets the -output_switch global parameter to SWITCH. This parameter determines the I/O switch through which trace, watch, and stop messages are written. If SWITCH is not attached to the same device as error_output, watch and stop messages are also written to error_output. The switch must be open and prepared to receive stream output. Specifying -no_output_switch or -output_switch "" resets -output_switch to its initial value, user_output. -quiet sets the -quiet global parameter, which tells the trace and watch commands not to summarize the effect of each command line or warn when trace is disabled. Initially -loud is set. -signals on|off, -sig on|off sets the -signals global parameter on or off. It controls whether signaled conditions are traced. Initially -signals is off. -stop_proc ENTRYNAME, -spp ENTRYNAME sets the -stop_proc global parameter to ENTRYNAME, where ENTRYNAME can be any string acceptable to the cv_entry_ subroutine. This parameter is the entrypoint that trace calls to stop execution. It is called with trace temporarily disabled. When the -stop_proc returns, trace is re-enabled and execution resumes. If the -stop_proc is the command processor, the start command makes it return. Specifying -no_stop_proc or -stop_proc "" reset -stop_proc to its initial value, the command processor (cu_$cl). Control arguments (actions): -add adds the specified entrypoints to the trace table. If any of them are already in the trace table, their trace parameters are updated. In either case, their trace parameters assume the current default values amended by any control arguments that specify trace parameters. -off turns the specified entrypoints off. They remain in the trace table, but tracing, watching, stopping, and metering are disabled. When an entrypoint is turned off, calls to it continue to be counted. -on turns the specified entrypoints on. -parameters, -pm displays the default trace parameters and the global parameters. -print_buffer N, -prbuf N displays the last N events in the circular trace buffer (see -buffer). If N is greater than 8191, the entire buffer is displayed. The amount of information displayed depends on whether -brief or -long is in effect. -remove, -rm removes the specified entrypoints from the trace table. -set_defaults, -sdf makes the trace parameters specified in the command line be the defaults. -status, -st displays the counters and trace parameters of the specified entrypoints in the trace table. Use the trace_meters command to display the meters. Notes: If you specify entrypoints and don't specify -add, -remove, -on, -off, or -status, -add is assumed. Execution is stopped either before an entrypoint has pushed its stack frame or after it has popped its stack frame; therefore, its stack frame cannot be inspected. When execution is stopped, trace is temporarily disabled until execution is resumed. The recursion level of an entrypoint is actually the number of invocations that have not yet returned, not the number of recursive invocations, which would be one less since the first invocation is not a recursive invocation. The order of entrypoints in the trace table is determined by their segment numbers and offsets. The table is ordered first by ascending segment number and then by ascending offset. This permits rapid lookup by binary search. Tracing with -automatic on and -meter on typically doubles execution time, but the overhead is excluded from the meters. Tracing with -automatic on and -buffer on typically triples execution time. Tracing with -automatic on and -arguments on into an output file requires about 20 milliseconds to trace each event and typically increases execution time by a factor of 50. It also uses up quota fast. The trace facility can watch virtual memory locations for changes in their contents. See the documentation of the watch command for more information. The trace facility has the following restrictions-- 1. Gates cannot be traced. Trace must be separately invoked in each ring. 2. Some programs use nonstandard call-return protocols that malfunction when traced or make trace malfunction. Programs that look at their caller's stack frame malfunction because trace inserts its own stack frame ahead of every entrypoint that it traces or meters (to detect the return or unwind). The trace facility has a list of some entrypoints that cannot be traced. These entrypoints may be added to the trace table but they are effectively turned off (see -off). The list includes: cobol_control_*, cobol_rts_*, condition_$*, cu_$*, formline_*, fortran_io_*, link_trap_caller_*, lisp_*, nonlocal_goto_$*, pascal_area_management_$*, pascal_errors_$*, pascal_io_$*, pascal_time$*, probe*, ssu_$standalone_invocation, ssu_invocation_$create_standalone, unwind_stack_, and unwinder_. 3. The trace table can hold up to 10,000 entrypoints. 4. An ALM entrypoint can only be traced if it invokes the ALM entry operator. The "entry" and "get_lp" pseudo-ops do this. The first instruction of an ALM entrypoint must be a transfer to the ALM entry operator, otherwise it is effectively turned off (see -off). Entrypoints that do not have segdefs may be added in automatic mode with names like bound_foo_$1234. Notes on the syntax of entrypoints: Trace uses an entryname syntax that is capable of referring to individual entrypoints or sets of entrypoints. An entryname can have the following forms: pathname|entryname designates an entrypoint by the absolute or relative pathname of its segment and by its symbolic offset within that segment (e.g., >sss>bound_fscom2_|copy). pathname same as pathname|[entry pathname]. If pathname contains no "<" or ">" characters, it is interpreted as reference_name. pathname|* designates some or all entrypoints in a segment. If the segment is not bound, it designates all entrypoints. If the segment is bound and the entry portion of the pathname is the name of the bound object, it designates all entrypoints (e.g., >sss>bound_fscom2_|*). If the segment is bound and the entry portion of the pathname is the name of a component of the bound object, it designates all entrypoints in the component (e.g., >sss>copy|*). reference_name$entryname designates an entrypoint by the reference name, absolute pathname, or relative pathname of its segment and by its symbolic offset within that segment (e.g., copy$cp). If reference_name contains "<" or ">" characters, it is interpreted as a pathname, otherwise it is interpreted as a reference name and is located via the search rules for executable segments. reference_name same as reference_name$reference_name. reference_name$* similar to pathname|*, except that the segment is designated by its reference name. * designates all entrypoints in the trace table. If you specify *, you cannot specify any other entrypoints. ----------------------------------------------------------- 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