dtrace_str2desc, dtrace_xstr2desc, dtrace_id2desc, dtrace_desc2str - Conversion utilities for probe descriptions
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)
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"
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"
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 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.
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.
The dtrace_xstr2desc() and dtrace_str2desc() functions will fail if:
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.
There is a bad macro variable in the probe description.
The spec argument is DTRACE_PROBESPEC_NONE.
Some component of the probe description exceeds the maximum allowed length.
The dtrace_id2desc() function will fail if:
The dtp or pdp argument is NULL.
The specified probe identifier, id, is invalid.
The dtrace_desc2str() function will fail if:
The pdp or buff argument is NULL.
See attributes(7) for descriptions of the following attributes:
|