org.opensolaris.os.dtrace
Class Option

java.lang.Object
  extended by org.opensolaris.os.dtrace.Option
All Implemented Interfaces:
java.io.Serializable

public final class Option
extends java.lang.Object
implements java.io.Serializable

A DTrace option and its value. Compile-time options must be set before calling Consumer compile(String program, ...) or compile(File program, ...) in order to affect program compilation. Runtime options may be set anytime before calling Consumer go(), and some of them may be changed while a consumer is running.

See the Options and Tunables chapter of the Solaris Dynamic Tracing Guide.

Immutable. Supports persistence using XMLEncoder.

See Also:
Serialized Form

Field Summary
static java.lang.String aggrate
          Rate of aggregation reading (time).
static java.lang.String aggsize
          Aggregation buffer size (size).
static java.lang.String aggsortkey
          Denotes that aggregation data should be sorted in tuple order, with ties broken by value order (no option value).
static java.lang.String aggsortkeypos
          When multiple aggregation tuple elements are present, the position of the tuple element that should act as the primary sort key (zero-based index).
static java.lang.String aggsortpos
          When multiple aggregations are being printed, the position of the aggregation that should act as the primary sort key (zero-based index).
static java.lang.String aggsortrev
          Denotes that aggregation data should be sorted in descending order (no option value).
static java.lang.String amin
          Set program attribute minimum (compile-time).
static java.lang.String argref
          Do not require all macro args to be used (compile-time; no option value).
static java.lang.String bufpolicy
          Buffering policy (switch, fill, or ring).
static long BUFPOLICY_FILL
          Value returned by Consumer.getOption(String option) for the bufpolicy option when the fill buffer policy is set.
static long BUFPOLICY_RING
          Value returned by Consumer.getOption(String option) for the bufpolicy option when the ring buffer policy is set.
static long BUFPOLICY_SWITCH
          Value returned by Consumer.getOption(String option) for the bufpolicy option when the default switch buffer policy is set.
static java.lang.String bufresize
          Buffer resizing policy (auto or manual).
static long BUFRESIZE_AUTO
          Value returned by Consumer.getOption(String option) for the bufresize option when the default auto buffer resize policy is set.
static long BUFRESIZE_MANUAL
          Value returned by Consumer.getOption(String option) for the bufresize option when the manual buffer resize policy is set.
static java.lang.String bufsize
          Principal buffer size (size).
static java.lang.String cleanrate
          Cleaning rate (time).
static java.lang.String cpp
          Run cpp(1) preprocessor on D script files (compile-time; no option value).
static java.lang.String cpppath
          Used together with cpp option, specifies which cpp to run by its pathname (compile-time).
static java.lang.String cpu
          CPU on which to enable tracing (scalar).
static java.lang.String defaultargs
          Use zero (0) or empty string ("") as the value for unspecified macro args (compile-time; no option value).
static java.lang.String define
          Define symbol when invoking preprocssor (compile-time).
static java.lang.String destructive
          Permit destructive actions (no option value).
static java.lang.String dynvarsize
          Dynamic variable space size (size).
static java.lang.String empty
          Permit compilation of empty D source files (compile-time; no option value).
static java.lang.String errtags
          Adds error tags to default error messages (compile-time; no option value).
static java.lang.String flowindent
          Adds Flow information to generated ProbeData indicating direction of control flow (entry or return) across function boundaries and depth in call stack (no option value).
static java.lang.String incdir
          Add include directory to preprocessor search path (compile-time).
static java.lang.String knodefs
          Permit unresolved kernel symbols (compile-time; no option value).
static java.lang.String libdir
          Add library directory to library search path (compile-time).
static java.lang.String nspec
          Number of speculations (scalar).
static java.lang.String quiet
          Only output explicitly traced data (no option value).
static java.lang.String specsize
          Speculation buffer size (size).
static java.lang.String stackframes
          Number of stack frames (scalar).
static java.lang.String statusrate
          Rate of status checking (time).
