1'\" te 2.\" CDDL HEADER START 3.\" 4.\" The contents of this file are subject to the terms of the 5.\" Common Development and Distribution License (the "License"). 6.\" You may not use this file except in compliance with the License. 7.\" 8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9.\" or http://www.opensolaris.org/os/licensing. 10.\" See the License for the specific language governing permissions 11.\" and limitations under the License. 12.\" 13.\" When distributing Covered Code, include this CDDL HEADER in each 14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15.\" If applicable, add the following below this CDDL HEADER, with the 16.\" fields enclosed by brackets "[]" replaced with your own identifying 17.\" information: Portions Copyright [yyyy] [name of copyright owner] 18.\" 19.\" CDDL HEADER END 20.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 21.\" 22.\" $FreeBSD$ 23.\" 24.Dd October 5, 2013 25.Dt DTRACE 1 26.Os 27.Sh NAME 28.Nm dtrace 29.Nd dynamic tracing compiler and tracing utility 30.Sh SYNOPSIS 31.Nm 32.Op Fl 32 | Fl 64 33.Op Fl aACeFGhHlqSvVwZ 34.Op Fl b Ar bufsz 35.Op Fl c Ar cmd 36.Op Fl D Ar name Op Ns = Ns value 37.Op Fl I Ar path 38.Op Fl L Ar path 39.Op Fl o Ar output 40.Op Fl s Ar script 41.Op Fl U Ar name 42.Op Fl x Ar arg Op Ns = Ns value 43.Op Fl X Cm a | c | s | t 44.Op Fl p Ar pid 45.Op Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc 46.Op Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc 47.Op Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \ 48 Oc Ar action Oc 49.Op Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \ 50 Oo Oo Ar predicate Oc Ar action Oc 51.Op Fl i Ar probe-id Oo Oo Ar predicate Oc Ar action Oc 52.Sh DESCRIPTION 53DTrace is a comprehensive dynamic tracing framework ported from Solaris. 54DTrace provides a powerful infrastructure that permits administrators, 55developers, and service personnel to concisely answer arbitrary questions about 56the behavior of the operating system and user programs. 57.Pp 58The 59.Nm 60command provides a generic interface to the essential services provided by the 61DTrace facility, including: 62.Bl -bullet -offset indent 63.It 64Options that list the set of probes and providers currently published by DTrace 65.It 66Options that enable probes directly using any of the probe description 67specifiers (provider, module, function, name) 68.It 69Options that run the D compiler and compile one or more D program files or 70programs written directly on the command line 71.It 72Options that generate anonymous tracing programs 73.It 74Options that generate program stability reports 75.It 76Options that modify DTrace tracing and buffering behavior and enable 77additional D compiler features 78.El 79.Pp 80You can use 81.Nm 82to create D scripts by using it in a shebang declaration to create an 83interpreter file. 84You can also use 85.Nm 86to attempt to compile D programs and determine their properties without 87actually enabling traces using the 88.Fl e 89option. 90.Sh OPTIONS 91The arguments accepted by the 92.Fl P , 93.Fl m , 94.Fl f , 95.Fl n , 96and 97.Fl i 98options can include an optional D language 99.Ar predicate 100enclosed in slashes and an optional D language 101.Ar action 102statement list enclosed in braces. 103D program code specified on the command line must be appropriately quoted to 104avoid interpretation of meta-characters by the shell. 105.Pp 106The following options are supported: 107.Bl -tag -width indent 108.It Fl 32 | Fl 64 109The D compiler produces programs using the native data model of the operating 110system kernel. 111If the 112.Fl 32 113option is specified, 114.Nm 115forces the D compiler to compile a D program using the 32-bit data model. 116If the 117.Fl 64 118option is specified, 119.Nm 120forces the D compiler to compile a D program using the 64-bit data model. 121These options are typically not required as 122.Nm 123selects the native data model as the default. 124The data model affects the sizes of integer types and other language properties. 125D programs compiled for either data model can be executed on both 32-bit and 12664-bit kernels. 127The 128.Fl 32 129and 130.Fl 64 131options also determine the 132.Xr elf 5 133file format (ELF32 or ELF64) produced by the 134.Fl G 135option. 136.It Fl a 137Claim anonymous tracing state and display the traced data. 138You can combine the 139.Fl a 140option with the 141.Fl e 142option to force 143.Nm 144to exit immediately after consuming the anonymous tracing state rather than 145continuing to wait for new data. 146.It Fl A 147Generate directives for anonymous tracing and write them to 148.Pa /boot/dtrace.dof . 149This option constructs a set of dtrace configuration file directives to enable 150the specified probes for anonymous tracing and then exits. 151By default, 152.Nm 153attempts to store the directives to the file 154.Pa /boot/dtrace.dof . 155This behavior can be modified using the 156.Fl o 157option to specify an alternate output file. 158.It Fl b Ar bufsz 159Set the principal trace buffer size to 160.Ar bufsz . 161The trace buffer size can include any of the size suffixes k, m, g, or t. 162If the buffer space cannot be allocated, 163.Nm dtrace 164attempts to reduce the buffer size or exit depending on the setting of the 165bufresize property. 166.It Fl c Ar cmd 167Run the specified command 168.Ar cmd 169and exit upon its completion. 170If more than one 171.Fl c 172option is present on the command line, 173.Nm dtrace 174exits when all commands have exited, reporting the exit status for each child 175process as it terminates. 176The process ID of the first command is made available to any D programs 177specified on the command line or using the 178.Fl s 179option through the 180.Li $target 181macro variable. 182.It Fl C 183Run the C preprocessor 184.Xr cpp 1 185over D programs before compiling them. 186You can pass options to the C preprocessor using the 187.Fl D , 188.Fl U , 189.Fl I , 190and 191.Fl H 192options. 193You can select the degree of C standard conformance if you use the 194.Fl X 195option. 196For a description of the set of tokens defined by the D compiler when invoking 197the C preprocessor, see 198.Fl X . 199.It Fl D Ar name Op Ns = Ns value 200Define 201.Ar name 202when invoking 203.Xr cpp 1 204(enabled using the 205.Fl C 206option). 207If you specify an additional 208.Ar value , 209the name is assigned the corresponding value. 210This option passes the 211.Fl D 212option to each 213.Xr cpp 1 214invocation. 215.It Fl e 216Exit after compiling any requests and consuming anonymous tracing state 217.Fl ( a 218option) but prior to enabling any probes. 219You can combine this option with the 220.Fl a 221option to print anonymous tracing data and exit. 222You can also combine this option with D compiler options. 223This combination verifies that the programs compile without actually executing 224them and enabling the corresponding instrumentation. 225.It Fl f Oo Oo Ar provider : Oc Ar module : Oc Ar function Oo Oo Ar predicate \ 226 Oc Ar action Oc 227Specify function name to trace or list 228.Fl ( l 229option). 230The corresponding argument can include any of the probe description forms 231.Ar provider:module:function , 232.Ar module:function , 233or 234.Ar function . 235Unspecified probe description fields are left blank and match any probes 236regardless of the values in those fields. 237If no qualifiers other than 238.Ar function 239are specified in the description, all probes with the corresponding 240.Ar function 241are matched. 242The 243.Fl f 244argument can be suffixed with an optional D probe clause. 245You can specify more than one 246.Fl f 247option on the command line at a time. 248.It Fl F 249Coalesce trace output by identifying function entry and return. 250Function entry probe reports are indented and their output is prefixed with 251.Ql -> . 252Function return probe reports are unindented and their output is prefixed with 253.Ql <- . 254System call entry probe reports are indented and their output is prefixed with 255.Ql => . 256System call return probe reports are unindented and their output is prefixed 257with 258.Ql <= . 259.It Fl G 260Generate an ELF file containing an embedded DTrace program. 261The DTrace probes specified in the program are saved inside of a relocatable ELF 262object which can be linked into another program. 263If the 264.Fl o 265option is present, the ELF file is saved using the pathname specified as the 266argument for this operand. 267If the 268.Fl o 269option is not present and the DTrace program is contained with a file whose name 270is 271.Ar filename.d , 272then the ELF file is saved using the name 273.Ar filename.o . 274Otherwise the ELF file is saved using the name d.out. 275.It Fl h 276Generate a header file containing macros that correspond to probes in the 277specified provider definitions. 278This option should be used to generate a header file that is included by other 279source files for later use with the 280.It Fl H 281Print the pathnames of included files when invoking 282.Xr cpp 1 283(enabled using the 284.Fl C 285option). 286This option passes the 287.Fl H 288option to each 289.Xr cpp 1 290invocation, causing it to display the list of pathnames, one for each line, to 291standard error. 292.Fl G 293option. 294If the 295.Fl o 296option 297is present, the header file is saved using the pathname specified as the 298argument for that option. 299If the 300.Fl o 301option is not present and the DTrace program is contained with a file whose 302name is 303.Ar filename.d , 304then the header file is saved using the name 305.Ar filename.h . 306.It Fl i Ar probe-id Op Oo Ar predicate Oc Ar action 307Specify probe identifier 308.Ar ( probe-id ) 309to trace or list 310.Ar ( l 311option). 312You can specify probe IDs using decimal integers as shown by `dtrace -l`. 313The 314.Fl i 315argument can be suffixed with an optional D probe clause. 316You can specify more than one 317.Fl i 318option at a time. 319.It Fl I Ar path 320Add the specified directory 321.Ar path 322to the search path for #include files when invoking 323.Xr cpp 1 324(enabled using the 325.Fl C 326option). 327This option passes the 328.Fl I 329option to each 330.Xr cpp 1 331invocation. 332The specified 333.Ar path 334is inserted into the search path ahead of the default directory list. 335.It Fl l 336List probes instead of enabling them. 337If the 338.Fl l 339option is specified, 340.Nm 341produces a report of the probes matching the descriptions given using the 342.Fl P , m , f , n , i , 343and 344.Fl s 345options. 346If none of these options are specified, this option lists all probes. 347.It Fl L Ar path 348Add the specified directory 349.Ar path 350to the search path for DTrace libraries. 351DTrace libraries are used to contain common definitions that can be used when 352writing D programs. 353The specified 354.Ar path 355is added after the default library search path. 356.It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc 357Specify module name to trace or list 358.Fl ( l 359option). 360The corresponding argument can include any of the probe description forms 361.Ar provider:module 362or 363.Ar module . 364Unspecified probe description fields are left blank and match any probes 365regardless of the values in those fields. 366If no qualifiers other than 367.Ar module 368are specified in the description, all probes with a corresponding 369.Ar module 370are matched. 371The 372.Fl m 373argument can be suffixed with an optional D probe clause. 374More than one 375.Fl m 376option can be specified on the command line at a time. 377.It Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \ 378 Oo Oo Ar predicate Oc Ar action Oc 379Specify probe name to trace or list 380.Fl ( l 381option). 382The corresponding argument can include any of the probe description forms 383.Ar provider:module:function:name , module:function:name , function:name , 384or 385.Ar name . 386Unspecified probe description fields are left blank and match any probes 387regardless of the values in those fields. 388If no qualifiers other than 389.Ar name 390are specified in the description, all probes with a corresponding 391.Ar name 392are matched. 393The 394.Fl n 395argument can be suffixed with an optional D probe clause. 396More than one 397.Fl n 398option can be specified on the command line at a time. 399.It Fl o Ar output 400Specify the 401.Ar output 402file for the 403.Fl A , G , 404and 405.Fl l 406options, or for the traced data itself. 407If the 408.Fl A 409option is present and 410.Fl o 411is not present, the default output file is 412.Pa /boot/dtrace.dof . 413If the 414.Fl G 415option is present and the 416.Fl s 417option's argument is of the form 418.Ar filename.d 419and 420.Fl o 421is not present, the default output file is 422.Ar filename.o . 423Otherwise the default output file is 424.Ar d.out . 425.It Fl p Ar pid 426Grab the specified process-ID 427.Ar pid , 428cache its symbol tables, and exit upon its completion. 429If more than one 430.Fl p 431option is present on the command line, 432.Nm 433exits when all commands have exited, reporting the exit status for each process 434as it terminates. 435The first process-ID is made available to any D programs specified on the 436command line or using the 437.Fl s 438option through the 439.Li $target 440macro variable. 441.It Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc 442Specify provider name to trace or list 443.Fl ( l 444option). 445The remaining probe description fields module, function, and name are left 446blank and match any probes regardless of the values in those fields. 447The 448.Fl P 449argument can be suffixed with an optional D probe clause. 450You can specify more than one 451.Fl P 452option on the command line at a time. 453.It Fl q 454Set quiet mode. 455.Nm 456suppresses messages such as the number of probes matched by the specified 457options and D programs and does not print column headers, the CPU ID, the probe 458ID, or insert newlines into the output. 459Only data traced and formatted by D program statements such as 460.Ql dtrace() 461and 462.Ql printf() 463is displayed to standard output. 464.It Fl s Ar script 465Compile the specified D program source file. 466If the 467.Fl e 468option is present, the program is compiled but instrumentation is not enabled. 469If the 470.Fl l 471option is present, the program is compiled and the set of probes matched by it 472is listed, but instrumentation is not enabled. 473If none of 474.Fl e , l , G , 475or 476.Fl A 477are present, the instrumentation specified by the D program is enabled and 478tracing begins. 479.It Fl S 480Show D compiler intermediate code. 481The D compiler produces a report of the intermediate code generated for each D 482program to standard error. 483.It Fl U Ar name 484Undefine the specified 485.Ar name 486when invoking 487.Xr cpp 1 488(enabled using the 489.Fl C 490option). 491This option passes the 492.Fl U 493option to each 494.Xr cpp 1 495invocation. 496.It Fl v 497Set verbose mode. 498If the 499.Fl v 500option is specified, 501.Nm 502produces a program stability report showing the minimum interface stability and 503dependency level for the specified D programs. 504.It Fl V 505Report the highest D programming interface version supported by 506.Nm . 507The version information is printed to standard output and the 508.Nm 509command exits. 510.It Fl w 511Permit destructive actions in D programs specified using the 512.Fl s , P , m , f , n , 513or 514.Fl i 515options. 516If the 517.Fl w 518option is not specified, 519.Nm 520does not permit the compilation or enabling of a D program that contains 521destructive actions. 522.It Fl x Ar arg Op Ns = Ns value 523Enable or modify a DTrace runtime option or D compiler option. 524Boolean options are enabled by specifying their name. 525Options with values are set by separating the option name and value with an 526equals sign (=). 527.It Fl X Cm a | c | s | t 528Specify the degree of conformance to the ISO C standard that should be selected 529when invoking 530.Xr cpp 1 531(enabled using the 532.Fl C 533option). 534The 535.Fl X 536option argument affects the value and presence of the __STDC__ macro depending 537upon the value of the argument letter. 538.sp 539The 540.Fl X 541option supports the following arguments: 542.Bl -tag -width indent 543.It a 544Default. 545ISO C plus K&R compatibility extensions, with semantic changes required by ISO 546C. 547This is the default mode if 548.Fl X 549is not specified. 550The predefined macro __STDC__ has a value of 0 when 551.Xr cpp 1 552is invoked in conjunction with the 553.Fl Xa 554option. 555.It c 556Conformance. 557Strictly conformant ISO C, without K&R C compatibility extensions. 558The predefined macro __STDC__ has a value of 1 when 559.Xr cpp 1 560is invoked in conjunction with the 561.Fl \&Xc 562option. 563.It s 564K&R C only. 565The macro __STDC__ is not defined when 566.Xr cpp 1 567is invoked in conjunction with the 568.Fl Xs 569option. 570.It t 571Transition. 572ISO C plus K&R C compatibility extensions, without semantic changes required by 573ISO C. 574The predefined macro __STDC__ has a value of 0 when 575.Xr cpp 1 576is invoked in conjunction with the 577.Fl Xt 578option. 579.El 580.Pp 581As the 582.Fl X 583option only affects how the D compiler invokes the C preprocessor, the 584.Fl Xa 585and 586.Fl Xt 587options are equivalent from the perspective of D and both are provided only to 588ease re-use of settings from a C build environment. 589.Pp 590Regardless of the 591.Fl X 592mode, the following additional C preprocessor definitions are always specified 593and valid in all modes: 594.Bl -bullet -offset indent 595.It 596__sun 597.It 598__unix 599.It 600__SVR4 601.It 602__sparc (on SPARC systems only) 603.It 604__sparcv9 (on SPARC systems only when 64-bit programs are compiled) 605.It 606__i386 (on x86 systems only when 32-bit programs are compiled) 607.It 608__amd64 (on x86 systems only when 64-bit programs are compiled) 609.It 610__`uname -s`_`uname -r` (for example, 611.Ql FreeBSD_9.2-RELEASE . 612.It 613__SUNW_D=1 614.It 615.No __SUNW_D_VERSION=0x Ns Ar MMmmmuuu 616.Pp 617Where 618.Ar MM 619is the major release value in hexadecimal, 620.Ar mmm 621is the minor release value in hexadecimal, and 622.Ar uuu 623is the micro release value in hexadecimal. 624.El 625.It Fl Z 626Permit probe descriptions that match zero probes. 627If the 628.Fl Z 629option is not specified, 630.Nm 631reports an error and exits if any probe descriptions specified in D program 632files 633.Fl ( s 634option) or on the command line 635.Fl ( P , m , f , n , 636or 637.Fl i 638options) contain descriptions that do not match any known probes. 639.El 640.Sh OPERANDS 641You can specify zero or more additional arguments on the 642.Nm 643command line to define a set of macro variables and so forth). 644The additional arguments can be used in D programs specified using the 645.Fl s 646option or on the command line. 647.Sh FILES 648.Bl -tag -width /boot/dtrace.dof -compact 649.It Pa /boot/dtrace.dof 650File for anonymous tracing directives. 651.El 652.Sh EXIT STATUS 653The following exit statuses are returned: 654.Bl -tag -width indent 655.It 0 656Successful completion. 657.Pp 658For D program requests, an exit status of 0 indicates that programs were 659successfully compiled, probes were successfully enabled, or anonymous state 660was successfully retrieved. 661.Nm 662returns 0 even if the specified tracing requests encountered errors or drops. 663.It 1 664An error occurred. 665.Pp 666For D program requests, an exit status of 1 indicates that program compilation 667failed or that the specified request could not be satisfied. 668.It 2 669Invalid command line options or arguments were specified. 670.El 671.Sh SEE ALSO 672.Xr cpp 1 , 673.Xr dtruss 1 , 674.Xr elf 5 675.Rs 676.%T Solaris Dynamic Tracing Guide 677.Re 678