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 Op-
       erating System. 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  Solaris  Dynamic  Tracing Guide describes how to use DTrace	to ob-
       serve, debug, and tune system behavior. Refer to	this book  for	a  de-
       tailed description of DTrace features, including	the bundled DTrace ob-
       servability 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 en-
       abling tracing using the	-e option. See OPTIONS.	See  the  Solaris  Dy-
       namic  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  in-
       clude  an  optional D language predicate	enclosed in slashes // and op-
       tional 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 de-
	   termine 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 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 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 op-
	   tion	constructs a set of dtrace(7D) configuration  file  directives
	   to  enable  the specified probes for	anonymous tracing and then ex-
	   its.	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 to-
	   kens	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 re-
	   turn	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  op-
	   tion	 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 li-
	   braries. 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 de-
	   scription, 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 op-
	   tion	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, re-
	   porting 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 in-
	   formation 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 en-
	   abled. 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 instrumenta-
	   tion	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  in-
		voked 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 So-
		      laris 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 ad-
       ditional	arguments can be used in D programs specified using the	-s op-
       tion 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  en-
	    abled,  or	anonymous state	was successfully retrieved. dtrace re-
	    turns 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 Un-
       committed.

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.3-RELEASE>

home | help