dtrace_printf_create, dtrace_printa_create, dtrace_format_lookup, dtrace_printf_format, dtrace_fprinta, dtrace_fprintf, dtrace_system, dtrace_freopen - DTrace formatted output interfaces
cc [ flag... ] file... -ldtrace [ library... ]
#include <dtrace.h>
void *dtrace_printf_create(dtrace_hdl_t *dtp, const char *s)
void *dtrace_printa_create(dtrace_hdl_t *dtp, const char *s)
void *dtrace_format_lookup(dtrace_hdl *dtp, int fmtid);
size_t dtrace_printf_format(dtrace_hdl_t *dtp, void *fmtdata, char *s,
size_t len)
int dtrace_fprintf(dtrace_hdl_t *dtp, FILE *fp, void *fmtdata,
const dtrace_probedata_t *data, const dtrace_recdesc_t *recp,
uint_t nrecs, const void *buf, size_t len)
int dtrace_fprinta(dtrace_hdl_t *dtp, FILE *fp, void *fmtdata,
const dtrace_probedata_t *data, const dtrace_recdesc_t *recp,
uint_t nrecs, const void *buf, size_t len)
int dtrace_system(dtrace_hdl_t *dtp, FILE *fp, void *fmtdata,
const dtrace_probedata_t *data, const dtrace_recdesc_t *recp,
uint_t nrecs, const void *buf, size_t len)
int dtrace_freopen(dtrace_hdl_t *dtp, FILE *fp, void *fmtdata,
const dtrace_probedata_t *data, const dtrace_recdesc_t *recp,
uint_t nrecs, const void *buf, size_t len)
These interfaces are used to process formatted output from D programs.
The dtrace_fprintf(), dtrace_fprinta(), dtrace_system() and dtrace_freopen() functions process the data from the printf(), printa(), system() and freopen() actions, respectively, in a D program. These functions take the following arguments:
DTrace handle returned by the dtrace_open(3DTRACE) function
File pointer to which the output will be written.
Opaque data structure returned by the dtrace_printf_create() function, or by the dtrace_printa_create() function in the case of the dtrace_fprinta() function
Pointer to the dtrace_probedata_t structure for this probe firing
Pointer to the record description for the printf(), printa(), freopen() or system() action.
Maximum number of records available to be consumed by the actions for the recp argument.
Pointer to the raw data for this probe firing
Size of the data for this enabled probe
The dtrace_format_lookup() function looks up the format data for this record. This function takes the following arguments:
DTrace handle returned by the dtrace_open(3DTRACE) function
Identifier for this format data. The identifier is stored in the dtrd_format member of the dtrace_recdesc_t structure.
The dtrace_printf_create() and the dtrace_printa_create() functions generate format data from a string. These functions take the following arguments:
DTrace handle returned by the dtrace_open(3DTRACE) function.
The dtrace_printf_format() extracts the format string and a writes it into a buffer, subject to a maximum length. This function takes the following arguments:
Opaque data structure from which the function extracts the format string. The fmtdata structure is returned by the dtrace_printf_create() function, or by the dtrace_printa_create() function in the case of the dtrace_fprinta() function
The maximum length in bytes of the format string.
The buffer into which the function writes the format string.
DTrace handle returned by the dtrace_open(3DTRACE) function
On successful completion, the dtrace_fprintf(), dtrace_fprinta(), dtrace_system(), and dtrace_freopen() functions return the number of records consumed for this action, nrecs, which may be less than the number of records passed to these functions. Otherwise, these function 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_printf_format() function returns the size of the format string, regardless of the value of _len_. Otherwise, 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 dtrace_printf_create(), dtrace_printa_create() and dtrace_format_lookup() functions return a pointer to format data that can be passed to the dtrace_fprintf(), dtrace_fprinta(), dtrace_freopen(), or dtrace_system() functions. Otherwise these functions return NULL 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_printf_create() and dtrace_printa_create() functions will fail if:
The dtp or s argument is NULL.
The system was unable to allocate memory while processing this function.
The string, s is an invalid format string.
The dtrace_printf_format() function will fail if:
The fmtdata argument is NULL.
The dtrace_fprintf(), dtrace_fprinta(), dtrace_freopen() and dtrace_system() functions will fail if:
The dtp, fmtdata, recp, or buf argument is NULL.
The nrecs argument is less than the actual number of records to be consumed by this action.
The len argument is smaller than the actual size of the data recorded for this action.
The following example shows how you can use the dtrace_fprintf() and dtrace_format_lookup() functions to process printf() function statements from a D program:
#include <dtrace.h>
#include <errno.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <strings.h>
#include <unistd.h>
static dtrace_hdl_t *g_dtp;
static char *g_prog = ""
"BEGIN"
"{"
" printf(\"%d %d %d\\n\", 4, 5, 6);"
" printf(\"%s %s %s\\n\", \"foo\", \"bar\", \"baz\");"
" exit(0);"
"}";
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
chewrec(const dtrace_probedata_t *data, const dtrace_recdesc_t *rec,
void *arg)
{
return (DTRACE_CONSUME_THIS);
}
static int
chew(const dtrace_probedata_t *data, void *arg)
{
dtrace_eprobedesc_t *edesc = data->dtpda_edesc;
dtrace_recdesc_t *recp;
int i = 0, n;
while (i < edesc->dtepd_nrecs) {
recp = &edesc->dtepd_rec[i];
if (recp->dtrd_action == DTRACEACT_PRINTF) {
if ((n = dtrace_fprintf(g_dtp, stdout,
dtrace_format_lookup(g_dtp, recp->dtrd_format),
data, recp, edesc->dtepd_nrecs - i,
data->dtpda_data, edesc->dtepd_size)) < 0)
fatal("error processing printf()");
if (n > 0)
i += n;
} else if (recp->dtrd_action == DTRACEACT_EXIT) {
i++;
}
}
return (DTRACE_CONSUME_NEXT);
}
int
main()
{
dtrace_prog_t *prog;
dtrace_proginfo_t info;
int err;
if ((g_dtp = dtrace_open(DTRACE_VERSION, 0, &err)) == NULL)
fatal("cannot open dtrace library: %s\n",
dtrace_errmsg(NULL, err));
if ((prog = dtrace_program_strcompile(g_dtp, g_prog,
DTRACE_PROBESPEC_NAME, 0, 0, NULL)) == NULL)
fatal("invalid program");
if (dtrace_program_exec(g_dtp, prog, &info) == -1)
fatal("failed to enable probes");
if (dtrace_setopt(g_dtp, "bufsize", "512k") == -1)
fatal("failed to set bufsize");
if (dtrace_go(g_dtp) != 0)
fatal("dtrace_go()");
while (1) {
int done = 0;
dtrace_sleep(g_dtp);
switch (dtrace_work(g_dtp, stdout, chew, chewrec,
NULL)) {
case DTRACE_WORKSTATUS_DONE:
done = 1;
break;
case DTRACE_WORKSTATUS_OKAY:
break;
default:
fatal("processing aborted");
}
if (done)
break;
}
if (dtrace_stop(g_dtp) == -1)
fatal("dtrace_stop()");
dtrace_close(g_dtp);
return (0);
}
See attributes(7) for descriptions of the following attributes:
|
libdtrace(3LIB), dtrace_errno(3DTRACE), dtrace_open(3DTRACE)