| DTRACE(1) | MidnightBSD General Commands Manual | DTRACE(1) |
dtrace — dynamic
tracing compiler and tracing utility
dtrace |
[-32 | -64]
[-aACeFGhHlqSvVwZ] [-b
bufsz] [-c
cmd] [-D
name [=value]] [-I
path] [-L
path] [-o
output] [-s
script] [-U
name] [-x
arg [=value]] [-X
a | c |
s | t]
[-p pid]
[-P provider
[[predicate] action]]
[-m [provider:]
module [[predicate]
action]] [-f
[[provider:] module:]
function [[predicate]
action]] [-n
[[[provider:] module:]
function:] name
[[predicate] action]]
[-i probe-id
[[predicate] action]] |
DTrace is a comprehensive dynamic tracing framework ported from Solaris. DTrace provides a powerful infrastructure that permits administrators, developers, and service personnel to concisely answer arbitrary questions about the behavior of the operating system and user programs.
The dtrace command provides a generic
interface to the essential services provided by the DTrace facility,
including:
You can use dtrace to create D scripts by
using it in a shebang declaration to create an interpreter file. You can
also use dtrace to attempt to compile D programs and
determine their properties without actually enabling traces using the
-e option.
The arguments accepted by the -P,
-m, -f,
-n, and -i options can
include an optional D language predicate enclosed in
slashes and an optional D language action statement
list enclosed in braces. D program code specified on the command line must
be appropriately quoted to avoid interpretation of meta-characters by the
shell.
The following options are supported:
-32 |
-64-32 option is
specified, dtrace forces the D compiler to compile
a D program using the 32-bit data model. If the
-64 option is specified,
dtrace forces the D compiler to compile a D
program using the 64-bit data model. These options are typically not
required as dtrace selects the native data model
as the default. The data model affects the sizes of integer types and
other language properties. D programs compiled for either data model can
be executed on both 32-bit and 64-bit kernels. The
-32 and -64 options also
determine the elf(5) file
format (ELF32 or ELF64) produced by the -G
option.-a-a option with the -e
option to force dtrace to exit immediately after
consuming the anonymous tracing state rather than continuing to wait for
new data.-Adtrace attempts to store the directives to the
file /boot/dtrace.dof. This behavior can be
modified using the -o option to specify an
alternate output file.-b
bufszdtrace
attempts to reduce the buffer size or exit depending on the setting of the
bufresize property.-c
cmd-c option is present
on the command line, dtrace exits when all
commands have exited, reporting the exit status for each child process as
it terminates. The process ID of the first command is made available to
any D programs specified on the command line or using the
-s option through the
$target macro variable.-C-D, -U,
-I, and -H options. You
can select the degree of C standard conformance if you use the
-X option. For a description of the set of tokens
defined by the D compiler when invoking the C preprocessor, see
-X.-D
name [=value]-C option). If you specify an additional
value, the name is assigned the corresponding value.
This option passes the -D option to each
cpp(1) invocation.-e-a option) but prior to enabling any probes. You
can combine this option with the -a option to
print anonymous tracing data and exit. You can also combine this option
with D compiler options. This combination verifies that the programs
compile without actually executing them and enabling the corresponding
instrumentation.-f
[[provider:] module:]
function [[predicate]
action]-l
option). The corresponding argument can include any of the probe
description forms provider:module:function,
module:function, or function.
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields. If no qualifiers other than
function are specified in the description, all
probes with the corresponding function are matched.
The -f argument can be suffixed with an optional D
probe clause. You can specify more than one -f
option on the command line at a time.-F->’. Function return probe
reports are unindented and their output is prefixed with
‘<-’. System call entry probe
reports are indented and their output is prefixed with
‘=>’. System call return probe
reports are unindented and their output is prefixed with
‘<=’.-G-o option is present, the ELF file is saved using
the pathname specified as the argument for this operand. If the
-o option is not present and the DTrace program is
contained with a file whose name is filename.d, then
the ELF file is saved using the name filename.o.
Otherwise the ELF file is saved using the name d.out.-h-G option. If the -o
option is present, the header file is saved using the pathname specified
as the argument for that option. If the -o option
is not present and the DTrace program is contained within a file whose
name is filename.d, then the header file is saved
using the name filename.h.-H-C option). This option passes the
-H option to each
cpp(1) invocation, causing
it to display the list of pathnames, one for each line, to standard
error.-i
probe-id [[predicate]
action]-i argument
can be suffixed with an optional D probe clause. You can specify more than
one -i option at a time.-I
path-C option). This option passes the
-I option to each
cpp(1) invocation. The
specified path is inserted into the search path
ahead of the default directory list.-l-l
option is specified, dtrace produces a report of
the probes matching the descriptions given using the
-P, -m,
-f, -n,
-i, and -s options. If
none of these options are specified, this option lists all probes.-L
path-m
[provider:] module
[[predicate] action]-l option).
The corresponding argument can include any of the probe description forms
provider:module or module.
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields. If no qualifiers other than
module are specified in the description, all probes
with a corresponding module are matched. The
-m argument can be suffixed with an optional D
probe clause. More than one -m option can be
specified on the command line at a time.-n
[[[provider:] module:]
function:] name
[[predicate] action]-l option).
The corresponding argument can include any of the probe description forms
provider:module:function:name,
module:function:name,
function:name, or name.
Unspecified probe description fields are left blank and match any probes
regardless of the values in those fields. If no qualifiers other than
name are specified in the description, all probes
with a corresponding name are matched. The
-n argument can be suffixed with an optional D
probe clause. More than one -n option can be
specified on the command line at a time.-o
output-A, -G, and
-l options, or for the traced data itself. If the
-A option is present and
-o is not present, the default output file is
/boot/dtrace.dof. If the
-G option is present and the
-s option's argument is of the form
filename.d and -o is not
present, the default output file is filename.o.
Otherwise the default output file is d.out.-p
pid-p option is present on the command line,
dtrace exits when all commands have exited,
reporting the exit status for each process as it terminates. The first
process-ID is made available to any D programs specified on the command
line or using the -s option through the
$target macro variable.-P
provider [[predicate]
action]-l
option). The remaining probe description fields module, function, and name
are left blank and match any probes regardless of the values in those
fields. The -P argument can be suffixed with an
optional D probe clause. You can specify more than one
-P option on the command line at a time.-qdtrace suppresses messages such as
the number of probes matched by the specified options and D programs and
does not print column headers, the CPU ID, the probe ID, or insert
newlines into the output. Only data traced and formatted by D program
statements such as ‘dtrace()’ and
‘printf()’ is displayed to standard
output.-s
script-e option is present, the program is compiled but
instrumentation is not enabled. If the -l option
is present, the program is compiled and the set of probes matched by it is
listed, but instrumentation is not enabled. If none of
-e, -l,
-G, or -A are present, the
instrumentation specified by the D program is enabled and tracing
begins.-S-U
name-C option). This option passes the
-U option to each
cpp(1) invocation.-v-v option is specified,
dtrace produces a program stability report showing
the minimum interface stability and dependency level for the specified D
programs.-Vdtrace. The version information is printed to
standard output and the dtrace command exits.-w-s, -P,
-m, -f,
-n, or -i options. If the
-w option is not specified,
dtrace does not permit the compilation or enabling
of a D program that contains destructive actions.-x
arg [=value]A size argument may be suffixed with one
of K, M,
G or T (either upper or
lower case) to indicate a multiple of Kilobytes, Megabytes, Gigabytes or
Terabytes respectively.
A time argument may be suffixed with one
of ns, nsec,
us, usec,
ms, msec,
s, sec,
m, min,
h, hour,
d, day,
hz. If no suffix is specified
hz will be used as the unit.
fill|switch|ringauto|manual-b flag.hz” suffix.-w
flag.-F
flag.-a
flag.jstack().jstack().-q flag.stack()
action.stack() and
ustack()
output.ustack() action.-X
a |
c |
s |
t-C option). The -X option
argument affects the value and presence of the __STDC__ macro depending
upon the value of the argument letter.
The -X option supports the following
arguments:
-X is not specified. The predefined macro
__STDC__ has a value of 0 when
cpp(1) is invoked in
conjunction with the -Xa option.-Xc
option.-Xs option.-Xt option.As the -X option only affects how the
D compiler invokes the C preprocessor, the -Xa
and -Xt options are equivalent from the
perspective of D and both are provided only to ease re-use of settings
from a C build environment.
Regardless of the -X mode, the
following additional C preprocessor definitions are always specified and
valid in all modes:
FreeBSD_9.2-RELEASE’.Where MM is the major release value in hexadecimal, mmm is the minor release value in hexadecimal, and uuu is the micro release value in hexadecimal.
-Z-Z option is not specified,
dtrace reports an error and exits if any probe
descriptions specified in D program files (-s
option) or on the command line (-P,
-m, -f,
-n, or -i options) contain
descriptions that do not match any known probes.You can specify zero or more additional arguments on the
dtrace command line to define a set of macro
variables and so forth). The additional arguments can be used in D programs
specified using the -s option or on the command
line.
The following exit statuses are returned:
For D program requests, an exit status of 0 indicates that
programs were successfully compiled, probes were successfully enabled,
or anonymous state was successfully retrieved.
dtrace returns 0 even if the specified tracing
requests encountered errors or drops.
For D program requests, an exit status of 1 indicates that program compilation failed or that the specified request could not be satisfied.
The dtrace utility first appeared in
FreeBSD 7.1.
Solaris Dynamic Tracing Guide.
| February 25, 2020 | midnightbsd-3.1 |