dtrace man page on FreeBSD

Man page or keyword search:  
man Server   9747 pages
apropos Keyword Search (all sections)
Output format
FreeBSD logo
[printable version]

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)
[top]

List of man pages available for FreeBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net