dtrace_program_link, dtrace_program_header - DTrace USDT probe support
cc [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>
int dtrace_program_header(dtrace_hdl_t *dtp, FILE *out,
const char *fname)
int dtrace_program_link(dtrace_hdl_t *dtp, dtrace_prog_t *pgp,
uint_t dflags, const char *file, int objc, char *const objv[])
The dtrace_program_header() and dtrace_program_link() functions support the creation of user-defined providers (USDT providers) for applications.
The dtrace_program_header() function performs the following actions:
The dtrace_program_header() function generates a C header file with the name, fname, containing the macro definitions for a USDT provider. This header file is written to the out argument.
The dtrace_program_header() function writes the header file to the out argument.
The dtrace_program_header() function calls the dtrace_program_strcompile(3DTRACE) or dtrace_program_fcompile(3DTRACE) function to compile the D language provider definition.
The information about the USDT provider is stored in the DTrace handle, dtp
The dtrace_program_link() function performs the following actions:
Given a compiled USDT provider definition in the pgp argument, the function processes the object files specified in the objv argument to create the probe points for that provider. The count of the files is maintained in the objc argument.
The function then creates an ELF object file containing the provider definition as an encapsulated DTrace Object Format (DOF) object. The name of the file is contained in the file argument.
Upon successful completion, these functions return 0. Otherwise 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.
The dtrace_program_header() function will fail if:
The dtp or out parameter is NULL.
The dtrace_program_link() function will fail if:
Either the dtp or file parameter is NULL, or the objv parameter is NULL even though the objc parameter is greater than 0.
The linker encountered an error.
Given the following USDT provider file, probes.d:
provider foo {
probe bar(int);
probe baz(int);
};
#pragma D attributes Evolving/Evolving/Common provider foo provider
#pragma D attributes Private/Private/Common provider foo module
#pragma D attributes Private/Private/Common provider foo function
#pragma D attributes Evolving/Evolving/Common provider foo name
#pragma D attributes Evolving/Evolving/Common provider foo args
The following program would generate the header file, probes.h:
#include <dtrace.h>
#include <stdio.h>
#include <stdlib.h>
static dtrace_hdl_t *g_dtp;
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);
}
int
main()
{
dtrace_prog_t *prog;
int err;
FILE *fp, *ofp;
char *provider_desc = "probes.d";
char *header = "probes.h";
if ((fp = fopen(provider_desc, "r")) == NULL)
fatal("cannot open %s", provider_desc);
if ((ofp = fopen(header, "w")) == NULL)
fatal("cannot open %s", header);
if ((g_dtp = dtrace_open(DTRACE_VERSION, DTRACE_O_NODEV,
&err)) == NULL)
fatal("cannot open dtrace library: %s\n",
dtrace_errmsg(NULL, err));
if ((prog = dtrace_program_fcompile(g_dtp, fp,
DTRACE_C_ZDEFS, 0, NULL)) == NULL)
fatal("invalid program");
if (dtrace_program_header(g_dtp, ofp, header) < 0)
fatal("dtrace_program_header()");
dtrace_close(g_dtp);
fclose(fp);
fclose(ofp);
return (0);
}
Example 2 Using the dtrace_program_link() Function
Given the following program as foo.c, compiled into object file foo.o ("cc -c -m64 foo.c"):
#include "probes.h"
void *
func(int size)
{
if (FOO_BAR_ENABLED()) {
if (size == 5) {
FOO_BAR(size);
}
}
if (FOO_BAZ_ENABLED()) {
if (size != 5) {
FOO_BAZ(size);
}
}
return (NULL);
}
The following program would create the probe points in the object file, foo.o and generate the DOF object file, probes.o from the USDT provider file, probes.d:
#include <dtrace.h>
#include <stdio.h>
#include <stdlib.h>
static dtrace_hdl_t *g_dtp;
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);
}
int
main(int argc, char **argv)
{
dtrace_prog_t *prog;
int err;
FILE *fp;
char *provider_desc = "probes.d";
char *provider_obj = "probes.o";
char *objv[] = {"foo.o"};
if ((fp = fopen(provider_desc, "r")) == NULL)
fatal("cannot open %s", provider_desc);
if ((g_dtp = dtrace_open(DTRACE_VERSION,
DTRACE_O_NODEV | DTRACE_O_LP64, &err)) == NULL)
fatal("cannot open dtrace library: %s\n",
dtrace_errmsg(NULL, err));
if ((prog = dtrace_program_fcompile(g_dtp, fp,
DTRACE_C_ZDEFS, 0, NULL)) == NULL)
fatal("invalid program");
if (dtrace_program_link(g_dtp, prog, 0, provider_obj, 1,
objv) < 0)
fatal("dtrace_program_link()");
dtrace_close(g_dtp);
fclose(fp);
return (0);
}
See attributes(7) for descriptions of the following attributes:
|
libdtrace(3LIB), dtrace_errno(3DTRACE), dtrace_program_fcompile(3DTRACE)