static java.lang.String stdc
          Specify ISO C conformance settings for preprocessor (compile-time).
static java.lang.String strsize
          String size (size).
static java.lang.String switchrate
          Rate of buffer switching (time).
static java.lang.String undef
          Undefine symbol when invoking preprocessor (compile-time).
static java.lang.String unodefs
          Permit unresolved user symbols (compile-time; no option value).
static long UNSET
          Value returned by Consumer.getOption(String option) when the given boolean option is unset.
static java.lang.String ustackframes
          Number of user stack frames (scalar).
static java.lang.String VALUE_AUTO
          bufresize default value: use auto buffer resizing policy.
static java.lang.String VALUE_FILL
          bufpolicy value: use fill princical buffer policy.
static java.lang.String VALUE_MANUAL
          bufresize value: use manual buffer resizing policy.
static java.lang.String VALUE_RING
          bufpolicy value: use ring princical buffer policy.
static java.lang.String VALUE_SET
          May be passed to Consumer.setOption(String option, String value) to set a boolean option such as flowindent.
static java.lang.String VALUE_SWITCH
          bufpolicy default value: use switch princical buffer policy.
static java.lang.String VALUE_UNSET
          May be passed to Consumer.setOption(String option, String value) to unset a boolean option such as flowindent.
static java.lang.String version
          Request specific version of native DTrace library (compile-time).
static java.lang.String zdefs
          Permit probe definitions that match zero probes (compile-time; no option value).
 
Constructor Summary
Option(java.lang.String optionName)
          Creates an option without an associated value.
Option(java.lang.String optionName, java.lang.String optionValue)
          Creates an option with the given name and value.
 
Method Summary
static java.lang.String days(int n)
          Gets a time option value indicating the given number of days.
 boolean equals(java.lang.Object o)
          Compares the specified object with this option for equality.
static java.lang.String gb(int n)
          Gets a size option value indicating the given number of gigabytes.
 java.lang.String getName()
          Gets the option name.
 java.lang.String getValue()
          Gets the option value.
 int hashCode()
          Overridden to ensure that equal options have equal hashcodes.
static java.lang.String hours(int n)
          Gets a time option value indicating the given number of hours.
static java.lang.String hz(int n)
          Gets a time option value indicating the given rate per second.
static java.lang.String kb(int n)
          Gets a size option value indicating the given number of kilobytes.
static java.lang.String mb(int n)
          Gets a size option value indicating the given number of megabytes.
static java.lang.String micros(int n)
          Gets a time option value indicating the given number of microseconds.
static java.lang.String millis(int n)
          Gets a time option value indicating the given number of milliseconds.
static java.lang.String minutes(int n)
          Gets a time option value indicating the given number of minutes.
static java.lang.String nanos(int n)
          Gets a time option value indicating the given number of nanoseconds.
static java.lang.String seconds(int n)
          Gets a time option value indicating the given number of seconds.
static java.lang.String tb(int n)
          Gets a size option value indicating the given number of terabytes.
 java.lang.String toString()
          Gets a string representation of this option useful for logging and not intended for display.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

UNSET

public static final long UNSET
Value returned by Consumer.getOption(String option) when the given boolean option is unset.

See Also:
Constant Field Values

BUFPOLICY_RING

public static final long BUFPOLICY_RING
Value returned by Consumer.getOption(String option) for the bufpolicy option when the ring buffer policy is set.

See Also:
Constant Field Values

BUFPOLICY_FILL

public static final long BUFPOLICY_FILL
Value returned by Consumer.getOption(String option) for the bufpolicy option when the fill buffer policy is set.

See Also:
Constant Field Values

BUFPOLICY_SWITCH

public static final long BUFPOLICY_SWITCH
Value returned by Consumer.getOption(String option) for the bufpolicy option when the default switch buffer policy is set.

See Also:
Constant Field Values

BUFRESIZE_AUTO

public static final long BUFRESIZE_AUTO
Value returned by Consumer.getOption(String option) for the bufresize option when the default auto buffer resize policy is set.

