man pages section 3: Extended Library Functions, Volume 2

dtrace_attr2str (3DTRACE)

Name

dtrace_class_name, dtrace_attr2str, dtrace_str2attr, dtrace_stability_name - Process DTrace stability and dependency class values

Synopsis

cc [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>

char *dtrace_attr2str(dtrace_attribute_t attr, char *buf, size_t len)

int dtrace_str2attr(const char *str, dtrace_attribute_t *attr)

const char *dtrace_stability_name(dtrace_stability_t s)

const char *dtrace_class_name(dtrace_class_t c)

Description

The functions have the following descriptions:

dtrace_attr2str()

The dtrace_attr2str() function takes a DTrace interface attribute, attr, of the type, dtrace_attribute_t, and returns the string describing that attribute in the provided buffer, buf. See the Stability chapter of the Dynamic Tracing Guide for information on the values for name stability, data stability, and data dependency.

The dtrace_attribute_t data structure is defined as follows:

typedef struct dtrace_attribute {
     dtrace_stability_t dtat_name;  /* entity name stability */
     dtrace_stability_t dtat_data;  /* entity data stability */
     dtrace_class_t dtat_class;     /* entity data dependency */
} dtrace_attribute_t;

For a dtrace_attribute_t data structure with the following values:

dtat_name == DTRACE_STABILITY_STABLE
dtat_data == DTRACE_STABILITY_STABLE
dtat_class == DTRACE_CLASS_COMMON

The following sample code places the string, Stable/Stable/Common in the buffer, buf.

if (dtrace_attr2str(attr, buf, 256) == NULL)
                 fatal("dtrace_attr2str()");

dtrace_str2attr()

The dtrace_str2attr() function takes a string, str, containing an attribute description, and populates the dtrace_attribute_t data type referenced by the DTrace interface attribute, attr with appropriate data.

For example, the following code:

if (dtrace_str2attr("Stable/Stable/Common", &attr) < 0)
                 fatal("dtrace_str2attr()"); 

populates the data structure with the following values:

dtat_name == DTRACE_STABILITY_STABLE
dtat_data == DTRACE_STABILITY_STABLE
dtat_class == DTRACE_CLASS_COMMON

dtrace_stability_name()

The dtrace_stability_name() function takes a DTrace stability value, s, and returns the string corresponding to that stability value.

For example, the following code returns the string, STABLE:

dtrace_stability_name(DTRACE_STABILITY_STABLE);

dtrace_class_name()

The dtrace_class_name() function takes a DTrace dependency class value, c, and returns the string corresponding to that value.

For example, the following code returns the string, Common:

dtrace_class_name(DTRACE_CLASS_COMMON);

Return Values

The values returned by the functions are described below:

dtrace_attr2str()

• On successful completion, returns a string describing the attributes.

• If any attribute is invalid, returns NULL.

• For other error conditions, returns -1 and sets the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.

dtrace_str2attr()

• On successful completion, returns 0.

• If the string, str is not a valid attribute description, returns -1.

• For other error conditions, returns -1 and sets the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.

dtrace_stability_name()

• On successful completion, returns a string containing the stability name.

• If the value of s does not correspond to a DTrace stability value, returns NULL.

dtrace_class_name()

• On successful completion, returns a string containing the dependency class name.

• If the value of c does not correspond to a DTrace dependency class, returns NULL.

Errors

The dtrace_attr2str() function will fail if:

EINVAL

buf is NULL.

The dtrace_str2attr() function will fail if:

EINVAL

Either str or attr is NULL.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE Architecture all Availability system/dtrace Interface Stability Committed MT-Level Safe

See Also

libdtrace(3LIB), dtrace_errno(3DTRACE)