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