See Also:
Constant Field Values

BUFRESIZE_MANUAL

public static final long BUFRESIZE_MANUAL
Value returned by Consumer.getOption(String option) for the bufresize option when the manual buffer resize policy is set.

See Also:
Constant Field Values

VALUE_SET

public static final java.lang.String VALUE_SET
May be passed to Consumer.setOption(String option, String value) to set a boolean option such as flowindent. However, a more convenient way to set boolean options is Consumer.setOption(String option).

See Also:
Constant Field Values

VALUE_UNSET

public static final java.lang.String VALUE_UNSET
May be passed to Consumer.setOption(String option, String value) to unset a boolean option such as flowindent. However, a more convenient way to unset boolean options is Consumer.unsetOption(String option).

See Also:
Constant Field Values

VALUE_RING

public static final java.lang.String VALUE_RING
bufpolicy value: use ring princical buffer policy.

See Also:
Constant Field Values

VALUE_FILL

public static final java.lang.String VALUE_FILL
bufpolicy value: use fill princical buffer policy.

See Also:
Constant Field Values

VALUE_SWITCH

public static final java.lang.String VALUE_SWITCH
bufpolicy default value: use switch princical buffer policy.

See Also:
Constant Field Values

VALUE_AUTO

public static final java.lang.String VALUE_AUTO
bufresize default value: use auto buffer resizing policy.

See Also:
Constant Field Values

VALUE_MANUAL

public static final java.lang.String VALUE_MANUAL
bufresize value: use manual buffer resizing policy.

See Also:
Constant Field Values

amin

public static final java.lang.String amin
Set program attribute minimum (compile-time). The format of the option value is defined by the InterfaceAttributes.toString() method.

See Also:
Program.getInfo(), Constant Field Values

argref

public static final java.lang.String argref
Do not require all macro args to be used (compile-time; no option value).

See Also:
Consumer.compile(String program, String[] macroArgs), Consumer.compile(File program, String[] macroArgs), Constant Field Values

cpp

public static final java.lang.String cpp
Run cpp(1) preprocessor on D script files (compile-time; no option value).

See Also:
Constant Field Values

cpppath

public static final java.lang.String cpppath
Used together with cpp option, specifies which cpp to run by its pathname (compile-time).

See Also:
Constant Field Values

defaultargs

public static final java.lang.String defaultargs
Use zero (0) or empty string ("") as the value for unspecified macro args (compile-time; no option value).

See Also:
Consumer.compile(String program, String[] macroArgs), Consumer.compile(File program, String[] macroArgs), Constant Field Values

define

public static final java.lang.String define
Define symbol when invoking preprocssor (compile-time).

See Also:
Constant Field Values

empty

public static final java.lang.String empty
Permit compilation of empty D source files (compile-time; no option value).

See Also:
Constant Field Values

errtags

public static final java.lang.String errtags
Adds error tags to default error messages (compile-time; no option value).

See Also:
Constant Field Values

incdir

public static final java.lang.String incdir
Add include directory to preprocessor search path (compile-time).

See Also:
Constant Field Values

knodefs

public static final java.lang.String knodefs
Permit unresolved kernel symbols (compile-time; no option value).

See Also:
Constant Field Values

libdir

public static final java.lang.String libdir
Add library directory to library search path (compile-time).

See Also:
Constant Field Values

stdc

public static final java.lang.String stdc
Specify ISO C conformance settings for preprocessor (compile-time).

See Also:
Constant Field Values

undef

public static final java.lang.String undef
Undefine symbol when invoking preprocessor (compile-time).

See Also:
Constant Field Values

unodefs

public static final java.lang.String unodefs
Permit unresolved user symbols (compile-time; no option value).

See Also:
Constant Field Values

version

public static final java.lang.String version
Request specific version of native DTrace library (compile-time).

See Also:
Constant Field Values

zdefs

public static final java.lang.String zdefs
Permit probe definitions that match zero probes (compile-time; no option value).

See Also:
Constant Field Values

