cddl/contrib/opensolaris/cmd/dtrace/dtrace.1

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