Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dtrace(1M)		System Administration Commands		    dtrace(1M)

NAME
       dtrace -	DTrace dynamic tracing compiler	and tracing utility

SYNOPSIS
       dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz]	[-c cmd]
	   [-D name [=value]] [-I path]	[-L path] [-o output]
	   [-s script] [-U name] [-x arg [=val]]
	   [-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]]

DESCRIPTION
       DTrace  is  a  comprehensive  dynamic tracing framework for the Solaris
       Operating System. DTrace	provides a powerful infrastructure  that  per-
       mits  administrators,  developers,  and	service	personnel to concisely
       answer arbitrary	questions about	the behavior of	the  operating	system
       and user	programs.

       The  Solaris  Dynamic  Tracing  Guide  describes	 how  to use DTrace to
       observe,	debug, and tune	system behavior. Refer	to  this  book	for  a
       detailed	 description  of DTrace	features, including the	bundled	DTrace
       observability tools, instrumentation providers, and the	D  programming
       language.

       The  dtrace  command provides a generic interface to the	essential ser-
       vices provided by the DTrace facility, including:

	   o	  Options that list the	set of probes and providers  currently
		  published by DTrace

	   o	  Options  that	 enable	probes directly	using any of the probe
		  description specifiers (provider, module, function, name)

	   o	  Options that run the D compiler and compile one  or  more  D
		  program  files  or  programs written directly	on the command
		  line

	   o	  Options that generate	anonymous tracing programs

	   o	  Options that generate	program	stability reports

	   o	  Options that modify DTrace tracing  and  buffering  behavior
		  and enable additional	D compiler features

       You  can	use dtrace to create D scripts by using	it in a	#! declaration
       to create an interpreter	file. You can also use dtrace  to  attempt  to
       compile	D  programs  and  determine  their properties without actually
       enabling	tracing	using the -e option.  See  OPTIONS.  See  the  Solaris
       Dynamic	Tracing	 Guide	for detailed examples of how to	use the	dtrace
       utility to perform these	tasks.

