dtrace_work() Function

The dtrace_work() function performs all of the work that must to be done periodically by a consumer. This work corresponds to the statusrate, switchrate, and aggrate rates. The dtrace_work() function first calls dtrace_status() to determine the status of the trace and then calls dtrace_aggregate_snap() and dtrace_consume() to consume any aggregation buffer or principal buffer data. The dtrace_work() function is a wrapper around these three function calls and a DTrace consumer can call these three functions separately. For more information about the dtrace_aggregate_snap() function, see Periodic Processing of Aggregation.

dtrace_workstatus_t dtrace_work(dtrace_hdl_t *dtp, FILE *fp, dtrace_consume_probe_f *pfunc, dtrace_consume_rec_f *rfunc, void *arg)

The arguments to the dtrace_work() function are:

• The DTrace handle.

• A file handle for output.

• Two function pointers.

• An optional argument to be passed to the two function pointers. This argument can maintain any state between successive invocations of the functions.

The two function pointers passed to dtrace_work() in the Embedding DTrace in a Consumer are chew() and chewrec(). They are called while processing the data from the primary buffer. The following figure shows the layout of a primary buffer. For more information about the DTrace buffer mechanism, see DTrace Buffers and Buffering.

DTrace Primary Buffer

The EPID is the enabled probe ID, which maps to a specific clause in a D program and determines the length and layout of the data after the EPID.

In Embedding DTrace in a Consumer, for each EPID that is processed from the buffer, the chew() function is called. The data that corresponds to an EPID might consist of a number of records. For each record that is processed for an EPID, the chewrec() function is called. These two function pointers enable you to augment or replace the default format for this data provided by the libdtrace library.

The return value for these two functions pointers can be one of the following four values:

DTRACE_CONSUME_THIS

Indicates that the libdtrace library must consume the EPID or record. A consumer uses this value to augment the default behavior. In Embedding DTrace in a Consumer, both the chew() and chewrec() functions return DTRACE_CONSUME_THIS without adding any output.

DTRACE_CONSUME_NEXT

Indicates that the libdtrace library must proceed to the next EPID or record. In Embedding DTrace in a Consumer, the consumer processes the EPID or record itself. If the action specified in a record is an exit(), the chewrec() function extracts the exit code from the record and returns DTRACE_CONSUME_NEXT to indicate that the record has been processed.

DTRACE_CONSUME_ERROR

Indicates that an error has occurred while processing an EPID or record.

DTRACE_CONSUME_ABORT

Indicates that consumption of the buffer must be terminated.

If a record specifies an exit() function, the chewrec() function extracts the exit code. The function also outputs a newline after processing the final record for an EPID. The chew() function prints the information about the CPU on which the probe was fired, and the probe ID, function, and name for each EPID processed. It also handles the flowindent output processing if that option is specified.

The source for dtrace in the usr/src/cmd/dtrace/dtrace.c file provides good examples of the chew() and chewrec() functions.