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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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:
<http://www.freebsd.org/cgi/man.cgi?query=dtrace&sektion=1&manpath=FreeBSD+9.0-RELEASE>

home | help