dtrace_type_name, dtrace_type_align, dtrace_type_cmp, dtrace_type_compat, dtrace_type_encoding, dtrace_type_enum_name, dtrace_type_kind, dtrace_type_member_info, dtrace_type_member_iter, dtrace_type_pointer, dtrace_type_reference, dtrace_type_resolve, dtrace_type_size, dtrace_type_visit - DTrace type interface
c [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>
ssize_t dtrace_type_align(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip)
int dtrace_type_array_info(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip,
const dtrace_type_arinfo_t *tap)
int dtrace_type_cmp(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *ltip,
const dtrace_typeinfo_t *rtip)
int dtrace_type_compat(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *ltip,
const dtrace_typeinfo_t *rtip)
int dtrace_type_encoding(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip,
const dtrace_type_encoding_t *dtep)
int dtrace_type_enum_name(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip,
int value, char *buf, size_t len)
int dtrace_type_kind(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip)
int dtrace_type_member_info(dtrace_hdl_t *dtp,
const dtrace_typeinfo_t *tip, const char *name,
dtrace_type_membinfo_t *mip)
typedef int dtrace_type_member_iter_f(dtrace_hdl_t *, const char *,
const dtrace_typeinfo_t *, ulong_t, void *)
int dtrace_type_member_iter(dtrace_hdl_t *dtp,
const dtrace_typeinfo_t *tip, dtrace_type_member_iter_f *func,
void *arg)
int dtrace_type_name(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip,
char *buf, size_t len)
dtrace_typeinfo_t *dtrace_type_pointer(dtrace_hdl_t *dtp,
const dtrace_typeinfo_t *tip)
dtrace_typeinfo_t *dtrace_type_reference(dtrace_hdl_t *dtp,
const dtrace_typeinfo_t *tip)
dtrace_typeinfo_t *dtrace_type_resolve(dtrace_hdl_t *dtp,
const dtrace_typeinfo_t *tip)
ssize_t dtrace_type_size(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip)
typedef int dtrace_type_visit_f(dtrace_hdl_t *, const dtrace_typeinfo_t *,
const char *, ulong_t, int, void *)
int dtrace_type_visit(dtrace_hdl_t *dtp, const dtrace_typeinfo_t *tip,
dtrace_type_visit_f *func, void *arg)
dtrace_typeinfo_t is an opaque data structure containing information about the type of an object in a piece of software that DTrace has instrumented. The functions in this man page return information about the type described by a dtrace_typeinfo_t data structure.
The functions are described as follows:
Returns the alignment in bytes of the specified type, tip.
Returns information about the specified array type, tip in the data structure referenced by the tap argument. The information includes the type of the contents of the array, the type of the index of the array, and the number of elements.
Determines whether the two types, ltip and rtip are the same.
Determines whether the two types, ltip and rtip are compatible types. Two types are compatible if they are the same type or have the same ASCII name and encoding properties.
Returns the encoding of the specified type, tip. The encoding is returned in the dtep argument. See the Usage section in this man page for the list of encodings.
If the specified type, tip is an enum, the dtrace_type_enum_name() function writes at most len bytes, including the NULL terminator, of the name associated with the value argument in that enum into the buf argument.
Returns the kind of the specified type, tip. The kind includes integer, float, array, function and other types. See the Usage section in this man page for the full list of kinds.
Returns the information about the member, name of the struct or union specified in the tip argument. This information is returned in the mip argument. See the Usage section in this man page for a description of the dtrace_type_membinfo_t data structure.
Iterates over the members of the struct or union specified in the tip argument. The callback function, func is called for each member. The name, type, and offset in bits of the member, along with the arg argument, is passed to the func argument.
Writes at most len bytes, including the NULL terminator, of the name of the specified type, tip into the buf argument.
Returns the type that is a reference to the specified type, tip, if the reference type already exists in the backend type system. The dtrace_type_pointer() function does not construct a new type.
Returns the type being referenced by the specified type, tip. The function returns NULL and sets an error if the tip argument does not specify a reference type.
Resolves the specified type, tip to its base type by recursively following any typedefs.
Returns the size in bytes of the specified type, tip.
Recursively visits the members of the specified type, tip. The callback function, func is called for each member of the specified type. The name, type, and offset (in bits) of each member is passed to the func argument, as well as the recursion depth and the arg argument.
The functions return values as described below:
On successful completion, the function returns the alignment in bytes of the specified type, tip. On failure, the function 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.
On successful completion, the function returns 0 and places the requested information in the data structure referenced by the tap argument. On failure, the function 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.
The function returns zero if the two specified types are the same type. On failure, the function returns a non-zero value.
The function returns a non-zero value if the two specified types are compatible.
On successful completion, the function returns the actual number of bytes needed to format the name associated with the value argument in the enum specified by the tip argument. If the tip argument is not an enum or if there is no name associated with that value, the function 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.
On successful completion, the function returns the kind of the specified type, tip. On failure, the function 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.
On successful completion, the function returns 0 and writes the member information into the location specified by the mip argument. On failure, the function 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.
On successful completion, the function returns 0. If any invocation of the callback function, func returns a non-zero value, the dtrace_type_member_iter() function stops processing the members of the tip argument and returns that value.
On successful completion, the function returns the actual number of bytes needed to format the name of the specified type the tip argument. On failure, the function 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.
On successful completion, the function returns a pointer to a dtrace_typeinfo_t data structure containing the type that is a pointer to the specified type, tip. The function cannot construct a new type and returns successfully only if the pointer type is defined. On failure, the function returns NULL and sets 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 function returns a pointer to a dtrace_typeinfo_t data structure containing the type referenced by the pointer type, tip. On failure, the function returns NULL and sets 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 function returns a pointer to a dtrace_typeinfo_t data structure containing the resolution of the specified type, tip, i.e., the resultant type after all typedefs are resolved. On failure, the function returns NULL and sets 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 function returns the size in bytes of the specified type, tip. On failure, the function 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.
If any invocation of the callback function, func returns a non-zero value, the dtrace_type_visit() function stops processing the members of the type, tip and returns that value. On failure,, the dtrace_type_visit() function returns 0.
All the functions will fail if:
The dtp or tip argument is NULL.
The system encountered an error while attempting to allocate memory.
The system encountered an error in processing the specified type.
The dtrace_type_array_info() function will fail if:
The tap argument is NULL.
The dtrace_type_cmp() and dtrace_type_compat() functions will fail if:
The ltip or rtip argument is NULL.
The dtrace_type_name() function will fail if:
The buf argument is NULL and the len argument is non-zero.
The dtrace_type_visit() function will fail if:
The func argument is NULL.
The array information returned in the tap argument to the dtrace_type_array_info() function has the following type:
typedef struct dtrace_type_arinfo {
dtrace_typeinfo_t dta_contents; /* type of contents */
dtrace_typeinfo_t dta_index; /* type of index */
uint_t dta_nelems; /* number of elements */
} dtrace_type_arinfo_t;
The type kind returned by the dtrace_type_kind() function is one of the following values:
DTRACE_TYPE_K_UNKNOWN
DTRACE_TYPE_K_INTEGER
DTRACE_TYPE_K_FLOAT
DTRACE_TYPE_K_POINTER
DTRACE_TYPE_K_ARRAY
DTRACE_TYPE_K_FUNCTION
DTRACE_TYPE_K_STRUCT
DTRACE_TYPE_K_UNION
DTRACE_TYPE_K_ENUM
DTRACE_TYPE_K_FORWARD
DTRACE_TYPE_K_TYPEDEF
DTRACE_TYPE_K_VOLATILE
DTRACE_TYPE_K_CONST
DTRACE_TYPE_K_RESTRICT
The type encoding returned in the dtep argument to the dtrace_type_encoding() function has the following type:
typedef struct dtrace_type_encoding {
uint_t dte_format; /* data format */
uint_t dte_offset; /* offset of value in bits */
uint_t dte_bits; /* size of storage in bits */
} dtrace_type_encoding_t;
For an integer type, one or more of the following flags may be set in the dte_format member of this structure:
DTRACE_TYPE_INT_SIGNED /* int is signed (On failure, unsigned) */
DTRACE_TYPE_INT_CHAR /* character display format */
DTRACE_TYPE_INT_BOOL /* boolean display format */
DTRACE_TYPE_INT_VARARGS /* varargs display format */
For a floating point type, dte_format will be one of the following values:
DTRACE_TYPE_FP_SINGLE /* IEEE 32-bit float encoding */
DTRACE_TYPE_FP_DOUBLE /* IEEE 64-bit float encoding */
DTRACE_TYPE_FP_CPLX /* Complex encoding */
DTRACE_TYPE_FP_DCPLX /* Double complex encoding */
DTRACE_TYPE_FP_LDCPLX /* Long double complex encoding */
DTRACE_TYPE_FP_LDOUBLE /* Long double encoding */
DTRACE_TYPE_FP_INTRVL /* Interval (2x32-bit) encoding */
DTRACE_TYPE_FP_DINTRVL /* Double interval (2x64-bit) encoding */
DTRACE_TYPE_FP_LDINTRVL /* Long double interval (2x128-bit) encoding */
DTRACE_TYPE_FP_IMAGRY /* Imaginary (32-bit) encoding */
DTRACE_TYPE_FP_DIMAGRY /* Long imaginary (64-bit) encoding */
DTRACE_TYPE_FP_LDIMAGRY /* Long double imaginary (128-bit) encoding */
The union or structure member information returned in the mip argument to the dtrace_type_member_info() function has the following type:
typedef struct dtrace_type_membinfo {
dtrace_typeinfo_t dtm_type; /* type of struct or union member */
ulong_t dtm_offset; /* offset of member in bits */
} dtrace_type_membinfo_t;
The following example shows how you can use the dtrace_type_name() and dtrace_type_visit() functions to print the members and offsets of a user-defined struct:
#include <dtrace.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
static dtrace_hdl_t *g_dtp;
static char *embed_type = ""
"struct bar"
"{"
" int a1;"
" char a2;"
" char a3;"
" double a4;"
"}"
"";
static char *my_type = ""
"struct foo"
"{"
" unsigned int b1;"
" double b2;"
" float b3;"
" struct bar b4;"
"}"
"";
static void
fatal(const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
(void) vfprintf(stderr, fmt, ap);
if (fmt[strlen(fmt) - 1] != '\n')
(void) fprintf(stderr, ": %s\n",
dtrace_errmsg(g_dtp, dtrace_errno(g_dtp)));
exit(EXIT_FAILURE);
}
static int
cb(dtrace_hdl_t *dtp, dtrace_typeinfo_t *tip, const char *name,
ulong_t offset, int depth, void *arg)
{
char *buf;
int len;
int i;
if ((len = dtrace_type_name(dtp, tip, NULL, 0)) < 0)
fatal("dtrace_type_name()");
if ((buf = malloc(len + 1)) == NULL)
fatal("malloc() failed\n");
if (dtrace_type_name(dtp, tip, buf, len + 1) < 0)
fatal("dtrace_type_name()");
for (i = 0; i < depth; i++)
printf("\t");
printf("0x%x %s %s\n", offset / NBBY, buf, name);
free(buf);
return (0);
}
int
main(int argc, char **argv)
{
int err;
dtrace_typeinfo_t dti;
if ((g_dtp = dtrace_open(DTRACE_VERSION, 0, &err)) == NULL)
fatal("cannot open dtrace library: %s\n",
dtrace_errmsg(NULL, err));
if (dtrace_type_strcompile(g_dtp, embed_type, &dti) != 0)
fatal("dtrace_type_strcompile failed");
if (dtrace_type_strcompile(g_dtp, my_type, &dti) != 0)
fatal("dtrace_type_strcompile failed");
dtrace_type_visit(g_dtp, &dti, cb, NULL);
dtrace_close(g_dtp);
return (0);
}
See attributes(7) for descriptions of the following attributes:
|
libdtrace(3LIB), dtrace_errno(3DTRACE), dtrace_lookup_by_type(3DTRACE), dtrace_symbol_type(3DTRACE), dtrace_type_strcompile(3DTRACE), dtrace_type_fcompile(3DTRACE)