1 /* 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 */ 21 22 /* 23 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 * 26 * ident "%Z%%M% %I% %E% SMI" 27 */ 28 package org.opensolaris.os.dtrace; 29 30 import java.io.*; 31 import java.util.*; 32 33 /** 34 * Interface to the native DTrace library, each instance is a single 35 * DTrace consumer. To consume the output of DTrace program actions, 36 * {@link #addConsumerListener(ConsumerListener l) register a probe data 37 * listener}. To get a snapshot of all aggregations in a D program on 38 * your own programmatic interval without relying on DTrace actions to 39 * generate that output, use the {@link #getAggregate()} method. 40 * 41 * @see ProbeData 42 * @see Aggregate 43 * 44 * @author Tom Erickson 45 */ 46 public interface Consumer { 47 48 /** 49 * Optional flags passed to {@link #open(Consumer.OpenFlag[] flags) 50 * open()}. 51 */ 52 public enum OpenFlag { 53 /** 54 * Generate 32-bit D programs. {@code ILP32} and {@link 55 * Consumer.OpenFlag#LP64 LP64} are mutually exclusive. 56 */ 57 ILP32, 58 /** 59 * Generate 64-bit D programs. {@code LP64} and {@link 60 * Consumer.OpenFlag#ILP32 ILP32} are mutually exclusive. 61 */ 62 LP64, 63 }; 64 65 /** 66 * Opens this DTrace consumer. Optional flags indicate behaviors 67 * that can only be set at the time of opening. Most optional 68 * behaviors are set using {@link #setOption(String option, String 69 * value) setOption()} after opening the consumer. In the great 70 * majority of cases, the consumer is opened without specifying any 71 * flags: 72 * <pre> {@code consumer.open();}</pre> 73 * Subsequent calls to set options, compile DTrace programs, enable 74 * probes, and run this consumer may be made from any thread. 75 * 76 * @throws NullPointerException if any of the given open flags is 77 * {@code null} 78 * @throws IllegalArgumentException if any of the given flags are 79 * mutually exlusive 80 * @throws IllegalStateException if this consumer is closed or has 81 * already been opened 82 * @throws DTraceException if an exception occurs in the native 83 * DTrace library 84 * @see #compile(File program, String[] macroArgs) 85 * @see #compile(String program, String[] macroArgs) 86 * @see #enable() 87 * @see #go() 88 */ 89 public void open(OpenFlag ... flags) throws DTraceException; 90 91 /** 92 * Compiles the given D program string. Optional macro arguments 93 * replace corresponding numbered macro variables in the D program 94 * starting at {@code $1}. 95 * 96 * @param program program string 97 * @param macroArgs macro substitutions for <i>$n</i> placeholders 98 * embedded in the given D program: {@code macroArgs[0]} replaces 99 * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 100 * occurrences of {@code $2}, and so on. {@code $0} is 101 * automatically replaced by the executable name and should not be 102 * included in the {@code macroArgs} parameter. See the <a 103 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view> 104 * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 105 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 106 * @return a non-null {@code Program} identifier that may be passed 107 * to {@link #enable(Program program) enable()} 108 * @throws NullPointerException if the given program string or any 109 * of the given macro arguments is {@code null} 110 * @throws IllegalStateException if called before {@link 111 * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 112 * consumer is closed 113 * @throws DTraceException if an exception occurs in the native 114 * DTrace library 115 * @see #compile(File program, String[] macroArgs) 116 */ 117 public Program compile(String program, String ... macroArgs) 118 throws DTraceException; 119 120 /** 121 * Compiles the given D program file. Optional macro arguments 122 * replace corresponding numbered macro variables in the D program 123 * starting at {@code $1}. 124 * 125 * @param program program file 126 * @param macroArgs macro substitutions for <i>$n</i> placeholders 127 * embedded in the given D program: {@code macroArgs[0]} replaces 128 * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 129 * occurrences of {@code $2}, and so on. {@code $0} is 130 * automatically set to the name of the given file and should not be 131 * included in the {@code macroArgs} parameter. See the <a 132 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view> 133 * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 134 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 135 * @return a non-null {@code Program} identifier that may be passed 136 * to {@link #enable(Program program) enable()} 137 * @throws NullPointerException if the given program file or any of 138 * the given macro arguments is {@code null} 139 * @throws IllegalStateException if called before {@link 140 * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 141 * consumer is closed 142 * @throws DTraceException if an exception occurs in the native 143 * DTrace library 144 * @throws FileNotFoundException if the given program file cannot be 145 * opened 146 * @throws IOException if an I/O error occurs while reading the 147 * contents of the given program file 148 * @throws SecurityException if a security manager exists and its 149 * {@code checkRead()} method denies read access to the file 150 * @see #compile(String program, String[] macroArgs) 151 */ 152 public Program compile(File program, String ... macroArgs) 153 throws DTraceException, IOException, SecurityException; 154 155 /** 156 * Enables all DTrace probes compiled by this consumer. Call {@code 157 * enable()} with no argument to enable everything this consumer has 158 * compiled so far (most commonly a single program, the only one to 159 * be compiled). Call with one {@link Program} at a time if you 160 * need information about enabled probes specific to each program. 161 * 162 * @throws IllegalStateException if called before compiling at least 163 * one program, or if any compiled program is already enabled, or if 164 * {@link #go()} was already called, or if this consumer is closed 165 * @throws DTraceException if an exception occurs in the native 166 * DTrace library 167 * @see #enable(Program program) 168 */ 169 public void enable() throws DTraceException; 170 171 /** 172 * Enables DTrace probes matching the given program and attaches 173 * information about those probes to the given program. A probe 174 * matched multiple times (within the same D program or in multiple 175 * D programs) triggers the actions associated with each matching 176 * occurrence every time that probe fires. 177 * 178 * @param program A {@code Program} identifier returned by {@link 179 * #compile(String program, String[] macroArgs) compile(String 180 * program, ...)} or {@link #compile(File program, String[] 181 * macroArgs) compile(File program, ...)}: If the given program is 182 * {@code null}, the call has the same behavior as {@link #enable()} 183 * with no argument; if the given program is non-null, the call 184 * enables only those probes matching that program. In the latter 185 * case, the {@code Program} parameter is modified as a way of 186 * passing back information about the given program and its matching 187 * probes, including program stability. 188 * @throws IllegalArgumentException if the given program is non-null 189 * and not compiled by this {@code Consumer} 190 * @throws IllegalStateException if the given program is already 191 * enabled (or if the given program is {@code null} and <i>any</i> 192 * program is already enabled), or if {@link #go()} was already 193 * called, or if this consumer is closed 194 * @throws DTraceException if an exception occurs in the native 195 * DTrace library 196 * @see #compile(String program, String[] macroArgs) 197 * @see #compile(File program, String[] macroArgs) 198 * @see #enable() 199 * @see #getProgramInfo(Program program) 200 */ 201 public void enable(Program program) throws DTraceException; 202 203 /** 204 * Attaches information about matching DTrace probes to the given 205 * program. Attaches the same information to the given program as 206 * that attached by {@link #enable(Program program)} but without 207 * enabling the probes. 208 * 209 * @throws NullPointerException if the given program is {@code null} 210 * @throws IllegalArgumentException if the given program was not 211 * compiled by this {@code Consumer} 212 * @throws IllegalStateException if called after {@link #close()} 213 * @throws DTraceException if an exception occurs in the native 214 * DTrace library 215 * @see #compile(String program, String[] macroArgs) 216 * @see #compile(File program, String[] macroArgs) 217 * @see #enable(Program program) 218 */ 219 public void getProgramInfo(Program program) throws DTraceException; 220 221 /** 222 * Sets a boolean option. 223 * 224 * @throws NullPointerException if the given option is {@code null} 225 * @throws DTraceException if a value is expected for the given 226 * option, or if the option is otherwise invalid 227 * @throws IllegalStateException if called before {@link 228 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 229 * the given option is a boolean compile-time option and {@link 230 * #go()} has already been called (see {@link Option} for a 231 * breakdown of runtime and compile-time options) 232 * @see #setOption(String option, String value) 233 * @see #unsetOption(String option) 234 */ 235 public void setOption(String option) throws DTraceException; 236 237 /** 238 * Unsets a boolean option. 239 * 240 * @throws NullPointerException if the given option is {@code null} 241 * @throws DTraceException if the given option is not a boolean 242 * option, or if the option is otherwise invalid 243 * @throws IllegalStateException if called before {@link 244 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 245 * the given option is a boolean compile-time option and {@link 246 * #go()} has already been called (see {@link Option} for a 247 * breakdown of runtime and compile-time options) 248 * @see #setOption(String option) 249 */ 250 public void unsetOption(String option) throws DTraceException; 251 252 /** 253 * Sets the value of a DTrace option. If the given option affects 254 * compile-time behavior, it must be set before calling {@link 255 * #compile(String program, String[] macroArgs) compile(String 256 * program, ...)} or {@link #compile(File program, String[] 257 * macroArgs) compile(File program, ...)} in order to have an effect 258 * on compilation. Some runtime options including {@link 259 * Option#switchrate switchrate} and {@link Option#aggrate aggrate} 260 * are settable while a consumer is running; others must be set 261 * before calling {@link #go()}. See the <a 262 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlis?a=view> 263 * <b>Options and Tunables</b></a> chapter of the <i>Solaris Dynamic 264 * Guide</i> for information about specific options. 265 * 266 * @throws NullPointerException if the given option or value is 267 * {@code null} 268 * @throws IllegalStateException if called before {@link 269 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 270 * the given option is a boolean compile-time option and {@code 271 * go()} has already been called (see {@link Option} for a breakdown 272 * of runtime and compile-time options) 273 * @throws DTraceException for any of the following: 274 * <ul><li>The option is invalid</li> 275 * <li>The value is invalid for the given option</li> 276 * <li>{@code go()} has been called to start this consumer, and the 277 * option is not settable on a running consumer (some runtime 278 * options, including {@link Option#switchrate switchrate} and 279 * {@link Option#aggrate aggrate} are settable while the consumer is 280 * running)</li></ul> 281 * 282 * @see #open(OpenFlag[] flags) 283 * @see #getOption(String option) 284 * @see Option 285 */ 286 public void setOption(String option, String value) throws DTraceException; 287 288 /** 289 * Gets the value of a DTrace option. 290 * 291 * @throws NullPointerException if the given option is {@code null} 292 * @throws IllegalStateException if called before {@link 293 * #open(OpenFlag[] flags) open()} or after {@link #close()} 294 * @throws DTraceException if the given option is invalid 295 * @return the value of the given DTrace option: If the given option 296 * is a boolean option and is currently unset, the returned value is 297 * {@link Option#UNSET}. If the given option is a <i>size</i> 298 * option, the returned value is in bytes. If the given option is a 299 * <i>time</i> option, the returned value is in nanoseconds. If the 300 * given option is {@link Option#bufpolicy bufpolicy}, the returned 301 * value is one of {@link Option#BUFPOLICY_RING BUFPOLICY_RING}, 302 * {@link Option#BUFPOLICY_FILL BUFPOLICY_FILL}, or {@link 303 * Option#BUFPOLICY_SWITCH BUFPOLICY_SWITCH}. If the given option 304 * is {@link Option#bufresize bufresize}, the returned value is one 305 * of {@link Option#BUFRESIZE_AUTO BUFRESIZE_AUTO} or {@link 306 * Option#BUFRESIZE_MANUAL BUFRESIZE_MANUAL}. 307 * 308 * @see #setOption(String option) 309 * @see #unsetOption(String option) 310 * @see #setOption(String option, String value) 311 * @see Option 312 */ 313 public long getOption(String option) throws DTraceException; 314 315 /** 316 * Reports whether or not this consumer is open. 317 * 318 * @return {@code true} if and only if {@link #open(OpenFlag[] 319 * flags) open()} has been called on this consumer and {@link 320 * #close()} has not 321 */ 322 public boolean isOpen(); 323 324 /** 325 * Reports whether or not it is valid to call {@link #go()}. 326 * 327 * @return {@code true} if and only if at least one program has been 328 * compiled, all compiled programs have been enabled, {@code go()} 329 * has not already been called, and {@link #close()} has not been 330 * called 331 */ 332 public boolean isEnabled(); 333 334 /** 335 * Reports whether or not this consumer is running. There may be a 336 * delay after calling {@link #go()} before this consumer actually 337 * starts running (listeners are notified by the {@link 338 * ConsumerListener#consumerStarted(ConsumerEvent e) 339 * consumerStarted()} method). 340 * 341 * @return {@code true} if this consumer is running, {@code false} 342 * otherwise 343 */ 344 public boolean isRunning(); 345 346 /** 347 * Reports whether or not this consumer is closed. A closed 348 * consumer cannot be reopened. 349 * <p> 350 * Note that a closed consumer is different from a consumer that has 351 * not yet been opened. 352 * 353 * @return {@code true} if {@link #close()} has been called on this 354 * consumer, {@code false} otherwise 355 */ 356 public boolean isClosed(); 357 358 /** 359 * Begin tracing and start a background thread to consume generated 360 * probe data. 361 * 362 * @throws IllegalStateException if not {@link #isEnabled()} 363 * @throws DTraceException if an exception occurs in the native 364 * DTrace library 365 * @see #go(ExceptionHandler h) 366 * @see #open(OpenFlag[] flags) 367 * @see #compile(String program, String[] macroArgs) 368 * @see #compile(File program, String[] macroArgs) 369 * @see #enable() 370 * @see #stop() 371 * @see #close() 372 */ 373 public void go() throws DTraceException; 374 375 /** 376 * Begin tracing and start a background thread to consume generated 377 * probe data. Handle any exception thrown in the consumer thread 378 * with the given handler. 379 * 380 * @throws IllegalStateException if not {@link #isEnabled()} 381 * @throws DTraceException if an exception occurs in the native 382 * DTrace library 383 * @see #go() 384 */ 385 public void go(ExceptionHandler h) throws DTraceException; 386 387 /** 388 * Stops all tracing, as well as the background thread started by 389 * {@link #go()} to consume generated probe data. A stopped 390 * consumer cannot be restarted. It is necessary to {@code close()} 391 * a stopped consumer to release the system resources it holds. 392 * <p> 393 * A consumer may stop on its own in response to the {@code exit()} 394 * action (see <b>{@code exit()}</b> in the <a 395 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhm?a=view> 396 * <b>Special Actions</b></a> section of the <b>Actions and 397 * Subroutines</b> chapter of the <i>Solaris Dynamic Tracing 398 * Guide</i>). Similarly, a consumer stops automatically if it has 399 * at least one target process and all its target processes have 400 * completed (see {@link #createProcess(String command) 401 * createProcess()} and {@link #grabProcess(int pid) 402 * grabProcess()}). A consumer also stops automatically if it 403 * encounters an exception while consuming probe data. In these 404 * cases it is not necessary to call {@code stop()}. If a consumer 405 * stops for any reason (an explicit call to {@code stop()} or any 406 * of the reasons just given), listeners are notified through the 407 * {@link ConsumerListener#consumerStopped(ConsumerEvent e) 408 * consumerStopped()} method. 409 * <p> 410 * Note that a call to {@code stop()} blocks until the background 411 * thread started by {@code go()} actually stops. After {@code 412 * stop()} returns, a call to {@link #isRunning()} returns {@code 413 * false}. If a {@code DTraceException} is thrown while stopping 414 * this consumer, it is handled by the handler passed to {@link 415 * #go(ExceptionHandler h)} (or a default handler if none is 416 * specified). 417 * 418 * @throws IllegalStateException if called before {@link #go()} or 419 * if {@code stop()} was already called 420 * @see #go() 421 * @see #close() 422 */ 423 public void stop(); 424 425 /** 426 * Closes an open consumer and releases the system resources it was 427 * holding. If the consumer is running, {@code close()} will {@link 428 * #stop()} it automatically. A closed consumer cannot be 429 * reopened. Closing a consumer that has not yet been opened makes 430 * it illegal to open that consumer afterwards. It is a no-op to 431 * call {@code close()} on a consumer that is already closed. 432 * 433 * @see #open(OpenFlag[] flags) 434 */ 435 public void close(); 436 437 /** 438 * Adds a listener for probe data generated by this consumer. 439 */ 440 public void addConsumerListener(ConsumerListener l); 441 442 /** 443 * Removes a listener for probe data generated by this consumer. 444 */ 445 public void removeConsumerListener(ConsumerListener l); 446 447 /** 448 * Gets a snapshot of all aggregations except those that have 449 * already been captured in a {@link PrintaRecord}. Does not clear 450 * any aggregation. 451 * <p> 452 * Provides a programmatic alternative to the {@code printa(}) 453 * action (see <a 454 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 455 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 456 * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 457 * 458 * @throws IllegalStateException if called before {@link #go()} or 459 * after {@link #close()} 460 * @throws DTraceException if an exception occurs in the native 461 * DTrace library 462 * @see #getAggregate(Set includedAggregationNames, Set 463 * clearedAggregationNames) 464 */ 465 public Aggregate getAggregate() throws DTraceException; 466 467 /** 468 * Gets a snapshot of all the specified aggregations except those 469 * that have already been captured in a {@link PrintaRecord}. Does 470 * not clear any aggregation. 471 * <p> 472 * Provides a programmatic alternative to the {@code printa(}) 473 * action (see <a 474 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 475 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 476 * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 477 * 478 * @param includedAggregationNames if {@code null}, all available 479 * aggregations are included; if non-null, only those aggregations 480 * specifically named by the given set are included 481 * @throws IllegalStateException if called before {@link #go()} or 482 * after {@link #close()} 483 * @throws DTraceException if an exception occurs in the native 484 * DTrace library 485 * @see #getAggregate(Set includedAggregationNames, Set 486 * clearedAggregationNames) 487 */ 488 public Aggregate getAggregate(Set <String> includedAggregationNames) 489 throws DTraceException; 490 491 /** 492 * Gets a snapshot of all the specified aggregations except those 493 * that have already been captured in a {@link PrintaRecord}, with 494 * the side effect of atomically clearing any subset of those 495 * aggregations. Clearing an aggregation resets all of its values 496 * to zero without removing any of its keys. Leave aggregations 497 * uncleared to get running totals, otherwise specify that an 498 * aggregation be cleared to get values per time interval. Note 499 * that once an aggregation is captured in a {@code PrintaRecord} 500 * (as a result of the {@code printa()} action), it is no longer 501 * available to the {@code getAggregate()} method. 502 * <p> 503 * Provides a programmatic alternative to the {@code printa(}) (see 504 * <a 505 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 506 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 507 * chapter of the <i>Solaris Dynamic Tracing Guide</i>) and {@code 508 * clear()} actions. 509 * 510 * @param includedAggregationNames if {@code null}, all available 511 * aggregations are included; if non-null, only those aggregations 512 * specifically named by the given set are included 513 * @param clearedAggregationNames if {@code null}, all available 514 * aggregations are cleared; if non-null, only those aggregations 515 * specifically named by the given set are cleared 516 * @throws IllegalStateException if called before {@link #go()} or 517 * after {@link #close()} 518 * @throws DTraceException if an exception occurs in the native 519 * DTrace library 520 */ 521 public Aggregate getAggregate(Set <String> includedAggregationNames, 522 Set <String> clearedAggregationNames) throws DTraceException; 523 524 /** 525 * Creates a process by executing the given command on the system 526 * and returns the created process ID. The created process is 527 * suspended until calling {@link #go()} so that the process waits 528 * to do anything until this consumer has started tracing (allowing 529 * a process to be traced from the very beginning of its execution). 530 * The macro variable {@code $target} in a D program will be 531 * replaced by the process ID of the created process. When the 532 * created process exits, this consumer notifies listeners through 533 * the {@link ConsumerListener#processStateChanged(ProcessEvent e) 534 * processStateChanged()} method. 535 * <p> 536 * See the <a 537 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view> 538 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 539 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 540 * 541 * @param command a string whose first token is assumed to be the 542 * name of the command and whose subsequent tokens are the arguments 543 * to that command. 544 * @return ID of the created process (pid) 545 * @throws NullPointerException if the given command is {@code nul}l 546 * @throws IllegalArgumentException if the given command is empty or 547 * contains only whitespace 548 * @throws IllegalStateException if called before {@link 549 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 550 * or if the consumer is closed 551 * @throws DTraceException if the process cannot be created 552 * @see #grabProcess(int pid) 553 */ 554 public int createProcess(String command) throws DTraceException; 555 556 /** 557 * Grabs the specified process and caches its symbol tables. The 558 * macro variable {@code $target} in a D program will be replaced by 559 * the process ID of the grabbed process. When the specified 560 * process exits, this consumer notifies listeners through the 561 * {@link ConsumerListener#processStateChanged(ProcessEvent e) 562 * processStateChanged()} method. 563 * <p> 564 * See the <a 565 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view> 566 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 567 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 568 * 569 * @param pid process ID of the process to be grabbed 570 * @throws IllegalStateException if called before {@link 571 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 572 * or if the consumer is closed 573 * @throws DTraceException if the process cannot be grabbed 574 * @see #createProcess(String command) 575 */ 576 public void grabProcess(int pid) throws DTraceException; 577 578 /** 579 * Lists probes that match the given probe description. See {@link 580 * ProbeDescription} for information about pattern syntax and 581 * wildcarding. 582 * 583 * @param filter use {@link ProbeDescription#EMPTY} to get all 584 * probes, otherwise get only those probes that match the given 585 * filter 586 * @return a non-null list of probe descriptions 587 * @throws IllegalStateException if called before {@link 588 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 589 * or if the consumer is closed 590 * @throws DTraceException if an exception occurs in the native 591 * DTrace library 592 * @see #open(OpenFlag[] flags) 593 * @see #close() 594 * @see #listProbeDetail(ProbeDescription filter) 595 * @see #listProgramProbes(Program program) 596 */ 597 public List <ProbeDescription> listProbes(ProbeDescription filter) 598 throws DTraceException; 599 600 /** 601 * Lists probes that match the given probe description and includes 602 * detail such as stability information about each listed probe. 603 * 604 * @param filter use {@link ProbeDescription#EMPTY} to get all 605 * probes, otherwise get only those probes that match the given 606 * filter 607 * @return a non-null list of probe detail 608 * @throws IllegalStateException if called before {@link 609 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 610 * or if the consumer is closed 611 * @throws DTraceException if an exception occurs in the native 612 * DTrace library 613 * @see #listProbes(ProbeDescription filter) 614 * @see #listProgramProbeDetail(Program program) 615 */ 616 public List <Probe> listProbeDetail(ProbeDescription filter) 617 throws DTraceException; 618 619 /** 620 * Lists probes that match the given compiled program. A probe 621 * matches a D program if that program contains any matching probe 622 * description. 623 * 624 * @param program a {@code Program} identifier returned by {@link 625 * #compile(String program, String[] macroArgs) compile(String 626 * program, ...)} or {@link #compile(File program, String[] 627 * macroArgs) compile(File program, ...)} 628 * @return a non-null list of probe descriptions 629 * @throws NullPointerException if the given program identifier is 630 * {@code null} 631 * @throws IllegalArgumentException if the specified program was not 632 * compiled by this consumer 633 * @throws IllegalStateException if called before {@link 634 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 635 * or if the consumer is closed 636 * @throws DTraceException if an exception occurs in the native 637 * DTrace library 638 * @see #listProbes(ProbeDescription filter) 639 */ 640 public List <ProbeDescription> listProgramProbes(Program program) 641 throws DTraceException; 642 643 /** 644 * Lists probes that match the given compiled program and includes 645 * detail such as stability information about each listed probe. 646 * 647 * @param program a {@code Program} identifier returned by {@link 648 * #compile(String program, String[] macroArgs) compile(String 649 * program, ...)} or {@link #compile(File program, String[] 650 * macroArgs) compile(File program, ...)} 651 * @return a non-null list of probe detail 652 * @throws NullPointerException if the given program identifier is 653 * {@code null} 654 * @throws IllegalArgumentException if the specified program was not 655 * compiled by this consumer 656 * @throws IllegalStateException if called before {@link 657 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 658 * or if the consumer is closed 659 * @throws DTraceException if an exception occurs in the native 660 * DTrace library 661 * @see #listProgramProbes(Program program) 662 * @see #listProbeDetail(ProbeDescription filter) 663 */ 664 public List <Probe> listProgramProbeDetail(Program program) 665 throws DTraceException; 666 667 /** 668 * Gets the kernel function name for the given 32-bit kernel 669 * address. 670 * 671 * @param address 32-bit kernel function address, such as the value 672 * of a {@link Tuple} member in an {@link AggregationRecord} to be 673 * converted for display 674 * @return the result of kernel function lookup as one of the 675 * following:<ul><li>{@code module`function}</li> 676 * <li>{@code module`function+offset}</li> 677 * <li>{@code module`address}</li> 678 * <li>{@code address}</li></ul> where {@code module} and {@code 679 * function} are names, and {@code offset} and {@code address} are 680 * integers in hexadecimal format preceded by "{@code 0x}". {@code 681 * offset} is the number of bytes from the beginning of the 682 * function, included when non-zero. {@code address} is simply the 683 * hex form of the input paramater, returned when function lookup 684 * fails. The exact details of this format are subject to change. 685 * @throws IllegalStateException if called before {@link #go()} or 686 * after {@link #close()} 687 * @see #lookupKernelFunction(long address) 688 */ 689 public String lookupKernelFunction(int address); 690 691 /** 692 * Gets the kernel function name for the given 64-bit kernel 693 * address. 694 * 695 * @param address 64-bit kernel function address 696 * @return kernel function name 697 * @throws IllegalStateException if called before {@link #go()} or 698 * after {@link #close()} 699 * @see #lookupKernelFunction(int address) 700 */ 701 public String lookupKernelFunction(long address); 702 703 /** 704 * Gets the user function name for the given 32-bit user address and 705 * process ID. 706 * 707 * @param pid ID of the user process containing the addressed 708 * function 709 * @param address 32-bit user function address, such as the value 710 * of a {@link Tuple} member in an {@link AggregationRecord} to be 711 * converted for display. 712 * @return result of user function lookup as one of the 713 * following:<ul> <li>{@code module`function}</li> 714 * <li>{@code module`function+offset}</li> 715 * <li>{@code module`address}</li> 716 * <li>{@code address}</li></ul> where {@code module} and {@code 717 * function} are names, and {@code offset} and {@code address} are 718 * integers in hexadecimal format preceded by "{@code 0x}". {@code 719 * offset} is the number of bytes from the beginning of the 720 * function, included when non-zero. {@code address} is simply the 721 * hex form of the input paramater, returned when function lookup 722 * fails. The exact details of this format are subject to change. 723 * @throws IllegalStateException if called before {@link #go()} or 724 * after {@link #close()} 725 * @see #lookupUserFunction(int pid, long address) 726 */ 727 public String lookupUserFunction(int pid, int address); 728 729 /** 730 * Gets the user function name for the given 64-bit user address and 731 * process ID. 732 * 733 * @param pid ID of the user process containing the addressed 734 * function 735 * @param address 64-bit user function address 736 * @return user function name 737 * @throws IllegalStateException if called before {@link #go()} or 738 * after {@link #close()} 739 * @see #lookupUserFunction(int pid, int address) 740 */ 741 public String lookupUserFunction(int pid, long address); 742 743 /** 744 * Gets the version of the native DTrace library. 745 * 746 * @return version string generated by the native DTrace library 747 * (same as the output of {@code dtrace(1M)} with the {@code -V} 748 * option) 749 */ 750 public String getVersion(); 751 } 752