aggrate

public static final java.lang.String aggrate
Rate of aggregation reading (time). Runtime option.

See Also:
Constant Field Values

aggsize

public static final java.lang.String aggsize
Aggregation buffer size (size). Runtime option.

See Also:
Constant Field Values

aggsortkey

public static final java.lang.String aggsortkey
Denotes that aggregation data should be sorted in tuple order, with ties broken by value order (no option value). Runtime option.

See Also:
AggregationRecord, aggsortkeypos, aggsortpos, aggsortrev, Constant Field Values

aggsortkeypos

public static final java.lang.String aggsortkeypos
When multiple aggregation tuple elements are present, the position of the tuple element that should act as the primary sort key (zero-based index). Runtime option.

See Also:
aggsortkey, aggsortpos, aggsortrev, Constant Field Values

aggsortpos

public static final java.lang.String aggsortpos
When multiple aggregations are being printed, the position of the aggregation that should act as the primary sort key (zero-based index). Runtime option.

Here "position" refers to the position of the aggregation in the printa() argument list after the format string (if any). For example, given the following statement:


 printa("%d %@7d %@7d\n", @a, @b);
 
setting aggsortpos to "0" indicates that output should be sorted using the values of @a as the primary sort key, while setting aggsortpos to "1" indicates that output should be sorted using the values of @b as the primary sort key.

See Also:
aggsortkey, aggsortkeypos, aggsortrev, Constant Field Values

aggsortrev

public static final java.lang.String aggsortrev
Denotes that aggregation data should be sorted in descending order (no option value). Runtime option.

The aggsortrev option is useful in combination with the aggsortkey, aggsortkeypos, and aggsortpos options, which define the ascending sort reversed by this option.

See Also:
aggsortkey, aggsortkeypos, aggsortpos, Constant Field Values

bufsize

public static final java.lang.String bufsize
Principal buffer size (size). Runtime option.

See Also:
Constant Field Values

bufpolicy

public static final java.lang.String bufpolicy
Buffering policy (switch, fill, or ring). Runtime option.

See the Principal Buffer Policies section of the Buffers and Buffering chapter of the Solaris Dynamic Tracing Guide.

See Also:
Constant Field Values

bufresize

public static final java.lang.String bufresize
Buffer resizing policy (auto or manual). Runtime option.

See the Buffer Resizing Policy section of the Buffers and Buffering chapter of the Solaris Dynamic Tracing Guide.

See Also:
Constant Field Values

cleanrate

public static final java.lang.String cleanrate
Cleaning rate (time). Runtime option.

See Also:
Constant Field Values

cpu

public static final java.lang.String cpu
CPU on which to enable tracing (scalar). Runtime option.

See Also:
Constant Field Values

destructive

public static final java.lang.String destructive
Permit destructive actions (no option value). Runtime option.

See Also:
Constant Field Values

dynvarsize

public static final java.lang.String dynvarsize
Dynamic variable space size (size). Runtime option.

See Also:
Constant Field Values

flowindent

public static final java.lang.String flowindent
Adds Flow information to generated ProbeData indicating direction of control flow (entry or return) across function boundaries and depth in call stack (no option value). Runtime option.

See Also:
Constant Field Values

nspec

public static final java.lang.String nspec
Number of speculations (scalar). Runtime option.

See Also:
Constant Field Values

quiet

public static final java.lang.String quiet
Only output explicitly traced data (no option value). Makes no difference to generated ProbeData, but user apps may use the quiet flag as a rendering hint similar to the -q dtrace(1M) command option. Runtime option.

See Also:
Constant Field Values

specsize

public static final java.lang.String specsize
Speculation buffer size (size). Runtime option.

See Also:
Constant Field Values

stackframes

public static final java.lang.String stackframes
Number of stack frames (scalar). Runtime option.

See Also:
Constant Field Values

statusrate

public static final java.lang.String statusrate
Rate of status checking (time). Runtime option.

See Also:
Constant Field Values

strsize

