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 */ open(OpenFlag .... flags)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 */ compile(String program, String ... macroArgs)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 */ compile(File program, String ... macroArgs)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 */ enable()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 */ enable(Program program)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 */ getProgramInfo(Program program)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 */ setOption(String option)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 */ unsetOption(String option)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 */ setOption(String option, String value)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 */ getOption(String option)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 */ isOpen()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 */ isEnabled()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 */ isRunning()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 */ isClosed()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 */ go()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 */ go(ExceptionHandler h)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 #abort() 422 * @see #close() 423 */ stop()424 public void stop(); 425 426 /** 427 * Aborts the background thread started by {@link #go()}. {@code 428 * abort()} is effectively the same as {@link #stop()} except that 429 * it does not block (i.e. it does not wait until the background 430 * thread actually stops). {@link #isRunning()} is likely {@code 431 * true} immediately after a call to {@code abort()}, since an 432 * aborted consumer stops at a time specified as later. 433 * Specifically, a call to {@code abort()} stops tracing just before 434 * the next {@link ConsumerListener#intervalBegan(ConsumerEvent e) 435 * intervalBegan()} event and stops consuming probe data by the 436 * subsequent {@link ConsumerListener#intervalEnded(ConsumerEvent e) 437 * intervalEnded()} event. When the aborted consumer actually 438 * stops, listeners are notified in the {@link 439 * ConsumerListener#consumerStopped(ConsumerEvent e) 440 * consumerStopped()} method, where it is convenient to {@link 441 * #close()} the stopped consumer after requesting the final 442 * aggregate. 443 * <p> 444 * The {@code abort()} and {@code stop()} methods have slightly 445 * different behavior when called <i>just after</i> {@code go()} but 446 * <i>before</i> the consumer actually starts running: It is 447 * possible to {@code stop()} a consumer before it starts running 448 * (resulting in a {@code consumerStopped()} event without a 449 * matching {@code consumerStarted()} event), whereas an aborted 450 * consumer will not stop until after it starts running, when it 451 * completes a single interval (that interval does not include 452 * sleeping to wait for traced probe data). Calling {@code abort()} 453 * before {@code go()} is legal and has the same effect as calling 454 * it after {@code go()} and before the consumer starts running. 455 * The last behavior follows from the design: You do not know the 456 * state of a consumer after calling {@code abort()}, nor is it 457 * necessary to know the state of a consumer before calling {@code 458 * abort()}. That may be preferable, for example, when you want to 459 * abort a consumer opened and started in another thread. 460 * 461 * @see #stop() 462 */ abort()463 public void abort(); 464 465 /** 466 * Closes an open consumer and releases the system resources it was 467 * holding. If the consumer is running, {@code close()} will {@link 468 * #stop()} it automatically. A closed consumer cannot be 469 * reopened. Closing a consumer that has not yet been opened makes 470 * it illegal to open that consumer afterwards. It is a no-op to 471 * call {@code close()} on a consumer that is already closed. 472 * 473 * @see #open(OpenFlag[] flags) 474 */ close()475 public void close(); 476 477 /** 478 * Adds a listener for probe data generated by this consumer. 479 */ addConsumerListener(ConsumerListener l)480 public void addConsumerListener(ConsumerListener l); 481 482 /** 483 * Removes a listener for probe data generated by this consumer. 484 */ removeConsumerListener(ConsumerListener l)485 public void removeConsumerListener(ConsumerListener l); 486 487 /** 488 * Gets a snapshot of all aggregations except those that have 489 * already been captured in a {@link PrintaRecord}. Does not clear 490 * any aggregation. 491 * <p> 492 * Provides a programmatic alternative to the {@code printa(}) 493 * action (see <a 494 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 495 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 496 * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 497 * 498 * @throws IllegalStateException if called before {@link #go()} or 499 * after {@link #close()} 500 * @throws DTraceException if an exception occurs in the native 501 * DTrace library 502 * @see #getAggregate(Set includedAggregationNames, Set 503 * clearedAggregationNames) 504 */ getAggregate()505 public Aggregate getAggregate() throws DTraceException; 506 507 /** 508 * Gets a snapshot of all the specified aggregations except those 509 * that have already been captured in a {@link PrintaRecord}. Does 510 * not clear any aggregation. 511 * <p> 512 * Provides a programmatic alternative to the {@code printa(}) 513 * action (see <a 514 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 515 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 516 * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 517 * 518 * @param includedAggregationNames if {@code null}, all available 519 * aggregations are included; if non-null, only those aggregations 520 * specifically named by the given set are included 521 * @throws IllegalStateException if called before {@link #go()} or 522 * after {@link #close()} 523 * @throws DTraceException if an exception occurs in the native 524 * DTrace library 525 * @see #getAggregate(Set includedAggregationNames, Set 526 * clearedAggregationNames) 527 */ getAggregate(Set <String> includedAggregationNames)528 public Aggregate getAggregate(Set <String> includedAggregationNames) 529 throws DTraceException; 530 531 /** 532 * Gets a snapshot of all the specified aggregations except those 533 * that have already been captured in a {@link PrintaRecord}, with 534 * the side effect of atomically clearing any subset of those 535 * aggregations. Clearing an aggregation resets all of its values 536 * to zero without removing any of its keys. Leave aggregations 537 * uncleared to get running totals, otherwise specify that an 538 * aggregation be cleared to get values per time interval. Note 539 * that once an aggregation is captured in a {@code PrintaRecord} 540 * (as a result of the {@code printa()} action), it is no longer 541 * available to the {@code getAggregate()} method. 542 * <p> 543 * Provides a programmatic alternative to the {@code printa(}) (see 544 * <a 545 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhv?a=view> 546 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 547 * chapter of the <i>Solaris Dynamic Tracing Guide</i>) and {@code 548 * clear()} actions. 549 * 550 * @param includedAggregationNames if {@code null}, all available 551 * aggregations are included; if non-null, only those aggregations 552 * specifically named by the given set are included 553 * @param clearedAggregationNames if {@code null}, all available 554 * aggregations are cleared; if non-null, only those aggregations 555 * specifically named by the given set are cleared 556 * @throws IllegalStateException if called before {@link #go()} or 557 * after {@link #close()} 558 * @throws DTraceException if an exception occurs in the native 559 * DTrace library 560 */ getAggregate(Set <String> includedAggregationNames, Set <String> clearedAggregationNames)561 public Aggregate getAggregate(Set <String> includedAggregationNames, 562 Set <String> clearedAggregationNames) throws DTraceException; 563 564 /** 565 * Creates a process by executing the given command on the system 566 * and returns the created process ID. The created process is 567 * suspended until calling {@link #go()} so that the process waits 568 * to do anything until this consumer has started tracing (allowing 569 * a process to be traced from the very beginning of its execution). 570 * The macro variable {@code $target} in a D program will be 571 * replaced by the process ID of the created process. When the 572 * created process exits, this consumer notifies listeners through 573 * the {@link ConsumerListener#processStateChanged(ProcessEvent e) 574 * processStateChanged()} method. 575 * <p> 576 * See the <a 577 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view> 578 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 579 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 580 * 581 * @param command a string whose first token is assumed to be the 582 * name of the command and whose subsequent tokens are the arguments 583 * to that command. 584 * @return ID of the created process (pid) 585 * @throws NullPointerException if the given command is {@code nul}l 586 * @throws IllegalArgumentException if the given command is empty or 587 * contains only whitespace 588 * @throws IllegalStateException if called before {@link 589 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 590 * or if the consumer is closed 591 * @throws DTraceException if the process cannot be created 592 * @see #grabProcess(int pid) 593 */ createProcess(String command)594 public int createProcess(String command) throws DTraceException; 595 596 /** 597 * Grabs the specified process and caches its symbol tables. The 598 * macro variable {@code $target} in a D program will be replaced by 599 * the process ID of the grabbed process. When the specified 600 * process exits, this consumer notifies listeners through the 601 * {@link ConsumerListener#processStateChanged(ProcessEvent e) 602 * processStateChanged()} method. 603 * <p> 604 * See the <a 605 * href=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view> 606 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 607 * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 608 * 609 * @param pid process ID of the process to be grabbed 610 * @throws IllegalStateException if called before {@link 611 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 612 * or if the consumer is closed 613 * @throws DTraceException if the process cannot be grabbed 614 * @see #createProcess(String command) 615 */ grabProcess(int pid)616 public void grabProcess(int pid) throws DTraceException; 617 618 /** 619 * Lists probes that match the given probe description. See {@link 620 * ProbeDescription} for information about pattern syntax and 621 * wildcarding. 622 * 623 * @param filter use {@link ProbeDescription#EMPTY} to get all 624 * probes, otherwise get only those probes that match the given 625 * filter 626 * @return a non-null list of probe descriptions 627 * @throws IllegalStateException if called before {@link 628 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 629 * or if the consumer is closed 630 * @throws DTraceException if an exception occurs in the native 631 * DTrace library 632 * @see #open(OpenFlag[] flags) 633 * @see #close() 634 * @see #listProbeDetail(ProbeDescription filter) 635 * @see #listProgramProbes(Program program) 636 */ listProbes(ProbeDescription filter)637 public List <ProbeDescription> listProbes(ProbeDescription filter) 638 throws DTraceException; 639 640 /** 641 * Lists probes that match the given probe description and includes 642 * detail such as stability information about each listed probe. 643 * 644 * @param filter use {@link ProbeDescription#EMPTY} to get all 645 * probes, otherwise get only those probes that match the given 646 * filter 647 * @return a non-null list of probe detail 648 * @throws IllegalStateException if called before {@link 649 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 650 * or if the consumer is closed 651 * @throws DTraceException if an exception occurs in the native 652 * DTrace library 653 * @see #listProbes(ProbeDescription filter) 654 * @see #listProgramProbeDetail(Program program) 655 */ listProbeDetail(ProbeDescription filter)656 public List <Probe> listProbeDetail(ProbeDescription filter) 657 throws DTraceException; 658 659 /** 660 * Lists probes that match the given compiled program. A probe 661 * matches a D program if that program contains any matching probe 662 * description. 663 * 664 * @param program a {@code Program} identifier returned by {@link 665 * #compile(String program, String[] macroArgs) compile(String 666 * program, ...)} or {@link #compile(File program, String[] 667 * macroArgs) compile(File program, ...)} 668 * @return a non-null list of probe descriptions 669 * @throws NullPointerException if the given program identifier is 670 * {@code null} 671 * @throws IllegalArgumentException if the specified program was not 672 * compiled by this consumer 673 * @throws IllegalStateException if called before {@link 674 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 675 * or if the consumer is closed 676 * @throws DTraceException if an exception occurs in the native 677 * DTrace library 678 * @see #listProbes(ProbeDescription filter) 679 */ listProgramProbes(Program program)680 public List <ProbeDescription> listProgramProbes(Program program) 681 throws DTraceException; 682 683 /** 684 * Lists probes that match the given compiled program and includes 685 * detail such as stability information about each listed probe. 686 * 687 * @param program a {@code Program} identifier returned by {@link 688 * #compile(String program, String[] macroArgs) compile(String 689 * program, ...)} or {@link #compile(File program, String[] 690 * macroArgs) compile(File program, ...)} 691 * @return a non-null list of probe detail 692 * @throws NullPointerException if the given program identifier is 693 * {@code null} 694 * @throws IllegalArgumentException if the specified program was not 695 * compiled by this consumer 696 * @throws IllegalStateException if called before {@link 697 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 698 * or if the consumer is closed 699 * @throws DTraceException if an exception occurs in the native 700 * DTrace library 701 * @see #listProgramProbes(Program program) 702 * @see #listProbeDetail(ProbeDescription filter) 703 */ listProgramProbeDetail(Program program)704 public List <Probe> listProgramProbeDetail(Program program) 705 throws DTraceException; 706 707 /** 708 * Gets the kernel function name for the given 32-bit kernel 709 * address. 710 * 711 * @param address 32-bit kernel function address, such as the value 712 * of a {@link Tuple} member in an {@link AggregationRecord} to be 713 * converted for display 714 * @return the result of kernel function lookup as one of the 715 * following:<ul><li>{@code module`function}</li> 716 * <li>{@code module`function+offset}</li> 717 * <li>{@code module`address}</li> 718 * <li>{@code address}</li></ul> where {@code module} and {@code 719 * function} are names, and {@code offset} and {@code address} are 720 * integers in hexadecimal format preceded by "{@code 0x}". {@code 721 * offset} is the number of bytes from the beginning of the 722 * function, included when non-zero. {@code address} is simply the 723 * hex form of the input paramater, returned when function lookup 724 * fails. The exact details of this format are subject to change. 725 * @throws IllegalStateException if called before {@link #go()} or 726 * after {@link #close()} 727 * @see #lookupKernelFunction(long address) 728 */ lookupKernelFunction(int address)729 public String lookupKernelFunction(int address); 730 731 /** 732 * Gets the kernel function name for the given 64-bit kernel 733 * address. 734 * 735 * @param address 64-bit kernel function address 736 * @return kernel function name 737 * @throws IllegalStateException if called before {@link #go()} or 738 * after {@link #close()} 739 * @see #lookupKernelFunction(int address) 740 */ lookupKernelFunction(long address)741 public String lookupKernelFunction(long address); 742 743 /** 744 * Gets the user function name for the given 32-bit user address and 745 * process ID. 746 * 747 * @param pid ID of the user process containing the addressed 748 * function 749 * @param address 32-bit user function address, such as the value 750 * of a {@link Tuple} member in an {@link AggregationRecord} to be 751 * converted for display. 752 * @return result of user function lookup as one of the 753 * following:<ul> <li>{@code module`function}</li> 754 * <li>{@code module`function+offset}</li> 755 * <li>{@code module`address}</li> 756 * <li>{@code address}</li></ul> where {@code module} and {@code 757 * function} are names, and {@code offset} and {@code address} are 758 * integers in hexadecimal format preceded by "{@code 0x}". {@code 759 * offset} is the number of bytes from the beginning of the 760 * function, included when non-zero. {@code address} is simply the 761 * hex form of the input paramater, returned when function lookup 762 * fails. The exact details of this format are subject to change. 763 * @throws IllegalStateException if called before {@link #go()} or 764 * after {@link #close()} 765 * @see #lookupUserFunction(int pid, long address) 766 */ lookupUserFunction(int pid, int address)767 public String lookupUserFunction(int pid, int address); 768 769 /** 770 * Gets the user function name for the given 64-bit user address and 771 * process ID. 772 * 773 * @param pid ID of the user process containing the addressed 774 * function 775 * @param address 64-bit user function address 776 * @return user function name 777 * @throws IllegalStateException if called before {@link #go()} or 778 * after {@link #close()} 779 * @see #lookupUserFunction(int pid, int address) 780 */ lookupUserFunction(int pid, long address)781 public String lookupUserFunction(int pid, long address); 782 783 /** 784 * Gets the version of the native DTrace library. 785 * 786 * @return version string generated by the native DTrace library 787 * (same as the output of {@code dtrace(1M)} with the {@code -V} 788 * option) 789 */ getVersion()790 public String getVersion(); 791 } 792