2N/A * The contents of this file are subject to the terms of the 2N/A * Common Development and Distribution License (the "License"). 2N/A * You may not use this file except in compliance with the License. 2N/A * See the License for the specific language governing permissions 2N/A * and limitations under the License. 2N/A * When distributing Covered Code, include this CDDL HEADER in each 2N/A * If applicable, add the following below this CDDL HEADER, with the 2N/A * fields enclosed by brackets "[]" replaced with your own identifying 2N/A * information: Portions Copyright [yyyy] [name of copyright owner] 2N/A * Copyright (c) 2006, 2011, Oracle and/or its affiliates. All rights reserved. 2N/A * Interface to the native DTrace library, each instance is a single 2N/A * DTrace consumer. To consume the output of DTrace program actions, 2N/A * {@link #addConsumerListener(ConsumerListener l) register a probe data 2N/A * listener}. To get a snapshot of all aggregations in a D program on 2N/A * your own programmatic interval without relying on DTrace actions to 2N/A * generate that output, use the {@link #getAggregate()} method. 2N/A * @author Tom Erickson 2N/A * Optional flags passed to {@link #open(Consumer.OpenFlag[] flags) 2N/A * Generate 32-bit D programs. {@code ILP32} and {@link 2N/A * Consumer.OpenFlag#LP64 LP64} are mutually exclusive. 2N/A * Generate 64-bit D programs. {@code LP64} and {@link 2N/A * Consumer.OpenFlag#ILP32 ILP32} are mutually exclusive. 2N/A * Opens this DTrace consumer. Optional flags indicate behaviors 2N/A * that can only be set at the time of opening. Most optional 2N/A * behaviors are set using {@link #setOption(String option, String 2N/A * value) setOption()} after opening the consumer. In the great 2N/A * majority of cases, the consumer is opened without specifying any 2N/A * <pre> {@code consumer.open();}</pre> 2N/A * Subsequent calls to set options, compile DTrace programs, enable 2N/A * probes, and run this consumer may be made from any thread. 2N/A * @throws NullPointerException if any of the given open flags is 2N/A * @throws IllegalArgumentException if any of the given flags are 2N/A * @throws IllegalStateException if this consumer is closed or has 2N/A * already been opened 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #compile(File program, String[] macroArgs) 2N/A * @see #compile(String program, String[] macroArgs) 2N/A * Compiles the given D program string. Optional macro arguments 2N/A * replace corresponding numbered macro variables in the D program 2N/A * starting at {@code $1}. 2N/A * @param program program string 2N/A * @param macroArgs macro substitutions for <i>$n</i> placeholders 2N/A * embedded in the given D program: {@code macroArgs[0]} replaces 2N/A * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 2N/A * occurrences of {@code $2}, and so on. {@code $0} is 2N/A * automatically replaced by the executable name and should not be 2N/A * included in the {@code macroArgs} parameter. See the <a 2N/A * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 2N/A * @return a non-null {@code Program} identifier that may be passed 2N/A * to {@link #enable(Program program) enable()} 2N/A * @throws NullPointerException if the given program string or any 2N/A * of the given macro arguments is {@code null} 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 2N/A * consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #compile(File program, String[] macroArgs) 2N/A * Compiles the given D program file. Optional macro arguments 2N/A * replace corresponding numbered macro variables in the D program 2N/A * starting at {@code $1}. 2N/A * @param program program file 2N/A * @param macroArgs macro substitutions for <i>$n</i> placeholders 2N/A * embedded in the given D program: {@code macroArgs[0]} replaces 2N/A * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 2N/A * occurrences of {@code $2}, and so on. {@code $0} is 2N/A * automatically set to the name of the given file and should not be 2N/A * included in the {@code macroArgs} parameter. See the <a 2N/A * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 2N/A * @return a non-null {@code Program} identifier that may be passed 2N/A * to {@link #enable(Program program) enable()} 2N/A * @throws NullPointerException if the given program file or any of 2N/A * the given macro arguments is {@code null} 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 2N/A * consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @throws FileNotFoundException if the given program file cannot be 2N/A * @throws IOException if an I/O error occurs while reading the 2N/A * contents of the given program file 2N/A * @throws SecurityException if a security manager exists and its 2N/A * {@code checkRead()} method denies read access to the file 2N/A * @see #compile(String program, String[] macroArgs) 2N/A * Enables all DTrace probes compiled by this consumer. Call {@code 2N/A * enable()} with no argument to enable everything this consumer has 2N/A * compiled so far (most commonly a single program, the only one to 2N/A * be compiled). Call with one {@link Program} at a time if you 2N/A * need information about enabled probes specific to each program. 2N/A * @throws IllegalStateException if called before compiling at least 2N/A * one program, or if any compiled program is already enabled, or if 2N/A * {@link #go()} was already called, or if this consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #enable(Program program) 2N/A * Enables DTrace probes matching the given program and attaches 2N/A * information about those probes to the given program. A probe 2N/A * matched multiple times (within the same D program or in multiple 2N/A * D programs) triggers the actions associated with each matching 2N/A * occurrence every time that probe fires. 2N/A * @param program A {@code Program} identifier returned by {@link 2N/A * #compile(String program, String[] macroArgs) compile(String 2N/A * program, ...)} or {@link #compile(File program, String[] 2N/A * macroArgs) compile(File program, ...)}: If the given program is 2N/A * {@code null}, the call has the same behavior as {@link #enable()} 2N/A * with no argument; if the given program is non-null, the call 2N/A * enables only those probes matching that program. In the latter 2N/A * case, the {@code Program} parameter is modified as a way of 2N/A * passing back information about the given program and its matching 2N/A * probes, including program stability. 2N/A * @throws IllegalArgumentException if the given program is non-null 2N/A * and not compiled by this {@code Consumer} 2N/A * @throws IllegalStateException if the given program is already 2N/A * enabled (or if the given program is {@code null} and <i>any</i> 2N/A * program is already enabled), or if {@link #go()} was already 2N/A * called, or if this consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #compile(String program, String[] macroArgs) 2N/A * @see #compile(File program, String[] macroArgs) 2N/A * @see #getProgramInfo(Program program) 2N/A * Attaches information about matching DTrace probes to the given 2N/A * program. Attaches the same information to the given program as 2N/A * that attached by {@link #enable(Program program)} but without 2N/A * enabling the probes. 2N/A * @throws NullPointerException if the given program is {@code null} 2N/A * @throws IllegalArgumentException if the given program was not 2N/A * compiled by this {@code Consumer} 2N/A * @throws IllegalStateException if called after {@link #close()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #compile(String program, String[] macroArgs) 2N/A * @see #compile(File program, String[] macroArgs) 2N/A * @see #enable(Program program) 2N/A * Sets a boolean option. 2N/A * @throws NullPointerException if the given option is {@code null} 2N/A * @throws DTraceException if a value is expected for the given 2N/A * option, or if the option is otherwise invalid 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 2N/A * the given option is a boolean compile-time option and {@link 2N/A * #go()} has already been called (see {@link Option} for a 2N/A * breakdown of runtime and compile-time options) 2N/A * @see #setOption(String option, String value) 2N/A * @see #unsetOption(String option) 2N/A * Unsets a boolean option. 2N/A * @throws NullPointerException if the given option is {@code null} 2N/A * @throws DTraceException if the given option is not a boolean 2N/A * option, or if the option is otherwise invalid 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 2N/A * the given option is a boolean compile-time option and {@link 2N/A * #go()} has already been called (see {@link Option} for a 2N/A * breakdown of runtime and compile-time options) 2N/A * @see #setOption(String option) 2N/A * Sets the value of a DTrace option. If the given option affects 2N/A * compile-time behavior, it must be set before calling {@link 2N/A * #compile(String program, String[] macroArgs) compile(String 2N/A * program, ...)} or {@link #compile(File program, String[] 2N/A * macroArgs) compile(File program, ...)} in order to have an effect 2N/A * on compilation. Some runtime options including {@link 2N/A * Option#switchrate switchrate} and {@link Option#aggrate aggrate} 2N/A * are settable while a consumer is running; others must be set 2N/A * before calling {@link #go()}. See the <a 2N/A * <b>Options and Tunables</b></a> chapter of the <i>Solaris Dynamic 2N/A * Guide</i> for information about specific options. 2N/A * @throws NullPointerException if the given option or value is 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 2N/A * the given option is a boolean compile-time option and {@code 2N/A * go()} has already been called (see {@link Option} for a breakdown 2N/A * of runtime and compile-time options) 2N/A * @throws DTraceException for any of the following: 2N/A * <ul><li>The option is invalid</li> 2N/A * <li>The value is invalid for the given option</li> 2N/A * <li>{@code go()} has been called to start this consumer, and the 2N/A * option is not settable on a running consumer (some runtime 2N/A * options, including {@link Option#switchrate switchrate} and 2N/A * {@link Option#aggrate aggrate} are settable while the consumer is 2N/A * running)</li></ul> 2N/A * @see #open(OpenFlag[] flags) 2N/A * @see #getOption(String option) 2N/A * Gets the value of a DTrace option. 2N/A * @throws NullPointerException if the given option is {@code null} 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(OpenFlag[] flags) open()} or after {@link #close()} 2N/A * @throws DTraceException if the given option is invalid 2N/A * @return the value of the given DTrace option: If the given option 2N/A * is a boolean option and is currently unset, the returned value is 2N/A * {@link Option#UNSET}. If the given option is a <i>size</i> 2N/A * option, the returned value is in bytes. If the given option is a 2N/A * <i>time</i> option, the returned value is in nanoseconds. If the 2N/A * given option is {@link Option#bufpolicy bufpolicy}, the returned 2N/A * value is one of {@link Option#BUFPOLICY_RING BUFPOLICY_RING}, 2N/A * {@link Option#BUFPOLICY_FILL BUFPOLICY_FILL}, or {@link 2N/A * Option#BUFPOLICY_SWITCH BUFPOLICY_SWITCH}. If the given option 2N/A * is {@link Option#bufresize bufresize}, the returned value is one 2N/A * of {@link Option#BUFRESIZE_AUTO BUFRESIZE_AUTO} or {@link 2N/A * Option#BUFRESIZE_MANUAL BUFRESIZE_MANUAL}. 2N/A * @see #setOption(String option) 2N/A * @see #unsetOption(String option) 2N/A * @see #setOption(String option, String value) 2N/A * Reports whether or not this consumer is open. 2N/A * @return {@code true} if and only if {@link #open(OpenFlag[] 2N/A * flags) open()} has been called on this consumer and {@link 2N/A * Reports whether or not it is valid to call {@link #go()}. 2N/A * @return {@code true} if and only if at least one program has been 2N/A * compiled, all compiled programs have been enabled, {@code go()} 2N/A * has not already been called, and {@link #close()} has not been 2N/A * Reports whether or not this consumer is running. There may be a 2N/A * delay after calling {@link #go()} before this consumer actually 2N/A * starts running (listeners are notified by the {@link 2N/A * ConsumerListener#consumerStarted(ConsumerEvent e) 2N/A * consumerStarted()} method). 2N/A * @return {@code true} if this consumer is running, {@code false} 2N/A * Reports whether or not this consumer is closed. A closed 2N/A * consumer cannot be reopened. 2N/A * Note that a closed consumer is different from a consumer that has 2N/A * not yet been opened. 2N/A * @return {@code true} if {@link #close()} has been called on this 2N/A * consumer, {@code false} otherwise 2N/A * Begin tracing and start a background thread to consume generated 2N/A * @throws IllegalStateException if not {@link #isEnabled()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #go(ExceptionHandler h) 2N/A * @see #open(OpenFlag[] flags) 2N/A * @see #compile(String program, String[] macroArgs) 2N/A * @see #compile(File program, String[] macroArgs) 2N/A * Begin tracing and start a background thread to consume generated 2N/A * probe data. Handle any exception thrown in the consumer thread 2N/A * with the given handler. 2N/A * @throws IllegalStateException if not {@link #isEnabled()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * Stops all tracing, as well as the background thread started by 2N/A * {@link #go()} to consume generated probe data. A stopped 2N/A * consumer cannot be restarted. It is necessary to {@code close()} 2N/A * a stopped consumer to release the system resources it holds. 2N/A * A consumer may stop on its own in response to the {@code exit()} 2N/A * action (see <b>{@code exit()}</b> in the <a 2N/A * <b>Special Actions</b></a> section of the <b>Actions and 2N/A * Subroutines</b> chapter of the <i>Solaris Dynamic Tracing 2N/A * Guide</i>). Similarly, a consumer stops automatically if it has 2N/A * at least one target process and all its target processes have 2N/A * completed (see {@link #createProcess(String command) 2N/A * createProcess()} and {@link #grabProcess(int pid) 2N/A * grabProcess()}). A consumer also stops automatically if it 2N/A * encounters an exception while consuming probe data. In these 2N/A * cases it is not necessary to call {@code stop()}. If a consumer 2N/A * stops for any reason (an explicit call to {@code stop()} or any 2N/A * of the reasons just given), listeners are notified through the 2N/A * {@link ConsumerListener#consumerStopped(ConsumerEvent e) 2N/A * consumerStopped()} method. 2N/A * Note that a call to {@code stop()} blocks until the background 2N/A * thread started by {@code go()} actually stops. After {@code 2N/A * stop()} returns, a call to {@link #isRunning()} returns {@code 2N/A * false}. If a {@code DTraceException} is thrown while stopping 2N/A * this consumer, it is handled by the handler passed to {@link 2N/A * #go(ExceptionHandler h)} (or a default handler if none is 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * if {@code stop()} was already called 2N/A * Aborts the background thread started by {@link #go()}. {@code 2N/A * abort()} is effectively the same as {@link #stop()} except that 2N/A * it does not block (i.e. it does not wait until the background 2N/A * thread actually stops). {@link #isRunning()} is likely {@code 2N/A * true} immediately after a call to {@code abort()}, since an 2N/A * aborted consumer stops at a time specified as later. 2N/A * Specifically, a call to {@code abort()} stops tracing just before 2N/A * the next {@link ConsumerListener#intervalBegan(ConsumerEvent e) 2N/A * intervalBegan()} event and stops consuming probe data by the 2N/A * subsequent {@link ConsumerListener#intervalEnded(ConsumerEvent e) 2N/A * intervalEnded()} event. When the aborted consumer actually 2N/A * stops, listeners are notified in the {@link 2N/A * ConsumerListener#consumerStopped(ConsumerEvent e) 2N/A * consumerStopped()} method, where it is convenient to {@link 2N/A * #close()} the stopped consumer after requesting the final 2N/A * The {@code abort()} and {@code stop()} methods have slightly 2N/A * different behavior when called <i>just after</i> {@code go()} but 2N/A * <i>before</i> the consumer actually starts running: It is 2N/A * possible to {@code stop()} a consumer before it starts running 2N/A * (resulting in a {@code consumerStopped()} event without a 2N/A * matching {@code consumerStarted()} event), whereas an aborted 2N/A * consumer will not stop until after it starts running, when it 2N/A * completes a single interval (that interval does not include 2N/A * sleeping to wait for traced probe data). Calling {@code abort()} 2N/A * before {@code go()} is legal and has the same effect as calling 2N/A * it after {@code go()} and before the consumer starts running. 2N/A * The last behavior follows from the design: You do not know the 2N/A * state of a consumer after calling {@code abort()}, nor is it 2N/A * necessary to know the state of a consumer before calling {@code 2N/A * abort()}. That may be preferable, for example, when you want to 2N/A * abort a consumer opened and started in another thread. 2N/A * Closes an open consumer and releases the system resources it was 2N/A * holding. If the consumer is running, {@code close()} will {@link 2N/A * #stop()} it automatically. A closed consumer cannot be 2N/A * reopened. Closing a consumer that has not yet been opened makes 2N/A * it illegal to open that consumer afterwards. It is a no-op to 2N/A * call {@code close()} on a consumer that is already closed. 2N/A * @see #open(OpenFlag[] flags) 2N/A * Adds a listener for probe data generated by this consumer. 2N/A * Removes a listener for probe data generated by this consumer. 2N/A * Gets a snapshot of all aggregations except those that have 2N/A * already been captured in a {@link PrintaRecord}. Does not clear 2N/A * Provides a programmatic alternative to the {@code printa(}) 2N/A * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #getAggregate(Set includedAggregationNames, Set 2N/A * clearedAggregationNames) 2N/A * Gets a snapshot of all the specified aggregations except those 2N/A * that have already been captured in a {@link PrintaRecord}. Does 2N/A * not clear any aggregation. 2N/A * Provides a programmatic alternative to the {@code printa(}) 2N/A * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>). 2N/A * @param includedAggregationNames if {@code null}, all available 2N/A * aggregations are included; if non-null, only those aggregations 2N/A * specifically named by the given set are included 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #getAggregate(Set includedAggregationNames, Set 2N/A * clearedAggregationNames) 2N/A * Gets a snapshot of all the specified aggregations except those 2N/A * that have already been captured in a {@link PrintaRecord}, with 2N/A * the side effect of atomically clearing any subset of those 2N/A * aggregations. Clearing an aggregation resets all of its values 2N/A * to zero without removing any of its keys. Leave aggregations 2N/A * uncleared to get running totals, otherwise specify that an 2N/A * aggregation be cleared to get values per time interval. Note 2N/A * that once an aggregation is captured in a {@code PrintaRecord} 2N/A * (as a result of the {@code printa()} action), it is no longer 2N/A * available to the {@code getAggregate()} method. 2N/A * Provides a programmatic alternative to the {@code printa(}) (see 2N/A * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>) and {@code 2N/A * @param includedAggregationNames if {@code null}, all available 2N/A * aggregations are included; if non-null, only those aggregations 2N/A * specifically named by the given set are included 2N/A * @param clearedAggregationNames if {@code null}, all available 2N/A * aggregations are cleared; if non-null, only those aggregations 2N/A * specifically named by the given set are cleared 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * Creates a process by executing the given command on the system 2N/A * and returns the created process ID. The created process is 2N/A * suspended until calling {@link #go()} so that the process waits 2N/A * to do anything until this consumer has started tracing (allowing 2N/A * a process to be traced from the very beginning of its execution). 2N/A * The macro variable {@code $target} in a D program will be 2N/A * replaced by the process ID of the created process. When the 2N/A * created process exits, this consumer notifies listeners through 2N/A * the {@link ConsumerListener#processStateChanged(ProcessEvent e) 2N/A * processStateChanged()} method. 2N/A * <b>Target Process ID</b></a> section of the <b>Scripting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 2N/A * @param command a string whose first token is assumed to be the 2N/A * name of the command and whose subsequent tokens are the arguments 2N/A * @return ID of the created process (pid) 2N/A * @throws NullPointerException if the given command is {@code nul}l 2N/A * @throws IllegalArgumentException if the given command is empty or 2N/A * contains only whitespace 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if the process cannot be created 2N/A * @see #grabProcess(int pid) 2N/A * Grabs the specified process and caches its symbol tables. The 2N/A * macro variable {@code $target} in a D program will be replaced by 2N/A * the process ID of the grabbed process. When the specified 2N/A * process exits, this consumer notifies listeners through the 2N/A * {@link ConsumerListener#processStateChanged(ProcessEvent e) 2N/A * processStateChanged()} method. 2N/A * <b>Target Process ID</b></a> section of the <b>Scripting</b> 2N/A * chapter of the <i>Solaris Dynamic Tracing Guide</i>. 2N/A * @param pid process ID of the process to be grabbed 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if the process cannot be grabbed 2N/A * @see #createProcess(String command) 2N/A * Lists probes that match the given probe description. See {@link 2N/A * ProbeDescription} for information about pattern syntax and 2N/A * @param filter use {@link ProbeDescription#EMPTY} to get all 2N/A * probes, otherwise get only those probes that match the given 2N/A * @return a non-null list of probe descriptions 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #open(OpenFlag[] flags) 2N/A * @see #listProbeDetail(ProbeDescription filter) 2N/A * @see #listProgramProbes(Program program) 2N/A * Lists probes that match the given probe description and includes 2N/A * detail such as stability information about each listed probe. 2N/A * @param filter use {@link ProbeDescription#EMPTY} to get all 2N/A * probes, otherwise get only those probes that match the given 2N/A * @return a non-null list of probe detail 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #listProbes(ProbeDescription filter) 2N/A * @see #listProgramProbeDetail(Program program) 2N/A * Lists probes that match the given compiled program. A probe 2N/A * matches a D program if that program contains any matching probe 2N/A * @param program a {@code Program} identifier returned by {@link 2N/A * #compile(String program, String[] macroArgs) compile(String 2N/A * program, ...)} or {@link #compile(File program, String[] 2N/A * macroArgs) compile(File program, ...)} 2N/A * @return a non-null list of probe descriptions 2N/A * @throws NullPointerException if the given program identifier is 2N/A * @throws IllegalArgumentException if the specified program was not 2N/A * compiled by this consumer 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #listProbes(ProbeDescription filter) 2N/A * Lists probes that match the given compiled program and includes 2N/A * detail such as stability information about each listed probe. 2N/A * @param program a {@code Program} identifier returned by {@link 2N/A * #compile(String program, String[] macroArgs) compile(String 2N/A * program, ...)} or {@link #compile(File program, String[] 2N/A * macroArgs) compile(File program, ...)} 2N/A * @return a non-null list of probe detail 2N/A * @throws NullPointerException if the given program identifier is 2N/A * @throws IllegalArgumentException if the specified program was not 2N/A * compiled by this consumer 2N/A * @throws IllegalStateException if called before {@link 2N/A * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 2N/A * or if the consumer is closed 2N/A * @throws DTraceException if an exception occurs in the native 2N/A * @see #listProgramProbes(Program program) 2N/A * @see #listProbeDetail(ProbeDescription filter) 2N/A * Gets the kernel function name for the given 32-bit kernel 2N/A * @param address 32-bit kernel function address, such as the value 2N/A * of a {@link Tuple} member in an {@link AggregationRecord} to be 2N/A * converted for display 2N/A * @return the result of kernel function lookup as one of the 2N/A * following:<ul><li>{@code module`function}</li> 2N/A * <li>{@code module`function+offset}</li> 2N/A * <li>{@code module`address}</li> 2N/A * <li>{@code address}</li></ul> where {@code module} and {@code 2N/A * function} are names, and {@code offset} and {@code address} are 2N/A * integers in hexadecimal format preceded by "{@code 0x}". {@code 2N/A * offset} is the number of bytes from the beginning of the 2N/A * function, included when non-zero. {@code address} is simply the 2N/A * hex form of the input parameter, returned when function lookup 2N/A * fails. The exact details of this format are subject to change. 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @see #lookupKernelFunction(long address) 2N/A * Gets the kernel function name for the given 64-bit kernel 2N/A * @param address 64-bit kernel function address 2N/A * @return kernel function name 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @see #lookupKernelFunction(int address) 2N/A * Gets the user function name for the given 32-bit user address and 2N/A * @param pid ID of the user process containing the addressed 2N/A * @param address 32-bit user function address, such as the value 2N/A * of a {@link Tuple} member in an {@link AggregationRecord} to be 2N/A * converted for display. 2N/A * @return result of user function lookup as one of the 2N/A * following:<ul> <li>{@code module`function}</li> 2N/A * <li>{@code module`function+offset}</li> 2N/A * <li>{@code module`address}</li> 2N/A * <li>{@code address}</li></ul> where {@code module} and {@code 2N/A * function} are names, and {@code offset} and {@code address} are 2N/A * integers in hexadecimal format preceded by "{@code 0x}". {@code 2N/A * offset} is the number of bytes from the beginning of the 2N/A * function, included when non-zero. {@code address} is simply the 2N/A * hex form of the input parameter, returned when function lookup 2N/A * fails. The exact details of this format are subject to change. 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @see #lookupUserFunction(int pid, long address) 2N/A * Gets the user function name for the given 64-bit user address and 2N/A * @param pid ID of the user process containing the addressed 2N/A * @param address 64-bit user function address 2N/A * @return user function name 2N/A * @throws IllegalStateException if called before {@link #go()} or 2N/A * after {@link #close()} 2N/A * @see #lookupUserFunction(int pid, int address) 2N/A * Gets the version of the native DTrace library. 2N/A * @return version string generated by the native DTrace library 2N/A * (same as the output of {@code dtrace(1M)} with the {@code -V}