1 10/17/84 trace
2
3 Syntax as a command: trace entrypoints -control_args
4
5
6 Function: can be used to debug systems of programs, stop execution at
7 any call or return, and measure the resources spent in each program.
8 It helps you isolate which programs might be malfunctioning by tracing
9 calls, returns, argument lists, and signals. A metering mode helps
10 expose inefficient programs by measuring and accumulating real time,
11 virtual CPU time, and page faults spent in each program. The trace
12 facility works with programs written in PL/I, FORTRAN, COBOL, Pascal,
13 and ALM.
14
15
16 Arguments:
17 entrypoints
18 represent program entrypoints. You must separate multiple
19 entrypoints by spaces see "Notes on the syntax of entrypoints".
20 If you don't use any control arguments, the entrypoints are added to
21 the trace table with the default trace parameters currently in
22 effect.
23
24
25 Control arguments trace parameters:
26 -arguments in|out|on|off, -ag in|out|on|off
27 lists the arguments when the specified entrypoints are traced at
28 call in, return out, both on, or neither off. Tracing
29 arguments is useful for debugging, but greatly increases the volume
30 of trace information. Default: initially off
31 -call COMMAND-LINE
32 executes a command line whenever the specified entrypoints are
33 traced at both call and return, but not at unwind. When
34 COMMAND-LINE contains spaces, quote it. It can't exceed 256
35 characters. Trace is temporarily disabled while COMMAND-LINE is
36 being executed. Specifying -no_call or -call "" turns off this
37 function. Default: initially -no_call
38
39
40 -every N, -ev N
41 prevents the specified entrypoints from being traced unless their
42 call count is a multiple of N; for example, -every 10 permits every
43 tenth call to be traced. Specifying -no_every or -every 0
44 eliminates this constraint. Default: initially -no_every
45 -first N, -ft N
46 prevents the specified entrypoints from being traced when their call
47 count is less than N; for example, if an entrypoint's -first is
48 1000, the first 999 calls are not traced. Specifying -no_first or
49 -first 0 eliminates this constraint. Default: initially
50 -no_first
51
52
53 -high N
54 prevents the specified entrypoints from being traced when their
55 recursion level is greater than N; for instance, if an entrypoint's
56 -high is 1, no recursive invocations are traced. Specifying
57 -no_high or -high 0 eliminates this constraint. Default:
58 initially -no_high
59 -last N, -lt N
60 prevents the specified entrypoints from being traced when their call
61 count is greater than N; for example, -last 1 traces only the first
62 call of each entrypoint. Specifying -no_last or -last 0 eliminates
63 this constraint. Default: initially -no_last
64
65
66 -low N
67 prevents the specified entrypoints from being traced when their
68 recursion level is less than N; for instance, -low 2 permits only
69 recursive invocations to be traced. Specifying -no_low or -low 0
70 eliminates this constraint. Default: initially -no_low
71 -new_high on|off
72 permits the specified entrypoints to be traced only when their
73 recursion level has reached a new high. It is useful for tracing
74 runaway recursion. Default: initially off
75 -no_call
76 turns off the -call function for the specified entrypoints.
77 Default initially
78 -no_every, -nev
79 eliminates the -every constraint for the specified entrypoints.
80 Default initially
81
82
83 -no_first, -nft
84 eliminates the -first constraint for the specified entrypoints.
85 Default initially
86 -no_high
87 eliminates the -high constraint for the specified entrypoints.
88 Default initially
89 -no_last, -nlt
90 eliminates the -last constraint for the specified entrypoints.
91 Default initially
92 -no_low
93 eliminates the -low constraint for the specified entrypoints.
94 Default initially
95 -no_stop_every, -nspev
96 eliminates the -stop_every constraint for the specified entrypoints.
97 Default initially
98
99
100 -no_stop_low, -nsplow
101 eliminates the -stop_low constraint for the specified entrypoints.
102 Default initially
103 -stop in|out|on|off, -sp in|out|on|off
104 stops execution of the specified entrypoints when they are called
105 in, when they return out, both on, or neither off.
106 Default: initially off
107 -stop_every N, -spev N
108 prevents the specified entrypoints from being stopped unless their
109 call count is a multiple of N; for instance, -stop_every 10 permits
110 every tenth call to be stopped. Execution can be stopped at call,
111 return, or both by specifying -stop in, -stop out, or -stop on.
112 Specifying -no_stop_every or -stop_every 0 eliminates this
113 constraint. Default: initially -no_stop_every
114
115
116 -stop_low N, -splow N
117 prevents the specified entrypoints from being stopped unless their
118 recursion level is N or greater; for example, -stop_low 2 only stops
119 recursive invocations. Execution can be stopped at call, return, or
120 both by specifying -stop in, -stop out, or -stop on. Specifying
121 -no_stop_low or -stop_low 0 eliminates this constraint. Default:
122 initially -no_stop_low
123 -trace in|out|on|off
124 traces the specified entrypoints when they are called in, when
125 they return out, both on, or neither off. Default:
126 initially on
127
128
129 Control arguments global parameters:
130 -alm on|off
131 sets the -alm global parameter on or off. ALM Assembly Language
132 for Multics programs sometimes use nonstandard call-return
133 protocols that malfunction when traced, or make trace malfunction.
134 This parameter controls how ALM entrypoints are handled. When -alm
135 is on, they are handled like ordinary entrypoints. When -alm is
136 off, they are ignored by the trace facility, even if they are in the
137 trace table. Initially -alm is off.
138
139
140 -automatic on|off, -auto on|off
141 sets the -automatic global parameter on or off. This parameter
142 provides an easy way to trace everything. It automatically adds
143 entrypoints to the trace table when they are first called. Their
144 trace parameters are set to the current defaults. Specifying
145 -automatic on implies -signals on, and specifying -automatic off
146 implies -signals off. If you want automatic mode without signal
147 tracing, specify -automatic on -signals off. Initially -automatic
148 is off.
149 -brief, -bf
150 sets the -brief global parameter, which abbreviates trace messages
151 by excluding the time of the trace event, the caller of the
152 entrypoint being traced, and the meters when the entrypoint returns.
153 This reduces wraparound when the trace is displayed on an 80-column
154 terminal instead of a line printer. Initially -brief is set.
155
156
157 -buffer on|off, -buf on|off
158 sets the -buffer global parameter on or off. Specifying -buffer on
159 redirects the trace information to a circular buffer in the process
160 directory. The buffer contains 8192 entries. You can display it
161 with -print_buffer. Buffering is much more efficient than regular
162 tracing, but buffer entries do not have room for argument lists.
163 Initially -buffer is off.
164 -disable, -disa
165 disables trace; for instance, to stop the trace messages, to
166 "freeze" the meters, or to turn trace off when it is not being used.
167 Trace is enabled when you use the trace command for the first time
168 in a process.
169 -enable, -ena
170 reverses the effect of -disable.
171
172
173 -long, -lg
174 sets the -long global parameter for full trace messages, which
175 include clock time and meters. This setting is appropriate for a
176 132-column output device. Initially -brief is set.
177 -loud
178 sets the -loud global parameter, which tells the trace and watch
179 commands to summarize the effect of each command line and warn when
180 trace is disabled. Initially -loud is set.
181 -meter on|off, -mt on|off
182 sets the -meter global parameter on or off. Trace always meters,
183 even if you specify -meter off. Specifying -meter on tells trace to
184 concentrate on metering and skip all trace, stop, and watch checks.
185 The trace_meters command displays and resets the meters. Initially
186 -meter is off.
187
188
189 -no_output_file, -nof
190 resets the -output_switch global parameter to its initial value,
191 user_output.
192 -no_output_switch, -nosw
193 resets the -output_switch global parameter to its initial value,
194 user_output.
195 -no_stop_proc, -nspp
196 resets the -stop_proc global parameter to its initial value, the
197 command processor cu_$cl.
198
199
200 -output_file PATH, -of PATH
201 sets the -output_switch global parameter so that the trace is
202 written to the file specified by PATH. The ".trace" suffix is added
203 to PATH if you don't give it; the file is truncated if it already
204 exists, or created if it does not. If the trace was already being
205 written to a file, that file is closed after the new one is opened.
206 Specifying -no_output_file or -output_file "" resets -output_switch
207 to its initial value, user_output.
208
209
210 -output_switch SWITCH, -osw SWITCH
211 sets the -output_switch global parameter to SWITCH. This parameter
212 determines the I/O switch through which trace, watch, and stop
213 messages are written. If SWITCH is not attached to the same device
214 as error_output, watch and stop messages are also written to
215 error_output. The switch must be open and prepared to receive
216 stream output. Specifying -no_output_switch or -output_switch ""
217 resets -output_switch to its initial value, user_output.
218 -quiet
219 sets the -quiet global parameter, which tells the trace and watch
220 commands not to summarize the effect of each command line or warn
221 when trace is disabled. Initially -loud is set.
222 -signals on|off, -sig on|off
223 sets the -signals global parameter on or off. It controls whether
224 signaled conditions are traced. Initially -signals is off.
225
226
227 -stop_proc ENTRYNAME, -spp ENTRYNAME
228 sets the -stop_proc global parameter to ENTRYNAME, where ENTRYNAME
229 can be any string acceptable to the cv_entry_ subroutine. This
230 parameter is the entrypoint that trace calls to stop execution. It
231 is called with trace temporarily disabled. When the -stop_proc
232 returns, trace is re-enabled and execution resumes. If the
233 -stop_proc is the command processor, the start command makes it
234 return. Specifying -no_stop_proc or -stop_proc "" reset -stop_proc
235 to its initial value, the command processor cu_$cl.
236
237
238 Control arguments actions:
239 -add
240 adds the specified entrypoints to the trace table. If any of them
241 are already in the trace table, their trace parameters are updated.
242 In either case, their trace parameters assume the current default
243 values amended by any control arguments that specify trace
244 parameters.
245 -off
246 turns the specified entrypoints off. They remain in the trace
247 table, but tracing, watching, stopping, and metering are disabled.
248 When an entrypoint is turned off, calls to it continue to be
249 counted.
250 -on
251 turns the specified entrypoints on.
252
253
254 -parameters, -pm
255 displays the default trace parameters and the global parameters.
256 -print_buffer N, -prbuf N
257 displays the last N events in the circular trace buffer see
258 -buffer. If N is greater than 8191, the entire buffer is
259 displayed. The amount of information displayed depends on whether
260 -brief or -long is in effect.
261 -remove, -rm
262 removes the specified entrypoints from the trace table.
263
264
265 -set_defaults, -sdf
266 makes the trace parameters specified in the command line be the
267 defaults.
268 -status, -st
269 displays the counters and trace parameters of the specified
270 entrypoints in the trace table. Use the trace_meters command to
271 display the meters.
272
273
274 Notes: If you specify entrypoints and don't specify -add, -remove,
275 -on, -off, or -status, -add is assumed.
276
277 Execution is stopped either before an entrypoint has pushed its stack
278 frame or after it has popped its stack frame; therefore, its stack
279 frame cannot be inspected. When execution is stopped, trace is
280 temporarily disabled until execution is resumed.
281
282 The recursion level of an entrypoint is actually the number of
283 invocations that have not yet returned, not the number of recursive
284 invocations, which would be one less since the first invocation is not
285 a recursive invocation.
286
287
288 The order of entrypoints in the trace table is determined by their
289 segment numbers and offsets. The table is ordered first by ascending
290 segment number and then by ascending offset. This permits rapid lookup
291 by binary search.
292
293 Tracing with -automatic on and -meter on typically doubles execution
294 time, but the overhead is excluded from the meters. Tracing with
295 -automatic on and -buffer on typically triples execution time. Tracing
296 with -automatic on and -arguments on into an output file requires about
297 20 milliseconds to trace each event and typically increases execution
298 time by a factor of 50. It also uses up quota fast.
299
300 The trace facility can watch virtual memory locations for changes in
301 their contents. See the documentation of the watch command for more
302 information.
303
304
305 The trace facility has the following restrictions--
306 1. Gates cannot be traced. Trace must be separately invoked in each
307 ring.
308 2. Some programs use nonstandard call-return protocols that
309 malfunction when traced or make trace malfunction. Programs that
310 look at their caller's stack frame malfunction because trace
311 inserts its own stack frame ahead of every entrypoint that it
312 traces or meters to detect the return or unwind.
313
314
315 The trace facility has a list of some entrypoints that cannot be
316 traced. These entrypoints may be added to the trace table but
317 they are effectively turned off see -off. The list includes:
318 cobol_control_*, cobol_rts_*, condition_$*, cu_$*, formline_*,
319 fortran_io_*, link_trap_caller_*, lisp_*, nonlocal_goto_$*,
320 pascal_area_management_$*, pascal_errors_$*, pascal_io_$*,
321 pascal_time$*, probe*, ssu_$standalone_invocation,
322 ssu_invocation_$create_standalone, unwind_stack_, and unwinder_.
323 3. The trace table can hold up to 10,000 entrypoints.
324 4. An ALM entrypoint can only be traced if it invokes the ALM entry
325 operator. The "entry" and "get_lp" pseudo-ops do this. The
326 first instruction of an ALM entrypoint must be a transfer to the
327 ALM entry operator, otherwise it is effectively turned off see
328 -off. Entrypoints that do not have segdefs may be added in
329 automatic mode with names like bound_foo_$1234.
330
331
332 Notes on the syntax of entrypoints: Trace uses an entryname syntax
333 that is capable of referring to individual entrypoints or sets of
334 entrypoints. An entryname can have the following forms:
335 pathname|entryname
336 designates an entrypoint by the absolute or relative pathname of its
337 segment and by its symbolic offset within that segment e.g.
338 >sss>bound_fscom2_|copy.
339 pathname
340 same as pathname|entry pathname. If pathname contains no "<" or
341 ">" characters, it is interpreted as reference_name.
342
343
344 pathname|*
345 designates some or all entrypoints in a segment. If the segment is
346 not bound, it designates all entrypoints. If the segment is bound
347 and the entry portion of the pathname is the name of the bound
348 object, it designates all entrypoints e.g. >sss>bound_fscom2_|*.
349 If the segment is bound and the entry portion of the pathname is the
350 name of a component of the bound object, it designates all
351 entrypoints in the component e.g. >sss>copy|*.
352 reference_name$entryname
353 designates an entrypoint by the reference name, absolute pathname,
354 or relative pathname of its segment and by its symbolic offset
355 within that segment e.g. copy$cp. If reference_name contains "<"
356 or ">" characters, it is interpreted as a pathname, otherwise it is
357 interpreted as a reference name and is located via the search rules
358 for executable segments.
359
360
361 reference_name
362 same as reference_name$reference_name.
363 reference_name$*
364 similar to pathname|*, except that the segment is designated by its
365 reference name.
366 *
367 designates all entrypoints in the trace table. If you specify *,
368 you cannot specify any other entrypoints.