xref: /freebsd/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 (revision a57ca37dd1848cd42844d9082c4a74c2ed57f68a)
1.\" CDDL HEADER START
2.\"
3.\" The contents of this file are subject to the terms of the
4.\" Common Development and Distribution License (the "License").
5.\" You may not use this file except in compliance with the License.
6.\"
7.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8.\" or http://www.opensolaris.org/os/licensing.
9.\" See the License for the specific language governing permissions
10.\" and limitations under the License.
11.\"
12.\" When distributing Covered Code, include this CDDL HEADER in each
13.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14.\" If applicable, add the following below this CDDL HEADER, with the
15.\" fields enclosed by brackets "[]" replaced with your own identifying
16.\" information: Portions Copyright [yyyy] [name of copyright owner]
17.\"
18.\" CDDL HEADER END
19.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
20.\"
21.\" $FreeBSD$
22.\"
23.Dd February 24, 2023
24.Dt DTRACE 1
25.Os
26.Sh NAME
27.Nm dtrace
28.Nd dynamic tracing compiler and tracing utility
29.Sh SYNOPSIS
30.Nm
31.Op Fl 32 | Fl 64
32.Op Fl aACdeFGhHlqSvVwZ
33.Op Fl b Ar bufsz
34.Op Fl c Ar cmd
35.Op Fl D Ar name Op Ns = Ns value
36.Op Fl I Ar path
37.Op Fl L Ar path
38.Op Fl o Ar output
39.Op Fl s Ar script
40.Op Fl U Ar name
41.Op Fl x Ar arg Op Ns = Ns value
42.Op Fl X Cm a | c | s | t
43.Op Fl p Ar pid
44.Op Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
45.Op Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
46.Op Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
47    Oc Ar action Oc
48.Op Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
49    Oo Oo Ar predicate Oc Ar action Oc
50.Op Fl i Ar probe-id Oo Oo Ar predicate Oc Ar action Oc
51.Sh DESCRIPTION
52DTrace is a comprehensive dynamic tracing framework ported from Solaris.
53DTrace provides a powerful infrastructure that permits administrators,
54developers, and service personnel to concisely answer arbitrary questions about
55the behavior of the operating system and user programs.
56.Pp
57The
58.Nm
59command provides a generic interface to the essential services provided by the
60DTrace facility, including:
61.Bl -bullet -offset indent
62.It
63Options that list the set of probes and providers currently published by DTrace
64.It
65Options that enable probes directly using any of the probe description
66specifiers (provider, module, function, name)
67.It
68Options that run the D compiler and compile one or more D program files or
69programs written directly on the command line
70.It
71Options that generate anonymous tracing programs
72.It
73Options that generate program stability reports
74.It
75Options that modify DTrace tracing and buffering behavior and enable
76additional D compiler features
77.El
78.Pp
79You can use
80.Nm
81to create D scripts by using it in a shebang declaration to create an
82interpreter file.
83You can also use
84.Nm
85to attempt to compile D programs and determine their properties without
86actually enabling traces using the
87.Fl e
88option.
89.Sh OPTIONS
90The arguments accepted by the
91.Fl P ,
92.Fl m ,
93.Fl f ,
94.Fl n ,
95and
96.Fl i
97options can include an optional D language
98.Ar predicate
99enclosed in slashes and an optional D language
100.Ar action
101statement list enclosed in braces.
102D program code specified on the command line must be appropriately quoted to
103avoid interpretation of meta-characters by the shell.
104.Pp
105The following options are supported:
106.Bl -tag -width indent
107.It Fl 32 | Fl 64
108The D compiler produces programs using the native data model of the operating
109system kernel.
110If the
111.Fl 32
112option is specified,
113.Nm
114forces the D compiler to compile a D program using the 32-bit data model.
115If the
116.Fl 64
117option is specified,
118.Nm
119forces the D compiler to compile a D program using the 64-bit data model.
120These options are typically not required as
121.Nm
122selects the native data model as the default.
123The data model affects the sizes of integer types and other language properties.
124D programs compiled for either data model can be executed on both 32-bit and
12564-bit kernels.
126The
127.Fl 32
128and
129.Fl 64
130options also determine the
131.Xr elf 5
132file format (ELF32 or ELF64) produced by the
133.Fl G
134option.
135.It Fl a
136Claim anonymous tracing state and display the traced data.
137You can combine the
138.Fl a
139option with the
140.Fl e
141option to force
142.Nm
143to exit immediately after consuming the anonymous tracing state rather than
144continuing to wait for new data.
145.It Fl A
146Generate directives for anonymous tracing and write them to
147.Pa /boot/dtrace.dof .
148This option constructs a set of dtrace configuration file directives to enable
149the specified probes for anonymous tracing and then exits.
150By default,
151.Nm
152attempts to store the directives to the file
153.Pa /boot/dtrace.dof .
154This behavior can be modified using the
155.Fl o
156option to specify an alternate output file.
157.It Fl b Ar bufsz
158Set the principal trace buffer size to
159.Ar bufsz .
160The trace buffer size can include any of the size suffixes k, m, g, or t.
161If the buffer space cannot be allocated,
162.Nm dtrace
163attempts to reduce the buffer size or exit depending on the setting of the
164bufresize property.
165.It Fl c Ar cmd
166Run the specified command
167.Ar cmd
168and exit upon its completion.
169If more than one
170.Fl c
171option is present on the command line,
172.Nm dtrace
173exits when all commands have exited, reporting the exit status for each child
174process as it terminates.
175The process ID of the first command is made available to any D programs
176specified on the command line or using the
177.Fl s
178option through the
179.Li $target
180macro variable.
181.It Fl C
182Run the C preprocessor
183.Xr cpp 1
184over D programs before compiling them.
185You can pass options to the C preprocessor using the
186.Fl D ,
187.Fl U ,
188.Fl I ,
189and
190.Fl H
191options.
192You can select the degree of C standard conformance if you use the
193.Fl X
194option.
195For a description of the set of tokens defined by the D compiler when invoking
196the C preprocessor, see
197.Fl X .
198.It Fl d
199Dump the D script to standard output, after syntactic transformations have been
200applied.
201For example, if-statements in D are implemented using such transformations: a
202conditional clause in a probe body is replaced at compile-time by a separate
203probe predicated on the original condition.
204.It Fl D Ar name Op Ns = Ns value
205Define
206.Ar name
207when invoking
208.Xr cpp 1
209(enabled using the
210.Fl C
211option).
212If you specify an additional
213.Ar value ,
214the name is assigned the corresponding value.
215This option passes the
216.Fl D
217option to each
218.Xr cpp 1
219invocation.
220.It Fl e
221Exit after compiling any requests and consuming anonymous tracing state
222.Fl ( a
223option) but prior to enabling any probes.
224You can combine this option with the
225.Fl a
226option to print anonymous tracing data and exit.
227You can also combine this option with D compiler options.
228This combination verifies that the programs compile without actually executing
229them and enabling the corresponding instrumentation.
230.It Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \
231    Oc Ar action Oc
232Specify function name to trace or list
233.Fl ( l
234option).
235The corresponding argument can include any of the probe description forms
236.Ar provider:module:function ,
237.Ar module:function ,
238or
239.Ar function .
240Unspecified probe description fields are left blank and match any probes
241regardless of the values in those fields.
242If no qualifiers other than
243.Ar function
244are specified in the description, all probes with the corresponding
245.Ar function
246are matched.
247The
248.Fl f
249argument can be suffixed with an optional D probe clause.
250You can specify more than one
251.Fl f
252option on the command line at a time.
253.It Fl F
254Coalesce trace output by identifying function entry and return.
255Function entry probe reports are indented and their output is prefixed with
256.Ql -> .
257Function return probe reports are unindented and their output is prefixed with
258.Ql <- .
259System call entry probe reports are indented and their output is prefixed with
260.Ql => .
261System call return probe reports are unindented and their output is prefixed
262with
263.Ql <= .
264.It Fl G
265Generate an ELF file containing an embedded DTrace program.
266The DTrace probes specified in the program are saved inside of a relocatable ELF
267object which can be linked into another program.
268If the
269.Fl o
270option is present, the ELF file is saved using the pathname specified as the
271argument for this operand.
272If the
273.Fl o
274option is not present and the DTrace program is contained with a file whose name
275is
276.Ar filename.d ,
277then the ELF file is saved using the name
278.Ar filename.o .
279Otherwise the ELF file is saved using the name d.out.
280.It Fl h
281Generate a header file containing macros that correspond to probes in the
282specified provider definitions.
283This option should be used to generate a header file that is included by other
284source files for later use with the
285.Fl G
286option.
287If the
288.Fl o
289option is present, the header file is saved using the pathname specified as the
290argument for that option.
291If the
292.Fl o
293option is not present and the DTrace program is contained within a file whose
294name is
295.Ar filename.d ,
296then the header file is saved using the name
297.Ar filename.h .
298.It Fl H
299Print the pathnames of included files when invoking
300.Xr cpp 1
301(enabled using the
302.Fl C
303option).
304This option passes the
305.Fl H
306option to each
307.Xr cpp 1
308invocation, causing it to display the list of pathnames, one for each line, to
309standard error.
310.It Fl i Ar probe-id Op Oo Ar predicate Oc Ar action
311Specify probe identifier
312.Ar ( probe-id )
313to trace or list
314.Ar ( l
315option).
316You can specify probe IDs using decimal integers as shown by `dtrace -l`.
317The
318.Fl i
319argument can be suffixed with an optional D probe clause.
320You can specify more than one
321.Fl i
322option at a time.
323.It Fl I Ar path
324Add the specified directory
325.Ar path
326to the search path for #include files when invoking
327.Xr cpp 1
328(enabled using the
329.Fl C
330option).
331This option passes the
332.Fl I
333option to each
334.Xr cpp 1
335invocation.
336The specified
337.Ar path
338is inserted into the search path ahead of the default directory list.
339.It Fl l
340List probes instead of enabling them.
341If the
342.Fl l
343option is specified,
344.Nm
345produces a report of the probes matching the descriptions given using the
346.Fl P , m , f , n , i ,
347and
348.Fl s
349options.
350If none of these options are specified, this option lists all probes.
351.It Fl L Ar path
352Add the specified directory
353.Ar path
354to the search path for DTrace libraries.
355DTrace libraries are used to contain common definitions that can be used when
356writing D programs.
357The specified
358.Ar path
359is added after the default library search path.
360.It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc
361Specify module name to trace or list
362.Fl ( l
363option).
364The corresponding argument can include any of the probe description forms
365.Ar provider:module
366or
367.Ar module .
368Unspecified probe description fields are left blank and match any probes
369regardless of the values in those fields.
370If no qualifiers other than
371.Ar module
372are specified in the description, all probes with a corresponding
373.Ar module
374are matched.
375The
376.Fl m
377argument can be suffixed with an optional D probe clause.
378More than one
379.Fl m
380option can be specified on the command line at a time.
381.It Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \
382    Oo Oo Ar predicate Oc Ar action Oc
383Specify probe name to trace or list
384.Fl ( l
385option).
386The corresponding argument can include any of the probe description forms
387.Ar provider:module:function:name , module:function:name , function:name ,
388or
389.Ar name .
390Unspecified probe description fields are left blank and match any probes
391regardless of the values in those fields.
392If no qualifiers other than
393.Ar name
394are specified in the description, all probes with a corresponding
395.Ar name
396are matched.
397The
398.Fl n
399argument can be suffixed with an optional D probe clause.
400More than one
401.Fl n
402option can be specified on the command line at a time.
403.It Fl o Ar output
404Specify the
405.Ar output
406file for the
407.Fl A , G ,
408and
409.Fl l
410options, or for the traced data itself.
411If the
412.Fl A
413option is present and
414.Fl o
415is not present, the default output file is
416.Pa /boot/dtrace.dof .
417If the
418.Fl G
419option is present and the
420.Fl s
421option's argument is of the form
422.Ar filename.d
423and
424.Fl o
425is not present, the default output file is
426.Ar filename.o .
427Otherwise the default output file is
428.Ar d.out .
429.It Fl p Ar pid
430Grab the specified process-ID
431.Ar pid ,
432cache its symbol tables, and exit upon its completion.
433If more than one
434.Fl p
435option is present on the command line,
436.Nm
437exits when all commands have exited, reporting the exit status for each process
438as it terminates.
439The first process-ID is made available to any D programs specified on the
440command line or using the
441.Fl s
442option through the
443.Li $target
444macro variable.
445.It Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc
446Specify provider name to trace or list
447.Fl ( l
448option).
449The remaining probe description fields module, function, and name are left
450blank and match any probes regardless of the values in those fields.
451The
452.Fl P
453argument can be suffixed with an optional D probe clause.
454You can specify more than one
455.Fl P
456option on the command line at a time.
457.It Fl q
458Set quiet mode.
459.Nm
460suppresses messages such as the number of probes matched by the specified
461options and D programs and does not print column headers, the CPU ID, the probe
462ID, or insert newlines into the output.
463Only data traced and formatted by D program statements such as
464.Ql dtrace()
465and
466.Ql printf()
467is displayed to standard output.
468.It Fl s Ar script
469Compile the specified D program source file.
470If the
471.Fl e
472option is present, the program is compiled but instrumentation is not enabled.
473If the
474.Fl l
475option is present, the program is compiled and the set of probes matched by it
476is listed, but instrumentation is not enabled.
477If none of
478.Fl e , l , G ,
479or
480.Fl A
481are present, the instrumentation specified by the D program is enabled and
482tracing begins.
483.It Fl S
484Show D compiler intermediate code.
485The D compiler produces a report of the intermediate code generated for each D
486program to standard error.
487.It Fl U Ar name
488Undefine the specified
489.Ar name
490when invoking
491.Xr cpp 1
492(enabled using the
493.Fl C
494option).
495This option passes the
496.Fl U
497option to each
498.Xr cpp 1
499invocation.
500.It Fl v
501Set verbose mode.
502If the
503.Fl v
504option is specified,
505.Nm
506produces a program stability report showing the minimum interface stability and
507dependency level for the specified D programs.
508.It Fl V
509Report the highest D programming interface version supported by
510.Nm .
511The version information is printed to standard output and the
512.Nm
513command exits.
514.It Fl w
515Permit destructive actions in D programs specified using the
516.Fl s , P , m , f , n ,
517or
518.Fl i
519options.
520If the
521.Fl w
522option is not specified,
523.Nm
524does not permit the compilation or enabling of a D program that contains
525destructive actions.
526.It Fl x Ar arg Op Ns = Ns value
527Enable or modify a DTrace runtime option or D compiler option.
528Boolean options are enabled by specifying their name.
529Options with values are set by separating the option name and value with an
530equals sign (=).
531.Pp
532A
533.Ar size
534argument may be suffixed with one of
535.Cm K ,
536.Cm M ,
537.Cm G
538or
539.Cm T
540(either upper or lower case) to indicate a multiple of
541Kilobytes, Megabytes, Gigabytes or Terabytes
542respectively.
543.Pp
544A
545.Ar time
546argument may be suffixed with one of
547.Cm ns ,
548.Cm nsec ,
549.Cm us ,
550.Cm usec ,
551.Cm ms ,
552.Cm msec ,
553.Cm s  ,
554.Cm sec ,
555.Cm m ,
556.Cm min ,
557.Cm h ,
558.Cm hour ,
559.Cm d  ,
560.Cm day ,
561.Cm hz .
562If no suffix is specified
563.Cm hz
564will be used as the unit.
565.Bl -tag -width indent
566.It Sy aggrate Ns = Ns Ar time
567Rate of aggregation reading.
568.It Sy aggsize Ns = Ns Ar size
569Size of the aggregation buffer.
570.It Sy bufpolicy Ns = Ns Cm fill Ns | Ns Cm switch Ns | Ns Cm ring
571Specifies the buffer policy for the principal buffer.
572.It Sy bufresize Ns = Ns Cm auto Ns | Ns Cm manual
573Buffer resizing policy.
574.It Sy bufsize Ns = Ns Ar size
575Size of the per-CPU principal buffer.
576Same as the
577.Fl b
578flag.
579.It Sy cleanrate Ns = Ns Ar time
580Cleaning rate.
581Must be specified in number-per-second with the
582.Dq Li hz
583suffix.
584.It Sy cpu Ns = Ns Ar scalar
585Specifies the CPU on which to enable tracing.
586.It Sy cpp
587Run a C preprocessor over input files.
588Same as the
589.Fl C
590flag.
591.It Sy cpppath Ns = Ns Ar path
592Use the specified path for the C preprocessor rather than
593searching for
594.Dq cpp
595in
596.Ev PATH .
597.It Sy defaultargs
598Allow references to unspecified macro arguments.
599.It Sy destructive
600Allow destructive actions.
601Same as the
602.Fl w
603flag.
604.It Sy dynvarsize Ns = Ns Ar size
605Size of the dynamic variable space.
606.It Sy flowindent
607Turn on flow indentation.
608Same as the
609.Fl F
610flag.
611.It Sy grabanon
612Claim anonymous state.
613Same as the
614.Fl a
615flag.
616.It Sy jstackframes Ns = Ns Ar scalar
617Number of default stack frames for
618.Fn jstack .
619.It Sy jstackstrsize Ns = Ns Ar scalar
620Default string space size for
621.Fn jstack .
622.It Sy ldpath Ns = Ns Ar path
623When
624.Fl G
625is specified, use the specified path for a static linker
626rather than searching for
627.Dq "ld"
628in
629.Ev PATH .
630.It Sy libdir Ns = Ns Ar path
631Add a directory to the system library path.
632.It Sy nspec Ns = Ns Ar scalar
633Number of speculations.
634.It Sy nolibs
635Do not load D system libraries.
636.It Sy quiet
637Set quiet mode.
638Same as the
639.Fl q
640flag.
641.It Sy specsize Ns = Ns Ar size
642Size of the speculation buffer.
643.It Sy strsize Ns = Ns Ar size
644Maximum size of strings.
645.It Sy stackframes Ns = Ns Ar scalar
646Maximum number of kernelspace stack frames to unwind when executing the
647.Fn stack
648action.
649.It Sy stackindent Ns = Ns Ar scalar
650Number of whitespace characters to use when indenting
651.Fn stack
652and
653.Fn ustack
654output.
655.It Sy statusrate Ns = Ns Ar time
656Rate of status checking.
657.It Sy switchrate Ns = Ns Ar time
658Rate of buffer switching.
659.It Sy syslibdir Ns = Ns Ar path
660Path to system libraries.
661Defaults to
662.Pa /usr/lib/dtrace .
663.It Sy ustackframes Ns = Ns Ar scalar
664Maximum number of userspace stack frames to unwind when executing the
665.Fn ustack
666action.
667.El
668.It Fl X Cm a | c | s | t
669Specify the degree of conformance to the ISO C standard that should be selected
670when invoking
671.Xr cpp 1
672(enabled using the
673.Fl C
674option).
675The
676.Fl X
677option argument affects the value and presence of the __STDC__ macro depending
678upon the value of the argument letter.
679.sp
680The
681.Fl X
682option supports the following arguments:
683.Bl -tag -width indent
684.It a
685Default.
686ISO C plus K&R compatibility extensions, with semantic changes required by ISO
687C.
688This is the default mode if
689.Fl X
690is not specified.
691The predefined macro __STDC__ has a value of 0 when
692.Xr cpp 1
693is invoked in conjunction with the
694.Fl Xa
695option.
696.It c
697Conformance.
698Strictly conformant ISO C, without K&R C compatibility extensions.
699The predefined macro __STDC__ has a value of 1 when
700.Xr cpp 1
701is invoked in conjunction with the
702.Fl \&Xc
703option.
704.It s
705K&R C only.
706The macro __STDC__ is not defined when
707.Xr cpp 1
708is invoked in conjunction with the
709.Fl Xs
710option.
711.It t
712Transition.
713ISO C plus K&R C compatibility extensions, without semantic changes required by
714ISO C.
715The predefined macro __STDC__ has a value of 0 when
716.Xr cpp 1
717is invoked in conjunction with the
718.Fl Xt
719option.
720.El
721.Pp
722As the
723.Fl X
724option only affects how the D compiler invokes the C preprocessor, the
725.Fl Xa
726and
727.Fl Xt
728options are equivalent from the perspective of D and both are provided only to
729ease re-use of settings from a C build environment.
730.Pp
731Regardless of the
732.Fl X
733mode, the following additional C preprocessor definitions are always specified
734and valid in all modes:
735.Bl -bullet -offset indent
736.It
737__sun
738.It
739__unix
740.It
741__SVR4
742.It
743__sparc (on SPARC systems only)
744.It
745__sparcv9 (on SPARC systems only when 64-bit programs are compiled)
746.It
747__i386 (on x86 systems only when 32-bit programs are compiled)
748.It
749__amd64 (on x86 systems only when 64-bit programs are compiled)
750.It
751__`uname -s`_`uname -r` (for example,
752.Ql FreeBSD_9.2-RELEASE .
753.It
754__SUNW_D=1
755.It
756.No __SUNW_D_VERSION=0x Ns Ar MMmmmuuu
757.Pp
758Where
759.Ar MM
760is the major release value in hexadecimal,
761.Ar mmm
762is the minor release value in hexadecimal, and
763.Ar uuu
764is the micro release value in hexadecimal.
765.El
766.It Fl Z
767Permit probe descriptions that match zero probes.
768If the
769.Fl Z
770option is not specified,
771.Nm
772reports an error and exits if any probe descriptions specified in D program
773files
774.Fl ( s
775option) or on the command line
776.Fl ( P , m , f , n ,
777or
778.Fl i
779options) contain descriptions that do not match any known probes.
780.El
781.Sh OPERANDS
782You can specify zero or more additional arguments on the
783.Nm
784command line to define a set of macro variables and so forth).
785The additional arguments can be used in D programs specified using the
786.Fl s
787option or on the command line.
788.Sh FILES
789.Bl -tag -width /boot/dtrace.dof -compact
790.It Pa /boot/dtrace.dof
791File for anonymous tracing directives.
792.El
793.Sh EXIT STATUS
794The following exit statuses are returned:
795.Bl -tag -width indent
796.It 0
797Successful completion.
798.Pp
799For D program requests, an exit status of 0 indicates that programs were
800successfully compiled, probes were successfully enabled, or anonymous state
801was successfully retrieved.
802.Nm
803returns 0 even if the specified tracing requests encountered errors or drops.
804.It 1
805An error occurred.
806.Pp
807For D program requests, an exit status of 1 indicates that program compilation
808failed or that the specified request could not be satisfied.
809.It 2
810Invalid command line options or arguments were specified.
811.El
812.Sh SEE ALSO
813.Xr cpp 1 ,
814.Xr elf 5 ,
815.Xr SDT 9
816.Rs
817.%T Solaris Dynamic Tracing Guide
818.Re
819.Sh HISTORY
820The
821.Nm
822utility first appeared in
823.Fx 7.1 .
824