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