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