| blob | ee598efd43283a4a94fbf84aa26b166a01984ed4 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PREX 1 "Mar 1, 2004"
7 .SH NAME
8 prex \- control tracing and manipulate probe points in a process or the kernel
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBprex\fR [\fB-o\fR \fItrace_file_name\fR] [\fB-l\fR \fIlibraries\fR] [\fB-s\fR \fIkbytes_size\fR] \fIcmd\fR
13 [\fIcmd-args\fR]...
14 .fi
16 .LP
17 .nf
18 \fBprex\fR [\fB-o\fR \fItrace_file_name\fR] [\fB-l\fR \fIlibraries\fR] [\fB-s\fR \fIkbytes_size\fR] \fB-p\fR \fIpid\fR
19 .fi
21 .LP
22 .nf
23 \fBprex\fR \fB-k\fR [\fB-s\fR \fIkbytes_size\fR]
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 The \fBprex\fR command is the part of the Solaris tracing architecture that
30 controls probes in a process or the kernel. See \fBtracing\fR(3TNF) for an
31 overview of this tracing architecture, including example source code using it.
32 .sp
33 .LP
34 \fBprex\fR is the application used for external control of probes. It
35 automatically preloads the \fBlibtnfprobe\fR library. \fBprex\fR locates all
36 the probes in a target executable or the kernel and provides an interface for
37 the user to manipulate them. It allows a probe to be turned on for tracing,
38 debugging, or both. Tracing generates a \fBTNF\fR (Trace Normal Form) trace
39 file that can be converted to \fBASCII\fR by \fBtnfdump\fR(1) and used for
40 performance analysis. Debugging generates a line to standard error whenever the
41 probe is hit at run time.
42 .sp
43 .LP
44 \fBprex\fR does not work on static executables. It only works on dynamic
45 executables.
46 .SS "Invoking prex"
47 .sp
48 .LP
49 There are three ways to invoke \fBprex\fR:
50 .RS +4
51 .TP
52 1.
53 Use \fBprex\fR to start the target application \fIcmd\fR. In this case, the
54 target application need not be built with a dependency on \fBlibtnfprobe\fR.
55 See \fBTNF_PROBE\fR(3TNF). \fBprex\fR sets the environment variable
56 \fBLD_PRELOAD\fR to load \fBlibtnfprobe\fR into the target process. See
57 \fBld\fR(1). \fBprex\fR then uses the environment variable \fBPATH\fR to find
58 the target application.
59 .RE
60 .RS +4
61 .TP
62 2.
63 Attach \fBprex\fR to a running application. In this case, the running target
64 application should have \fBlibtnfprobe\fR already linked in. Alternatively, the
65 user may manually set \fBLD_PRELOAD\fR to include \fBlibtnfprobe.so.1\fR prior
66 to invoking the target.
67 .RE
68 .RS +4
69 .TP
70 3.
71 Use \fBprex\fR with the \fB-k\fR option to set \fBprex\fR to \fBkernel
72 mode\fR. \fBprex\fR can then be used to control probes in the Solaris kernel.
73 In kernel mode, additional commands are defined, and some commands that are
74 valid in other modes are invalid. See \fBKernel\fR \fBMode\fR below.
75 .RE
76 .SS "Control File Format and Command Language"
77 .sp
78 .LP
79 In a future release of \fBprex\fR, the command language may be moved to a
80 syntax that is supported by an existing scripting language like \fBksh\fR(1).
81 In the meantime, the interface to \fBprex\fR is uncommitted.
82 .RS +4
83 .TP
84 .ie t \(bu
85 .el o
86 Commands should be in \fBASCII\fR.
87 .RE
88 .RS +4
89 .TP
90 .ie t \(bu
91 .el o
92 Each command is terminated with the NEWLINE character.
93 .RE
94 .RS +4
95 .TP
96 .ie t \(bu
97 .el o
98 A command can be continued onto the next line by ending the previous line with
99 the backslash ("\fB\e\fR") character.
100 .RE
101 .RS +4
102 .TP
103 .ie t \(bu
104 .el o
105 Tokens in a command must be separated by whitespace (one or more spaces or
106 tabs).
107 .RE
108 .RS +4
109 .TP
110 .ie t \(bu
111 .el o
112 The "\fB#\fR" character implies that the rest of the line is a comment.
113 .RE
114 .SS "Basic prex Commands"
115 .sp
117 .sp
118 .TS
119 c c
120 l l .
121 Command Result
122 _
123 % \fBprex a.out\fR T{
124 Attaches \fBprex\fR to your program and starts \fBprex\fR.
125 T}
126 prex> \fBenable $all\fR Enables all the probes.
127 prex> \fBquit resume\fR T{
128 Quits \fBprex\fR and resumes execution of program.
129 T}
130 .TE
132 .SS "Control File Search Path"
133 .sp
134 .LP
135 There are two different methods of communicating with \fBprex\fR:
136 .RS +4
137 .TP
138 .ie t \(bu
139 .el o
140 By specifications in a control file. During start-up, \fBprex\fR searches for a
141 file named \fB\&.prexrc\fR in the directories specified below. \fBprex\fR does
142 not stop at the first one it finds. This way a user can override any defaults
143 that are set up. The search order is:
144 .sp
145 .in +2
146 .nf
147 $HOME/
148 \&./
149 .fi
150 .in -2
151 .sp
153 .RE
154 .RS +4
155 .TP
156 .ie t \(bu
157 .el o
158 By typing commands at the \fBprex\fR prompt.
159 .RE
160 .sp
161 .LP
162 The command language for both methods is the same and is specified in USAGE.
163 The commands that return output will not make sense in a control file. The
164 output will go to standard output.
165 .sp
166 .LP
167 When using \fBprex\fR on a target process, the target will be in one of two
168 states, running or stopped. This can be detected by the presence or absence of
169 the \fBprex>\fR prompt. If the prompt is absent, it means that the target
170 process is running. Typing Control-C will stop the target pr ocess and return
171 the user to the prompt. There is no guarantee that Control-C will return to a
172 \fBprex\fR prompt immediately. For example, if the target process is stopped on
173 a job control stop (\fBSIGSTOP\fR), then Control-C in \fBprex\fR will wait
174 until the target has been continued (\fBSIGCONT\fR). See \fBSignals to Target
175 Program\fR below for more information on signals and the target process.
176 .SH OPTIONS
177 .sp
178 .LP
179 The following options are supported:
180 .sp
181 .ne 2
182 .na
183 \fB\fB-k\fR\fR
184 .ad
185 .RS 22n
186 \fBkernel mode\fR: \fBprex\fR is used to control probes in the Solaris kernel.
187 In kernel mode, additional commands are defined, and some commands valid in
188 other modes are invalid. See \fBKernel Mode\fR below.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fB-l\fR \fIlibraries\fR\fR
195 .ad
196 .RS 22n
197 The \fIlibraries\fR mentioned are linked in to the target application using
198 \fBLD_PRELOAD\fR (see \fBld\fR(1)). This option cannot be used when attaching
199 to a running process. The argument to the \fB-l\fR option should be a
200 space-separated string enclosed in double quotes. Each token in the string is a
201 library name. It follows the \fBLD_PRELOAD\fR rules on how libraries should be
202 specified and where they will be found.
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fB-o\fR \fItrace_file_name\fR\fR
209 .ad
210 .RS 22n
211 File to be used for the trace output. \fItrace_file_name\fR is assumed to be
212 relative to the current working directory of \fBprex\fR (that is, the directory
213 that the user was in when \fBprex\fR was started).
214 .sp
215 If \fBprex\fR attaches to a process that is already tracing, the new
216 \fItrace_file_name\fR (if provided) will not be used. If no
217 \fItrace_file_name\fR is specified, the default is
218 \fB/$TMPDIR/trace-\fR\fIpid\fR where \fIpid\fR is the process id of the target
219 program. If \fBTMPDIR\fR is not set, \fB/tmp\fR is used.
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fB-s\fR \fIkbytes_size\fR\fR
226 .ad
227 .RS 22n
228 Maximum size of the output trace file in Kbytes. The default size of the trace
229 \fIkbytes_size\fR is \fB4096\fR (2^10) bytes or \fB4\fR Mbytes for normal
230 usage, and \fB384\fR or \fB384\fR kbytes in kernel mode. The minimum size that
231 can be specified is \fB128\fR Kbytes. The trace file can be thought of as a
232 least recently used circular buffer. Once the file has been filled, newer
233 events will overwrite the older ones.
234 .RE
236 .SH USAGE
237 .sp
238 .LP
239 This section describes the usage of the \fBprex\fR utility.
240 .SS "Grammar"
241 .sp
242 .LP
243 Probes are specified by a list of space-separated selectors. Selectors are of
244 the form:
245 .sp
246 .in +2
247 .nf
248 \fIattribute\fR=\fIvalue\fR
249 .fi
250 .in -2
252 .sp
253 .LP
254 (See \fBTNF_PROBE\fR(3TNF)). The "\fIattribute\fR=" is optional. If it is not
255 specified, it defaults to "\fBkeys=\fR".
256 .sp
257 .LP
258 The \fIattribute\fR or \fIvalue\fR (generically called "spec") can be any of
259 the following:
260 .sp
261 .ne 2
262 .na
263 \fB\fBIDENT\fR\fR
264 .ad
265 .RS 14n
266 Any sequence of letters, digits, _\|, \e\|, ., % not beginning with a digit.
267 \fBIDENT\fR implies an exact match.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBQUOTED_STR\fR\fR
274 .ad
275 .RS 14n
276 Usually used to escape reserved words (any commands in the command language).
277 \fBQUOTED_STR\fR implies an exact match and has to be enclosed in single quotes
278 (' ').
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fBREGEXP\fR\fR
285 .ad
286 .RS 14n
287 An \fBed\fR(1) regular expression pattern match. \fBREGEXP\fR has to be
288 enclosed in slashes (/ /), A / can be included in a \fBREGEXP\fR by escaping it
289 with a backslash \e\|.
290 .RE
292 .sp
293 .LP
294 The following grammar explains the syntax.
295 .sp
296 .in +2
297 .nf
298 selector_list ::= | /* empty */
299 \fIselector_list\fR \fIselector\fR
300 selector ::= \fIspec\fR=\fIspec\fR | /* whitespace around `=' opt */
301 \fIspec\fR
302 spec ::= IDENT |
303 QUOTED_STR |
304 REGEXP
305 .fi
306 .in -2
308 .sp
309 .LP
310 The terminals in the above grammar are:
311 .sp
312 .in +2
313 .nf
314 IDENT = [a-zA-Z_\e.%]{[a-zA-Z0-9_\e.%]}+
315 QUOTED_STR = '[^\en']*' /* any string in single quotes */
316 REGEXP = /[^\en/]*/ /* regexp's have to be in / / */
317 .fi
318 .in -2
320 .sp
321 .LP
322 This is a list of the remaining grammar that is needed to understand the syntax
323 of the command language (defined in next subsection):
324 .sp
325 .in +2
326 .nf
327 filename ::= QUOTED_STR /* QUOTED_STR defined above */
328 spec_list ::= /* empty */ |
329 \fIspec_list\fR \fIspec\fR /* \fIspec\fR defined above */
330 fcn_handle ::= &IDENT /* IDENT defined above */
331 set_name ::= $IDENT /* IDENT defined above */
332 .fi
333 .in -2
335 .SS "Command Language"
336 .RS +4
337 .TP
338 1.
339 Set Creation and Set Listing
340 .sp
341 .in +2
342 .nf
343 \fBcreate $\fIset_name\fR \fIselector_list\fR
344 list sets # list the defined sets\fR
345 .fi
346 .in -2
347 .sp
349 \fBcreate\fR can be used to define a set which contains probes that match the
350 \fIselector_list\fR. The set \fB$all\fR is pre-defined as /.*/ and it matches
351 all the probes.
352 .RE
353 .RS +4
354 .TP
355 2.
356 Function Listing
357 .sp
358 .in +2
359 .nf
360 \fBlist fcns # list the available \fIfcn_handle\fR\fR
361 .fi
362 .in -2
363 .sp
365 The user can list the different functions that can be connected to probe
366 points. Currently, only the debug function called \fB&debug\fR is available.
367 .RE
368 .RS +4
369 .TP
370 3.
371 Commands to Connect and Disconnect Probe Functions
372 .sp
373 .in +2
374 .nf
375 \fBconnect &\fIfcn_handle\fR $\fIset_name\fR
376 connect &\fIfcn_handle\fR \fIselector_list\fR
377 clear $\fIset_name\fR
378 clear \fIselector_list\fR\fR
379 .fi
380 .in -2
381 .sp
383 The \fBconnect\fR command is used to connect probe functions (which must be
384 prefixed by `\fB&\fR\&') to probes. The probes are specified either as a single
385 set (with a `\fB$\fR'), or by explicitly listing the probe selectors in the
386 command. The probe function has to be one that is listed by the \fBlist fcns\fR
387 command. This command does not enable the probes.
388 .sp
389 The \fBclear\fR command is used to disconnect all connected probe functions
390 from the specified probes.
391 .RE
392 .RS +4
393 .TP
394 4.
395 Commands to Toggle the Tracing Mode
396 .sp
397 .in +2
398 .nf
399 \fBtrace $\fIset_name\fR
400 trace \fIselector_list\fR
401 untrace $\fIset_name\fR
402 untrace \fIselector_list\fR\fR
403 .fi
404 .in -2
405 .sp
407 The \fBtrace\fR and \fBuntrace\fR commands are used to toggle the tracing
408 action of a probe point (that is, whether a probe will emit a trace record or
409 not if it is hit). This command does not enable the probes specified. Probes
410 have tracing on by default. The most efficient way to turn off tracing is by
411 using the \fBdisable\fR command. \fBuntrace\fR is useful if you want debug
412 output but no tracing. If so, set the state of the probe to enabled, untraced,
413 and the debug function connected.
414 .RE
415 .RS +4
416 .TP
417 5.
418 Commands to Enable and Disable Probes
419 .sp
420 .in +2
421 .nf
422 \fBenable $\fIset_name\fR
423 enable \fIselector_list\fR
424 disable $\fIset_name\fR
425 disable \fIselector_list\fR\fR
426 .fi
427 .in -2
428 .sp
430 The \fBenable\fR and \fBdisable\fR commands are used to control whether the
431 probes perform the action that they have been set up for. To trace a probe, it
432 has to be both enabled and traced (using the \fBtrace\fR command). Probes are
433 disabled by default. The \fBlist history\fR command is used to list the probe
434 control commands issued: \fBconnect\fR, \fBclear\fR, \fBtrace\fR,
435 \fBuntrace\fR, \fBenable\fR, and \fBdisable\fR. These are the commands that
436 are executed whenever a new shared object is brought in to the target program
437 by \fBdlopen\fR(3C). See the subsection, \fBdlopen'ed Libraries\fR, below for
438 more information.
439 .sp
440 The following table shows the actions that result from specific combinations of
441 tracing, enabling, and connecting:
442 .sp
443 .in +2
444 .nf
445 Enabled or Tracing State Debug State Results
446 Disabled (On/Off) (Connected/Cleared) In
447 ------------------------------------------------------------
448 Enabled On Connected Tracing and
449 Debugging
451 Enabled On Cleared Tracing only
453 Enabled Off Connected Debugging only
455 Enabled Off Cleared Nothing
457 Disabled On Connected Nothing
459 Disabled On Cleared Nothing
461 Disabled Off Connected Nothing
463 Disabled Off Cleared Nothing
464 .fi
465 .in -2
466 .sp
468 .RE
469 .RS +4
470 .TP
471 6.
472 List History
473 .sp
474 .in +2
475 .nf
476 \fBlist history # lists probe control command history\fR
477 .fi
478 .in -2
479 .sp
481 The \fBlist history\fR command displays a list of the probe control commands
482 previously issued in the tracing session, for example, \fBconnect\fR,
483 \fBclear\fR, \fBtrace\fR, \fBdisable\fR. Commands in the history list are
484 executed wherever a new shared object is brought into the target program by
485 \fBdlopen\fR(3C).
486 .RE
487 .RS +4
488 .TP
489 7.
490 Commands to List Probes, List Values, or List Trace File Name
491 .sp
492 .in +2
493 .nf
494 \fBlist \fIspec_list\fR probes $\fIset_name\fR # list probes $all
495 list \fIspec_list\fR probes \fIselector_list\fR # list name probes file=test.c
496 list values \fIspec_list\fR # list values keys given in \fIspec_list\fR
497 list tracefile # list tracefile\fR
498 .fi
499 .in -2
500 .sp
502 The first two commands list the selected attributes and values of the specified
503 probes. They can be used to check the state of a probe. The third command lists
504 the various values associated with the selected attributes. The fourth command
505 lists the current tracefile.
506 .RE
507 .RS +4
508 .TP
509 8.
510 Help Command
511 .sp
512 .in +2
513 .nf
514 \fBhelp \fItopic\fR\fR
515 .fi
516 .in -2
517 .sp
519 To get a list of the help topics that are available, invoke the \fBhelp\fR
520 command with no arguments. If a \fItopic\fR argument is specified, help is
521 printed for that topic.
522 .RE
523 .RS +4
524 .TP
525 9.
526 Source a File
527 .sp
528 .in +2
529 .nf
530 \fBsource \fIfilename\fR\fR
531 .fi
532 .in -2
533 .sp
535 The \fBsource\fR command can be used to source a file of \fBprex\fR commands.
536 \fBsource\fR can be nested (that is, a file can source another file).
537 \fIfilename\fR is a quoted string.
538 .RE
539 .RS +4
540 .TP
541 10.
542 Process Control
543 .sp
544 .in +2
545 .nf
546 \fBcontinue # resumes the target process
547 quit kill # quit prex, kill target
548 quit resume # quit prex, continue target
549 quit suspend # quit prex, leave target suspended
550 quit # quit prex (continue or kill target)\fR
551 .fi
552 .in -2
553 .sp
555 The default \fBquit\fR will continue the target process if \fBprex\fR attached
556 to it. Instead, if \fBprex\fR had started the target program, \fBquit\fR will
557 kill the target process.
558 .RE
559 .SS "dlopen'ed Libraries"
560 .sp
561 .LP
562 Probes in shared objects that are brought in by \fBdlopen\fR(3C) are
563 automatically set up according to the command history of \fBprex\fR. When a
564 shared object is removed by a \fBdlclose\fR(3C), \fBprex\fR again needs to
565 refresh its understanding of the probes in the target program. This implies
566 that there is more work to do for \fBdlopen\fR(3C) and \fBdlclose\fR(3C) \(emso
567 they will take slightly longer. If a user is not interested in this feature and
568 doesn't want to interfere with \fBdlopen\fR(3C) and \fBdlclose\fR(3C), detach
569 \fBprex\fR from the target to inhibit this feature.
570 .SS "Signals to Target Program"
571 .sp
572 .LP
573 \fBprex\fR does not interfere with signals that are delivered directly to the
574 target program. However, \fBprex\fR receives all signals normally generated
575 from the terminal, for example, Control-C (\fBSIGINT\fR), and Control-Z
576 (\fBSIGSTOP\fR), and does not forward them to the target program. To signal the
577 target program, use the \fBkill\fR(1) command from a shell.
578 .SS "Interactions with Other Applications"
579 .sp
580 .LP
581 Process managing applications like \fBdbx\fR, \fBtruss\fR(1), and \fBprex\fR
582 cannot operate on the same target program simultaneously. \fBprex\fR will not
583 be able to attach to a target which is being controlled by another application.
584 A user can trace and debug a program serially by the following method: first
585 attach \fBprex\fR to target (or start target through \fBprex\fR), set up the
586 probes using the command language, and then type \fBquit suspend\fR. The user
587 can then attach \fBdbx\fR to the suspended process and debug it. A user can
588 also suspend the target by sending it a \fBSIGSTOP\fR signal, and then by
589 typing \fBquit resume\fR to \fBprex\fR. In this case, the user should also send
590 a \fBSIGCONT\fR signal after invoking \fBdbx\fR on the stopped process (else
591 \fBdbx\fR will be hung).
592 .SS "Failure of Event Writing Operations"
593 .sp
594 .LP
595 There are a few failure points that are possible when writing out events to a
596 trace file, for example, system call failures. These failures result in a
597 failure code being set in the target process. The target process continues
598 normally, but no trace records are written. Whenever a user enters Control-C to
599 \fBprex\fR to get to a \fBprex\fR prompt, \fBprex\fR will check the failure
600 code in the target and inform the user if there was a tracing failure.
601 .SS "Target Executing a Fork or exec"
602 .sp
603 .LP
604 If the target program does a \fBfork\fR(2), any probes that the child
605 encounters will cause events to be logged to the same trace file. Events are
606 annotated with a process id, so it will be possible to determine which process
607 a particular event came from. In multi-threaded programs, there is a race
608 condition with a thread doing a fork while the other threads are still running.
609 For the trace file not to get corrupted, the user should either use
610 \fBfork1\fR(2), or make sure that all other threads are quiescent when doing a
611 \fBfork\fR(2),
612 .sp
613 .LP
614 If the target program itself (not any children it may \fBfork\fR(2)) does an
615 \fBexec\fR(2), \fBprex\fR detaches from the target and exits. The user can
616 reconnect \fBprex\fR with \fBprex\fR \fB-p\fR \fIpid\fR.
617 .sp
618 .LP
619 A \fBvfork\fR(2) is generally followed quickly by an \fBexec\fR(2) in the
620 child, and in the interim, the child borrows the parent's process while the
621 parent waits for the \fBexec\fR(2). Any events logged by the child from the
622 parent process will appear to have been logged by the parent.
623 .SS "Kernel Mode"
624 .sp
625 .LP
626 Invoking \fBprex\fR with the \fB-k\fR flag causes \fBprex\fR to run in
627 \fBkernel mode\fR. In kernel mode, \fBprex\fR controls probes in the Solaris
628 kernel. See \fBtnf_kernel_probes\fR(4) for a list of available probes in the
629 Solaris kernel. A few \fBprex\fR commands are unavailable in kernel mode; many
630 other commands are valid in kernel mode only.
631 .sp
632 .LP
633 The \fB-l\fR, \fB-o\fR, and \fB-p\fR command-line options are not valid in
634 kernel mode (that is, they may not be combined with the \fB-k\fR flag).
635 .sp
636 .LP
637 The rest of this section describes the differences in the \fBprex\fR command
638 language when running \fBprex\fR in kernel mode.
639 .RS +4
640 .TP
641 1.
642 \fBprex\fR will not stop the kernel
643 .sp
644 When \fBprex\fR attaches to a running user program, it stops the user program.
645 Obviously, it cannot do this when attaching to the kernel. Instead, \fBprex\fR
646 provides a ``tracing master switch'': no probes will have any effect unless the
647 tracing master switch is on. This allows the user to iteratively select probes
648 to enable, then enable them all at once by turning on the master switch.
649 .sp
650 The command
651 .sp
652 .in +2
653 .nf
654 \fBktrace [ on | off ]\fR
655 .fi
656 .in -2
657 .sp
659 is used to inspect and set the value of the master switch. Without an argument,
660 \fBprex\fR reports the current state of the master switch.
661 .sp
662 Since \fBprex\fR will not stop or kill the kernel, the
663 .sp
664 .in +2
665 .nf
666 \fBquit resume\fR
667 .fi
668 .in -2
669 .sp
671 and
672 .sp
673 .in +2
674 .nf
675 \fBquit kill\fR
676 .fi
677 .in -2
678 .sp
680 commands are not valid in kernel mode.
681 .RE
682 .RS +4
683 .TP
684 2.
685 No functions may be attached to probes in the kernel
686 .sp
687 In particular, the debug function is unavailable in kernel mode.
688 .RE
689 .RS +4
690 .TP
691 3.
692 Trace output is written to an in-core buffer
693 .sp
694 In kernel mode, a trace output file is not generated directly, in order to
695 allow probes to be placed in time-critical code. Instead, trace output is
696 written to an in-core buffer, and copied out by a separate program,
697 \fBtnfxtract\fR(1).
698 .sp
699 The in-core buffer is not automatically created. The following \fBprex\fR
700 command controls buffer allocation and deallocation:
701 .sp
702 .in +2
703 .nf
704 \fBbuffer [ alloc [ \fIsize\fR ] | dealloc ]\fR
705 .fi
706 .in -2
707 .sp
709 Without an argument, the \fBbuffer\fR command reports the size of the currently
710 allocated buffer, if any. With an argument of \fBalloc\fR [\fIsize\fR],
711 \fBprex\fR allocates a buffer of the given size. \fIsize\fR is in bytes, with
712 an optional suffix of '\fBk\fR' or '\fBm\fR' specifying a multiplier of
713 \fB1024\fR or \fB1048576\fR, respectively. If no \fIsize\fR is specified, the
714 \fIsize\fR specified on the command line with the \fB-s\fR option is used as a
715 default. If the \fB-s\fR command line option was not used, the ``default
716 default'' is 384 kilobytes.
717 .sp
718 With an argument of \fBdealloc\fR, \fBprex\fR deallocates the trace buffer in
719 the kernel.
720 .sp
721 \fBprex\fR will reject attempts to turn the tracing master switch on when no
722 buffer is allocated, and to deallocate the buffer when the tracing master
723 switch is on. \fBprex\fR will refuse to allocate a buffer when one is already
724 allocated; use \fBbuffer dealloc\fR first.
725 .sp
726 \fBprex\fR will not allocate a buffer larger than one-half of a machine's
727 physical memory.
728 .RE
729 .RS +4
730 .TP
731 4.
732 \fBprex\fR supports per-process probe enabling in the kernel
733 .sp
734 In kernel mode, it is possible to select a set of processes for which probes
735 are enabled. No trace output will be written when other processes traverse
736 these probe points. This is called "process filter mode". By default, process
737 filter mode is off, and all processes cause the generation of trace records
738 when they hit an enabled probe.
739 .sp
740 Some kernel events such as interrupts cannot be associated with a particular
741 user process. By convention, these events are considered to be generated by
742 process id 0.
743 .sp
744 \fBprex\fR provides commands to turn process filter mode on and off, to get the
745 current status of the process filter mode switch, to add and delete processes
746 (by process id) from the process filter set, and to list the current process
747 filter set.
748 .sp
749 The process filter set is maintained even when process filter mode is off, but
750 has no effect unless process filter mode is on.
751 .sp
752 When a process in the process filter set exits, its process id is automatically
753 deleted from the process filter set.
754 .sp
755 The command:
756 .sp
757 .in +2
758 .nf
759 \fBpfilter [ on | off | add \fIpidlist\fR | delete \fIpidlist\fR ]\fR
760 .fi
761 .in -2
762 .sp
764 controls the process filter switch, and process filter set membership. With no
765 arguments, \fBpfilter\fR prints the current process filter set and the state of
766 the process filter mode switch:
767 .sp
768 .ne 2
769 .na
770 \fB\fBon\fR or \fBoff\fR\fR
771 .ad
772 .RS 18n
773 set the state of the process filter mode switch.
774 .RE
776 .sp
777 .ne 2
778 .na
779 \fB\fBadd\fR \fIpidlist\fR\fR
780 .ad
781 .br
782 .na
783 \fB\fBdelete\fR \fIpidlist\fR\fR
784 .ad
785 .RS 18n
786 add or delete processes from the process filter set. \fIpidlist\fR is a
787 comma-separated list of one or more process ids.
788 .RE
790 .RE
791 .SH EXAMPLES
792 .sp
793 .LP
794 See \fBtracing\fR(3TNF) for complete examples showing, among other things, the
795 use of \fBprex\fR to do simple probe control.
796 .sp
797 .LP
798 When either the process or kernel is started, all probes are disabled.
799 .LP
800 \fBExample 1 \fRSet creation and set listing
801 .sp
802 .in +2
803 .nf
804 \fBcreate $out name=/out/ # $out = probes with "out" in
805 # value of "name" attribute
806 create $foo /page/ name=biodone # $foo = union of
807 # probes with "page" in value of keys attribute
808 # probes with "biodone" as value of "name" attribute
809 list sets # list the defined sets
810 list fcns # list the defined probe fcns\fR
811 .fi
812 .in -2
813 .sp
815 .LP
816 \fBExample 2 \fRCommands to trace and connect probe functions
817 .sp
818 .in +2
819 .nf
820 \fBtrace foobar='on' # exact match on foobar attribute
821 trace $all # trace all probes (predefined set $all)
822 connect &debug $foo # connect debug func to probes in $foo\fR
823 .fi
824 .in -2
825 .sp
827 .LP
828 \fBExample 3 \fRCommands to enable and disable probes
829 .sp
830 .in +2
831 .nf
832 \fBenable $all # enable all probes
833 enable /vm/ name=alloc # enable the specified probes
834 disable $foo # disable probes in set $foo
835 list history # list probe control commands issued\fR
836 .fi
837 .in -2
838 .sp
840 .LP
841 \fBExample 4 \fRProcess control
842 .sp
843 .in +2
844 .nf
845 \fBcontinue # resumes the target process
846 ^C # stop target; give control to prex
847 quit resume # exit prex, leave process running
848 # and resume execution of program\fR
849 .fi
850 .in -2
851 .sp
853 .LP
854 \fBExample 5 \fRKernel mode
855 .sp
856 .in +2
857 .nf
858 \fBbuffer alloc 2m # allocate a 2 Megabyte buffer
859 enable $all # enable all probes
860 trace $all # trace all probes
861 ktrace on # turn tracing on
862 ktrace off # turn tracing back off
863 pfilter on # turn process filter mode on
864 pfilter add 1379 # add pid 1379 to process filter
865 ktrace on # turn tracing on
866 # (only pid 1379 will be traced)\fR
867 .fi
868 .in -2
869 .sp
871 .SH FILES
872 .sp
873 .ne 2
874 .na
875 \fB\fB\&.prexrc\fR\fR
876 .ad
877 .RS 15n
878 local \fBprex\fR initialization file
879 .RE
881 .sp
882 .ne 2
883 .na
884 \fB\fB~/.prexrc\fR\fR
885 .ad
886 .RS 15n
887 user's \fBprex\fR initialization file
888 .RE
890 .sp
891 .ne 2
892 .na
893 \fB\fB/proc/\fInnnnn\fR\fR\fR
894 .ad
895 .RS 15n
896 process files
897 .RE
899 .SH SEE ALSO
900 .sp
901 .LP
902 \fBed\fR(1), \fBkill\fR(1), \fBksh\fR(1), \fBld\fR(1), \fBtnfdump\fR(1),
903 \fBtnfxtract\fR(1), \fBtruss\fR(1), \fBexec\fR(2), \fBfork\fR(2),
904 \fBfork1\fR(2), \fBvfork\fR(2), \fBTNF_DECLARE_RECORD\fR(3TNF),
905 \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), \fBdlopen\fR(3C),
906 \fBgethrtime\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtnf_process_disable\fR(3TNF),
907 \fBtracing\fR(3TNF), \fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)
908 .SH NOTES
909 .sp
910 .LP
911 Currently, the only probe function that is available is the \fB&debug\fR
912 function. When this function is executed, it prints out the arguments sent in
913 to the probe as well as the value associated with the \fBsunw%debug\fR
914 attribute in the detail field (if any) to \fBstderr\fR.
915 .sp
916 .LP
917 For example, for the following probe point:
918 .sp
919 .in +2
920 .nf
921 TNF_PROBE_2(input_values, "testapp main",
922 "sunw%debug 'have read input values successfully'",
923 tnf_long, int_input, x,
924 tnf_string, string_input, input);
925 .fi
926 .in -2
927 .sp
929 .sp
930 .LP
931 If \fIx\fR was 100 and \fIinput\fR was the string "success", then the output of
932 the debug probe function would be:
933 .sp
934 .in +2
935 .nf
936 probe input_values; sunw%debug "have read input values successfully";
937 int_input=100; string_input="success";
938 .fi
939 .in -2
940 .sp
942 .sp
943 .LP
944 Some non-SPARC hardware lacks a true high-resolution timer, causing
945 \fBgethrtime()\fR to return the same value multiple times in succession. This
946 can lead to problems in how some tools interpret the trace file. This situation
947 can be improved by interposing a version of \fBgethrtime()\fR, which causes
948 these successive values to be artificially incremented by one nanosecond:
949 .sp
950 .in +2
951 .nf
952 hrtime_t
953 gethrtime()
954 {
955 static mutex_t lock;
956 static hrtime_t (*real_gethrtime)(void) = NULL;
957 static hrtime_t last_time = 0;
959 hrtime_t this_time;
961 if (real_gethrtime == NULL) {
962 real_gethrtime =
963 (hrtime_t (*)(void)) dlsym(RTLD_NEXT, "gethrtime");
964 }
965 this_time = real_gethrtime();
967 mutex_lock(&lock);
968 if (this_time <= last_time)
969 this_time = ++last_time;
970 else
971 last_time = this_time;
972 mutex_unlock(&lock);
974 return (this_time);
975 }
976 .fi
977 .in -2
978 .sp
980 .sp
981 .LP
982 Of course, this does not increase the resolution of the timer, so timestamps
983 for individual events are still relatively inaccurate. But this technique
984 maintains ordering, so that if event A causes event B, B never appears to
985 happen before or at the same time as A.
986 .sp
987 .LP
988 \fBdbx\fR is available with the Sun Workshop Products.
989 .SH BUGS
990 .sp
991 .LP
992 \fBprex\fR should issue a notification when a process id has been automatically
993 deleted from the filter set.
994 .sp
995 .LP
996 There is a known bug in \fBprex\fR which can result in this message:
997 .sp
998 .in +2
999 .nf
1000 Tracing shut down in target program due to an internal
1001 error - Please restart prex and target
1002 .fi
1003 .in -2
1004 .sp
1006 .sp
1007 .LP
1008 When \fBprex\fR runs as root, and the target process is not root, and the
1009 tracefile is placed in a directory where it cannot be removed and re-created (a
1010 directory with the sticky bit on, like \fB/tmp\fR),mm then the target process
1011 will not be able to open the tracefile when it needs to. This results in
1012 tracing being disabled.
1013 .sp
1014 .LP
1015 Changing any of the circumstances listed above should fix the problem. Either
1016 don't run \fBprex\fR as root, or run the target process as root, or specify the
1017 tracefile in a directory other than \fB/tmp\fR.