OPTIONS
       The arguments accepted by the -P,  -m,  -f,  -n,	 and  -i  options  can
       include	an  optional  D	 language predicate enclosed in	slashes	// and
       optional	D language action statement list enclosed in braces {}.	D pro-
       gram code specified on the command line must be appropriately quoted to
       avoid intepretation of meta-characters by the shell.

       The following options are supported:

       -32 | -64

	   The D compiler produces programs using the native data model	of the
	   operating  system  kernel.  You  can	 use the isainfo -b command to
	   determine the current operating system  data	 model.	  If  the  -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	speci-
	   fied, 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 file	format (ELF32 or ELF64)	produced by the	-G option.

       -a

	   Claim  anonymous tracing state and display the traced data. You can
	   combine the -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. See	the  Solaris  Dynamic  Tracing
	   Guide for more information about anonymous tracing.

       -A

	   Generate  driver.conf(4)  directives	 for  anonymous	 tracing. This
	   option constructs a set of dtrace(7D) configuration file directives
	   to  enable  the  specified  probes  for  anonymous tracing and then
	   exits. By default, dtrace attempts to store the directives  to  the
	   file	 /kernel/drv/dtrace.conf.  You can modify this behavior	if you
	   use the -o option to	specify	an alternate output file.

       -b bufsz

	   Set principal trace buffer size (bufsz). The	trace buffer size  can
	   include  any	 of  the  size	suffixes k, m, g, or t.	 If the	buffer
	   space cannot	be allocated, dtrace attempts  to  reduce  the	buffer
	   size	or exit	depending on the setting of the	bufresize property.

       -c cmd

	   Run the specified command cmd and exit upon its completion. If more
	   than	one -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. Refer to
	   the	Solaris	 Dynamic  Tracing  Guide for more information on macro
	   variables.

       -C

	   Run the C preprocessor cpp(1)  over	D  programs  before  compiling
	   them.  You can pass options to the C	preprocessor using the -D, -U,
	   -I, and -H options. You can select the degree of C standard confor-
	   mance  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]

	   Define  name	when invoking cpp(1) (enabled using the	-C option). If
	   you specify the equals sign (=) and additional value, the  name  is
	   assigned  the corresponding value. This option passes the -D	option
	   to each cpp invocation.

       -e

	   Exit	after compiling	any requests and consuming  anonymous  tracing
	   state (-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	 actu-
	   ally	executing them and enabling the	corresponding instrumentation.

       -f[[provider:]module:]function[[predicate]action]]

	   Specify function name to trace or list (-l option). The correspond-
	   ing argument	 can  include  any  of	the  probe  description	 forms
	   provider:module:function,  module:function,	or function.  Unspeci-
	   fied	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 suf-
	   fixed with an optional D probe clause. You can  specify  more  than
	   one -f option on the	command	line at	a time.

       -F

	   Coalesce  trace  output  by	identifying function entry and return.
	   Function entry probe	reports	are indented and their output is  pre-
	   fixed  with	->.  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

	   Generate  an	 ELF  file  containing an embedded DTrace program. The
	   DTrace probes specified in the program are saved inside of a	 relo-
	   catable ELF object which can	be linked into another program.	If the
	   -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 file-
	   name.o.  Otherwise the ELF file is saved using the name d.out.

       -H

	   Print the pathnames of included files when invoking cpp(1) (enabled
	   using  the -C option). This option passes the -H option to each cpp
	   invocation, causing it to display the list of  pathnames,  one  for
	   each	line, to stderr.

       -h

	   Generate  a header file containing macros that correspond to	probes
	   in the specified provider definitions. This option should  be  used
	   to  generate	 a  header file	that is	included by other source files
	   for later use with the -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	with a file whose name is filename.d, then the
	   header file is saved	using the name filename.h.

       -i probe-id[[predicate] action]

	   Specify probe identifier (probe-id) to trace	or list	 (-l  option).
	   You can specify probe IDs using decimal integers as shown by	dtrace
	   -l. The -i argument can  be	suffixed  with	an  optional  D	 probe
	   clause. You can specify more	than one -i option at a	time.

       -I path

	   Add	the  specified	directory path to the search path for #include
	   files when invoking cpp(1) (enabled	using  the  -C	option).  This
	   option  passes  the -I option to each cpp invocation. The specified
	   path	is inserted into the search path ahead of the  default	direc-
	   tory	list.

       -L path

	   Add	the  specified	directory  path	 to the	search path for	DTrace
	   libraries. DTrace libraries are used	to contain common  definitions
	   that	 can  be  used	when writing D programs. The specified path is
	   added after the default library search path.

       -l

	   List	probes instead of enabling them. If the	-l  option  is	speci-
	   fied,  dtrace produces a report of the probes matching the descrip-
	   tions given using the -P, -m, -f, -n, -i, and -s options.  If  none
	   of these options are	specified, this	option lists all probes.

       -m [[provider:] module: [[predicate] action]]

	   Specify module name to trace	or list	(-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]

	   Specify  probe name to trace	or list	(-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

	   Specify the output file for the -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 /kernel/drv/dtrace.conf.	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 file-
	   name.o.  Otherwise the default output file is d.out.

       -p pid

	   Grab	the specified process-ID pid, cache  its  symbol  tables,  and
	   exit	 upon its completion. If more than one -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. Refer to the  Solaris  Dynamic  Tracing  Guide  for  more
	   information on macro	variables.

       -P provider [[predicate]	action]

	   Specify  provider  name to trace or list (-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.

       -q

	   Set	quiet  mode.  dtrace 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	state-
	   ments such as trace() and printf() is displayed to stdout.

       -s

	   Compile  the	 specified  D program source file. If the -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 instru-
	   mentation specified by the D	program	is enabled and tracing begins.

       -S

	   Show	D compiler intermediate	code. The D compiler produces a	report
	   of the intermediate code generated for each D program to stderr.

       -U name

	   Undefine the	specified name when invoking cpp(1) (enabled using the
	   -C option). This option passes the -U option	to  each  cpp  invoca-
	   tion.

       -v

	   Set	verbose	mode. If the -v	option is specified, dtrace produces a
	   program stability report showing the	 minimum  interface  stability
	   and dependency level	for the	specified D programs. DTrace stability
	   levels are explained	in further detail in the Solaris Dynamic Trac-
	   ing Guide.

       -V

	   Report  the	highest	 D  programming	interface version supported by
	   dtrace. The version information is printed to stdout	and the	dtrace
	   command  exits. Refer to the	Solaris	Dynamic	Tracing	Guide for more
	   information about DTrace versioning features.

       -w

	   Permit destructive actions in D programs specified  using  the  -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 [=val]

	   Enable  or modify a DTrace runtime option or	D compiler option. The
	   list	of options is found in	the  Solaris  Dynamic  Tracing	Guide.
	   Boolean  options are	enabled	by specifying their name. Options with
	   values are set by separating	the option  name  and  value  with  an
	   equals sign (=).

       -X a | c	| s | t

	   Specify the degree of conformance to	the ISO	C standard that	should
	   be selected when invoking cpp(1) (enabled  using  the  -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:

	   a	Default. ISO C plus K&R	compatibility extensions, with	seman-
		tic  changes required by ISO C.	This is	the default mode if -X
		is not specified. The predefined macro __STDC__	has a value of
		0 when cpp is invoked in conjunction with the -Xa option.

	   c	Conformance. Strictly conformant ISO C,	without	K&R C compati-
		bility extensions. The predefined macro	__STDC__ has  a	 value
		of 1 when cpp is invoked in conjunction	with the -Xc option.

	   s	K&R  C	only.  The  macro  __STDC__ is not defined when	cpp is
		invoked	in conjunction with the	-Xs option.

	   t	Transition. ISO	C plus K&R C compatibility extensions, without
		semantic  changes  required  by	 ISO  C.  The predefined macro
		__STDC__ has a value of	0 when cpp is invoked  in  conjunction
		with the -Xt option.

	   As the -X option only affects how the D compiler invokes the	C pre-
	   processor, the -Xa and -Xt options are equivalent from the perspec-
	   tive	 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:

	       o      __sun

	       o      __unix

	       o      __SVR4

	       o      __sparc (on SPARC	systems	only)

	       o      __sparcv9	 (on  SPARC  systems only when 64-bit programs
		      are compiled)

	       o      __i386 (on x86 systems only  when	 32-bit	 programs  are
		      compiled)

	       o      __amd64  (on  x86	 systems only when 64-bit programs are
		      compiled)

	       o      __`uname -s`_`uname -r` (for example, __SunOS_5_10)

	       o      __SUNW_D=1

	       o      __SUNW_D_VERSION=0xMMmmmuuu

		      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.	Refer  to  the
		      Solaris Dynamic Tracing Guide for	more information about
		      DTrace versioning.

       -Z

	   Permit probe	descriptions that match	zero probes. If	the -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.

OPERANDS
       You can specify zero or more additional arguments on the	dtrace command
       line  to	 define	 a  set	of macro variables ($1,	$2, and	so forth). The
       additional arguments can	be used	in D programs specified	using  the  -s
       option  or on the command line. The use of macro	variables is described
       further in the Solaris Dynamic Tracing Guide.

EXIT STATUS
       The following exit values are returned:

       0    Successful completion.

	    For	D program requests, an exit status of 0	 indicates  that  pro-
	    grams   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.

       1    An error occurred.

	    For	D program requests, an exit status of 1	indicates that program
	    compilation	failed or that the specified request could not be sat-
	    isfied.

       2    Invalid command line options or arguments were specified.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWdtrc			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+

       The command-line	syntax is  Committed.  The  human-readable  output  is
       Uncommitted.

SEE ALSO
       cpp(1),	isainfo(1),  libdtrace(3LIB),  driver.conf(4),	attributes(5),
       dtrace(7D)

       Solaris Dynamic Tracing Guide

SunOS 5.11			  5 Sep	2006			    dtrace(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | EXIT STATUS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dtrace&sektion=1&manpath=FreeBSD+8.2-RELEASE>

home | help