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