Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_id2desc (3DTRACE)

Name

dtrace_str2desc, dtrace_xstr2desc, dtrace_id2desc, dtrace_desc2str - Conversion utilities for probe descriptions

Synopsis

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

     int dtrace_xstr2desc(dtrace_hdl_t *dtp, dtrace_probespec_t spec,
	const char *s, int argc, char *const argv[], dtrace_probedesc_t *pdp)

     int dtrace_str2desc(dtrace_hdl_t *dtp, dtrace_probespec_t spec,
	const char *s, dtrace_probedesc_t *pdp)

     int dtrace_id2desc(dtrace_hdl_t *dtp, dtrace_id_t id,
	 dtrace_probedesc_t *pdp)

     char *dtrace_desc2str(const dtrace_probedesc_t *pdp, char *buf,
	 size_t len)

Description

The dtrace_xstr2desc() Function

The dtrace_xstr2desc() function takes a string, s, containing a DTrace probe name that can contain macros, such as the name, syscall:$1:$2:entry. The function populates the dtrace_probedesc_t data structure referenced by the pdp argument with appropriate data. The function expands the macros, if any, in the DTrace probe name based on the values of the arguments, argc and argv, that are passed to the function.

The dtrace_probedesc_t data structure is defined as follows:

     typedef struct dtrace_probedesc {
     	dtrace_id_t dtpd_id;                     /* probe identifier */
     	char dtpd_provider[DTRACE_PROVNAMELEN];  /* provider name */
     	char dtpd_mod[DTRACE_MODNAMELEN];        /* module name */
     	char dtpd_func[DTRACE_FUNCNAMELEN];      /* function name */
     	char dtpd_name[DTRACE_NAMELEN];          /* probe name */
     } dtrace_probedesc_t;

For example, given the following code:

      dtrace_hdl_t *dtp;
      dtrace_probedesc_t pd;
      char *myargv[3];
      int argc;

	/* After initializing dtp. */
       myargv[0] = "dtrace";
       myargv[1] = "foo";
       myargv[2] = "bar";
       myargc = 3; 
       dtrace_xstr2desc(dtp, DTRACE_PROBESPEC_NAME,
           "syscall:$1:$2:entry", myargc, myargv, &pd);

The fields of dtrace_probedesc_t data structure referenced by the pdp argument contain the following values:

     dtpd_id == 0
     dtpd_provider == "syscall"
     dtpd_mod == "foo"
     dtpd_func == "bar"
     dtpd_name == "entry"

Note -  This function does not set the probe ID.

The dtrace_str2desc() Function

The dtrace_str2desc() function takes a string, s, containing a DTrace probe name that does not contain macros, such as the name, syscall::pread:entry. The function populates the dtrace_probedesc_t data structure referenced by the pdp argument with the appropriate data.

For example, given the following code:

      dtrace_hdl_t *dtp;
      dtrace_probedesc_t pd;

      /* After initializing dtp. */
      dtrace_str2desc(dtp, DTRACE_PROBESPEC_NAME,
            "syscall::pread:entry", &pd);

The fields of the dtrace_probedesc_t data structure referenced by the pdp argument contain the following values:

     dtpd_id == 0
     dtpd_provider == "syscall"
     dtpd_mod == ""
     dtpd_func == "pread"
     dtpd_name == "entry"

Note -  This function does not set the probe ID.

The dtrace_id2desc() Function

The dtrace_id2desc() function takes the ID of a DTrace probe in its id argument, and populates the fields of the dtrace_probedesc_t data structure referenced by the pdp argument with the data corresponding to the probe.

For example, if the 'dtrace -l' shows the following information:

   ID        PROVIDER            MODULE                      FUNCTION NAME
[ ... ]
  478          fbt                fcsm                    fcsm_alloc_cmd entry

Then, given the following code:

    dtrace_hdl_t *dtp;
    dtrace_probedesc_t pd;

    /* After initializing dtp. */
    dtrace_id2desc(dtp, 478, &pd);

The fields of the dtrace_probedesc_t data structure referenced by the pdp argument contain the following values:

        dtpd_id == 478
        dtpd_provider == "fbt"
        dtpd_mod == "fcsm"
        dtpd_func == "fcsm_alloc_cmd"
        dtpd_name == "entry"

The dtrace_desc2str() Function

The dtrace_desc2str() function takes a dtrace_probedesc_t data structure referenced by the pdp argument, and returns the description of the probe in the provided buffer, buf.

For example, given the following code:

      dtrace_probedesc_t pd;
	char buf[256];

	pd.dtpd_id = 0;
	pd.dtpd_provider = "fbt";
	pd.dtpd_mod = "fcsm";
	pd.dtpd_func = "fcsm_alloc_cmd";
	pd.dtpd_name = "entry";

	dtrace_desc2str(&pd, buf, 256);

The buf argument contains the string, fbt:fcsm:fcsm_alloc_cmd:entry.


Note -  If the dtpd_id argument contains a non-zero value, the description returned is a string containing that value.

Return Values

On successful completion, the dtrace_xstr2desc(), dtrace_str2desc() and dtrace_id2desc() functions return 0. On failure, the functions return -1 and set the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.

On successful completion, the dtrace_desc2str() function returns a pointer to the buf argument. On failure, the function returns NULL and sets the errno argument with the error number to indicate the error. See the dtrace_errno(3DTRACE) man page for more information.

Errors

The dtrace_xstr2desc() and dtrace_str2desc() functions will fail if:

EINVAL

Either the argument, dtp, s, or pdp is NULL, or the argument, spec is an inappropriate value.

Either a positional macro such as $1, is used in the s and argv parameters, or that element of the argv parameter is NULL. This applies only to the dtrace_xstr2desc() function.

EDT_BADSPCV

There is a bad macro variable in the probe description.

EDT_BADSPEC

The spec argument is DTRACE_PROBESPEC_NONE.

ENAMETOOLONG

Some component of the probe description exceeds the maximum allowed length.

The dtrace_id2desc() function will fail if:

EINVAL

The dtp or pdp argument is NULL.

EDT_BADID

The specified probe identifier, id, is invalid.

The dtrace_desc2str() function will fail if:

EINVAL

The pdp or buff argument 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)