Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_printf_format (3DTRACE)

Name

dtrace_printf_create, dtrace_printa_create, dtrace_format_lookup, dtrace_printf_format, dtrace_fprinta, dtrace_fprintf, dtrace_system, dtrace_freopen - DTrace formatted output interfaces

Synopsis

     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)

Description

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:

dtp

DTrace handle returned by the dtrace_open(3DTRACE) function

fp

File pointer to which the output will be written.

fmtdata

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

data

Pointer to the dtrace_probedata_t structure for this probe firing

recp

Pointer to the record description for the printf(), printa(), freopen() or system() action.

nrecs

Maximum number of records available to be consumed by the actions for the recp argument.

buf

Pointer to the raw data for this probe firing

len

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:

dtp

DTrace handle returned by the dtrace_open(3DTRACE) function

fmtid

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:

dtp

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:

fmtdata

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

len

The maximum length in bytes of the format string.

buf

The buffer into which the function writes the format string.

dtp

DTrace handle returned by the dtrace_open(3DTRACE) function

Return Values

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.

Errors

The dtrace_printf_create() and dtrace_printa_create() functions will fail if:

EINVAL

The dtp or s argument is NULL.

EDT_NOMEM

The system was unable to allocate memory while processing this function.

EDT_COMPILER

The string, s is an invalid format string.

The dtrace_printf_format() function will fail if:

EINVAL

The fmtdata argument is NULL.

The dtrace_fprintf(), dtrace_fprinta(), dtrace_freopen() and dtrace_system() functions will fail if:

EINVAL

The dtp, fmtdata, recp, or buf argument is NULL.

EDT_DMISMATCH

The nrecs argument is less than the actual number of records to be consumed by this action.

EDT_DOFFSET

The len argument is smaller than the actual size of the data recorded for this action.

Examples

Example 1 Using the dtrace_fprintf() and dtrace_format_lookup() Functions to Process printf() function Statements From a D Program

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);
}

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), dtrace_open(3DTRACE)