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.Fl G 281option. 282If the 283.Fl o 284option is present, the header file is saved using the pathname specified as the 285argument for that option. 286If the 287.Fl o 288option is not present and the DTrace program is contained within a file whose 289name is 290.Ar filename.d , 291then the header file is saved using the name 292.Ar filename.h . 293.It Fl H 294Print the pathnames of included files when invoking 295.Xr cpp 1 296(enabled using the 297.Fl C 298option). 299This option passes the 300.Fl H 301option to each 302.Xr cpp 1 303invocation, causing it to display the list of pathnames, one for each line, to 304standard error. 305.It Fl i Ar probe-id Op Oo Ar predicate Oc Ar action 306Specify probe identifier 307.Ar ( probe-id ) 308to trace or list 309.Ar ( l 310option). 311You can specify probe IDs using decimal integers as shown by `dtrace -l`. 312The 313.Fl i 314argument can be suffixed with an optional D probe clause. 315You can specify more than one 316.Fl i 317option at a time. 318.It Fl I Ar path 319Add the specified directory 320.Ar path 321to the search path for #include files when invoking 322.Xr cpp 1 323(enabled using the 324.Fl C 325option). 326This option passes the 327.Fl I 328option to each 329.Xr cpp 1 330invocation. 331The specified 332.Ar path 333is inserted into the search path ahead of the default directory list. 334.It Fl l 335List probes instead of enabling them. 336If the 337.Fl l 338option is specified, 339.Nm 340produces a report of the probes matching the descriptions given using the 341.Fl P , m , f , n , i , 342and 343.Fl s 344options. 345If none of these options are specified, this option lists all probes. 346.It Fl L Ar path 347Add the specified directory 348.Ar path 349to the search path for DTrace libraries. 350DTrace libraries are used to contain common definitions that can be used when 351writing D programs. 352The specified 353.Ar path 354is added after the default library search path. 355.It Fl m Oo Ar provider : Oc Ar module Oo Oo Ar predicate Oc Ar action Oc 356Specify module name to trace or list 357.Fl ( l 358option). 359The corresponding argument can include any of the probe description forms 360.Ar provider:module 361or 362.Ar module . 363Unspecified probe description fields are left blank and match any probes 364regardless of the values in those fields. 365If no qualifiers other than 366.Ar module 367are specified in the description, all probes with a corresponding 368.Ar module 369are matched. 370The 371.Fl m 372argument can be suffixed with an optional D probe clause. 373More than one 374.Fl m 375option can be specified on the command line at a time. 376.It Fl n Oo Oo Oo Ar provider : Oc Ar module : Oc Ar function : Oc Ar name \ 377 Oo Oo Ar predicate Oc Ar action Oc 378Specify probe name to trace or list 379.Fl ( l 380option). 381The corresponding argument can include any of the probe description forms 382.Ar provider:module:function:name , module:function:name , function:name , 383or 384.Ar name . 385Unspecified probe description fields are left blank and match any probes 386regardless of the values in those fields. 387If no qualifiers other than 388.Ar name 389are specified in the description, all probes with a corresponding 390.Ar name 391are matched. 392The 393.Fl n 394argument can be suffixed with an optional D probe clause. 395More than one 396.Fl n 397option can be specified on the command line at a time. 398.It Fl o Ar output 399Specify the 400.Ar output 401file for the 402.Fl A , G , 403and 404.Fl l 405options, or for the traced data itself. 406If the 407.Fl A 408option is present and 409.Fl o 410is not present, the default output file is 411.Pa /boot/dtrace.dof . 412If the 413.Fl G 414option is present and the 415.Fl s 416option's argument is of the form 417.Ar filename.d 418and 419.Fl o 420is not present, the default output file is 421.Ar filename.o . 422Otherwise the default output file is 423.Ar d.out . 424.It Fl p Ar pid 425Grab the specified process-ID 426.Ar pid , 427cache its symbol tables, and exit upon its completion. 428If more than one 429.Fl p 430option is present on the command line, 431.Nm 432exits when all commands have exited, reporting the exit status for each process 433as it terminates. 434The first process-ID is made available to any D programs specified on the 435command line or using the 436.Fl s 437option through the 438.Li $target 439macro variable. 440.It Fl P Ar provider Oo Oo Ar predicate Oc Ar action Oc 441Specify provider name to trace or list 442.Fl ( l 443option). 444The remaining probe description fields module, function, and name are left 445blank and match any probes regardless of the values in those fields. 446The 447.Fl P 448argument can be suffixed with an optional D probe clause. 449You can specify more than one 450.Fl P 451option on the command line at a time. 452.It Fl q 453Set quiet mode. 454.Nm 455suppresses messages such as the number of probes matched by the specified 456options and D programs and does not print column headers, the CPU ID, the probe 457ID, or insert newlines into the output. 458Only data traced and formatted by D program statements such as 459.Ql dtrace() 460and 461.Ql printf() 462is displayed to standard output. 463.It Fl s Ar script 464Compile the specified D program source file. 465If the 466.Fl e 467option is present, the program is compiled but instrumentation is not enabled. 468If the 469.Fl l 470option is present, the program is compiled and the set of probes matched by it 471is listed, but instrumentation is not enabled. 472If none of 473.Fl e , l , G , 474or 475.Fl A 476are present, the instrumentation specified by the D program is enabled and 477tracing begins. 478.It Fl S 479Show D compiler intermediate code. 480The D compiler produces a report of the intermediate code generated for each D 481program to standard error. 482.It Fl U Ar name 483Undefine the specified 484.Ar name 485when invoking 486.Xr cpp 1 487(enabled using the 488.Fl C 489option). 490This option passes the 491.Fl U 492option to each 493.Xr cpp 1 494invocation. 495.It Fl v 496Set verbose mode. 497If the 498.Fl v 499option is specified, 500.Nm 501produces a program stability report showing the minimum interface stability and 502dependency level for the specified D programs. 503.It Fl V 504Report the highest D programming interface version supported by 505.Nm . 506The version information is printed to standard output and the 507.Nm 508command exits. 509.It Fl w 510Permit destructive actions in D programs specified using the 511.Fl s , P , m , f , n , 512or 513.Fl i 514options. 515If the 516.Fl w 517option is not specified, 518.Nm 519does not permit the compilation or enabling of a D program that contains 520destructive actions. 521.It Fl x Ar arg Op Ns = Ns value 522Enable or modify a DTrace runtime option or D compiler option. 523Boolean options are enabled by specifying their name. 524Options with values are set by separating the option name and value with an 525equals sign (=). 526.It Fl X Cm a | c | s | t 527Specify the degree of conformance to the ISO C standard that should be selected 528when invoking 529.Xr cpp 1 530(enabled using the 531.Fl C 532option). 533The 534.Fl X 535option argument affects the value and presence of the __STDC__ macro depending 536upon the value of the argument letter. 537.sp 538The 539.Fl X 540option supports the following arguments: 541.Bl -tag -width indent 542.It a 543Default. 544ISO C plus K&R compatibility extensions, with semantic changes required by ISO 545C. 546This is the default mode if 547.Fl X 548is not specified. 549The predefined macro __STDC__ has a value of 0 when 550.Xr cpp 1 551is invoked in conjunction with the 552.Fl Xa 553option. 554.It c 555Conformance. 556Strictly conformant ISO C, without K&R C compatibility extensions. 557The predefined macro __STDC__ has a value of 1 when 558.Xr cpp 1 559is invoked in conjunction with the 560.Fl \&Xc 561option. 562.It s 563K&R C only. 564The macro __STDC__ is not defined when 565.Xr cpp 1 566is invoked in conjunction with the 567.Fl Xs 568option. 569.It t 570Transition. 571ISO C plus K&R C compatibility extensions, without semantic changes required by 572ISO C. 573The predefined macro __STDC__ has a value of 0 when 574.Xr cpp 1 575is invoked in conjunction with the 576.Fl Xt 577option. 578.El 579.Pp 580As the 581.Fl X 582option only affects how the D compiler invokes the C preprocessor, the 583.Fl Xa 584and 585.Fl Xt 586options are equivalent from the perspective of D and both are provided only to 587ease re-use of settings from a C build environment. 588.Pp 589Regardless of the 590.Fl X 591mode, the following additional C preprocessor definitions are always specified 592and valid in all modes: 593.Bl -bullet -offset indent 594.It 595__sun 596.It 597__unix 598.It 599__SVR4 600.It 601__sparc (on SPARC systems only) 602.It 603__sparcv9 (on SPARC systems only when 64-bit programs are compiled) 604.It 605__i386 (on x86 systems only when 32-bit programs are compiled) 606.It 607__amd64 (on x86 systems only when 64-bit programs are compiled) 608.It 609__`uname -s`_`uname -r` (for example, 610.Ql FreeBSD_9.2-RELEASE . 611.It 612__SUNW_D=1 613.It 614.No __SUNW_D_VERSION=0x Ns Ar MMmmmuuu 615.Pp 616Where 617.Ar MM 618is the major release value in hexadecimal, 619.Ar mmm 620is the minor release value in hexadecimal, and 621.Ar uuu 622is the micro release value in hexadecimal. 623.El 624.It Fl Z 625Permit probe descriptions that match zero probes. 626If the 627.Fl Z 628option is not specified, 629.Nm 630reports an error and exits if any probe descriptions specified in D program 631files 632.Fl ( s 633option) or on the command line 634.Fl ( P , m , f , n , 635or 636.Fl i 637options) contain descriptions that do not match any known probes. 638.El 639.Sh OPERANDS 640You can specify zero or more additional arguments on the 641.Nm 642command line to define a set of macro variables and so forth). 643The additional arguments can be used in D programs specified using the 644.Fl s 645option or on the command line. 646.Sh FILES 647.Bl -tag -width /boot/dtrace.dof -compact 648.It Pa /boot/dtrace.dof 649File for anonymous tracing directives. 650.El 651.Sh EXIT STATUS 652The following exit statuses are returned: 653.Bl -tag -width indent 654.It 0 655Successful completion. 656.Pp 657For D program requests, an exit status of 0 indicates that programs were 658successfully compiled, probes were successfully enabled, or anonymous state 659was successfully retrieved. 660.Nm 661returns 0 even if the specified tracing requests encountered errors or drops. 662.It 1 663An error occurred. 664.Pp 665For D program requests, an exit status of 1 indicates that program compilation 666failed or that the specified request could not be satisfied. 667.It 2 668Invalid command line options or arguments were specified. 669.El 670.Sh SEE ALSO 671.Xr cpp 1 , 672.Xr dtruss 1 , 673.Xr elf 5 674.Rs 675.%T Solaris Dynamic Tracing Guide 676.Re 677