public static final java.lang.String strsize
String size (size). Runtime option.

See Also:
Constant Field Values

switchrate

public static final java.lang.String switchrate
Rate of buffer switching (time). Runtime option.

See Also:
Constant Field Values

ustackframes

public static final java.lang.String ustackframes
Number of user stack frames (scalar). Runtime option.

See Also:
Constant Field Values
Constructor Detail

Option

public Option(java.lang.String optionName)
Creates an option without an associated value. The created boolean option has the value VALUE_SET. To specify that the named option be unset, use VALUE_UNSET.

Parameters:
optionName - DTrace option name
Throws:
java.lang.NullPointerException - if the given option name is null
See Also:
Option(String optionName, String optionValue)

Option

public Option(java.lang.String optionName,
              java.lang.String optionValue)
Creates an option with the given name and value.

Parameters:
optionName - DTrace option name
optionValue - DTrace option value
Throws:
java.lang.NullPointerException - if the given option name or value is null
Method Detail

kb

public static java.lang.String kb(int n)
Gets a size option value indicating the given number of kilobytes.

Parameters:
n - number of kilobytes
Returns:
size option value indicating the given number of kilobytes

mb

public static java.lang.String mb(int n)
Gets a size option value indicating the given number of megabytes.

Parameters:
n - number of megabytes
Returns:
size option value indicating the given number of megabytes

gb

public static java.lang.String gb(int n)
Gets a size option value indicating the given number of gigabytes.

Parameters:
n - number of gigabytes
Returns:
size option value indicating the given number of gigabytes

tb

public static java.lang.String tb(int n)
Gets a size option value indicating the given number of terabytes.

Parameters:
n - number of terabytes
Returns:
size option value indicating the given number of terabytes

nanos

public static java.lang.String nanos(int n)
Gets a time option value indicating the given number of nanoseconds.

Parameters:
n - number of nanoseconds
Returns:
time option value indicating the given number of nanoseconds

micros

public static java.lang.String micros(int n)
Gets a time option value indicating the given number of microseconds.

Parameters:
n - number of microseconds
Returns:
time option value indicating the given number of microseconds

millis

public static java.lang.String millis(int n)
Gets a time option value indicating the given number of milliseconds.

Parameters:
n - number of milliseconds
Returns:
time option value indicating the given number of milliseconds

seconds

public static java.lang.String seconds(int n)
Gets a time option value indicating the given number of seconds.

Parameters:
n - number of seconds
Returns:
time option value indicating the given number of seconds

minutes

public static java.lang.String minutes(int n)
Gets a time option value indicating the given number of minutes.

Parameters:
n - number of minutes
Returns:
time option value indicating the given number of minutes

hours

public static java.lang.String hours(int n)
Gets a time option value indicating the given number of hours.

Parameters:
n - number of hours
Returns:
time option value indicating the given number of hours

days

public static java.lang.String days(int n)
Gets a time option value indicating the given number of days.

Parameters:
n - number of days
Returns:
time option value indicating the given number of days

hz

public static java.lang.String hz(int n)
Gets a time option value indicating the given rate per second.

Parameters:
n - number of cycles per second (hertz)
Returns:
time option value indicating rate per second

getName

public java.lang.String getName()
Gets the option name.

Returns:
non-null option name

getValue

public java.lang.String getValue()
Gets the option value.

Returns:
option value, or null if no value is associated with the option

equals

public boolean equals(java.lang.Object o)
Compares the specified object with this option for equality. Defines equality as having equal names and values.

Overrides:
equals in class java.lang.Object
Returns:
true if and only if the specified object is an Option with the same name and the same value as this option. Option values are the same if they are both null or if they are equal as defined by String.equals().

hashCode

public int hashCode()
Overridden to ensure that equal options have equal hashcodes.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Gets a string representation of this option useful for logging and not intended for display. The exact details of the representation are unspecified and subject to change, but the following format may be regarded as typical:

 class-name[property1 = value1, property2 = value2]
 

Overrides:
toString in class java.lang.Object