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 theEPID
or record. A consumer uses this value to augment the default behavior. In Embedding DTrace in a Consumer, both thechew
() andchewrec
() functions returnDTRACE_CONSUME_THIS
without adding any output. -
DTRACE_CONSUME_NEXT
-
Indicates that the
libdtrace
library must proceed to the nextEPID
or record. In Embedding DTrace in a Consumer, the consumer processes theEPID
or record itself. If the action specified in a record is anexit
(), thechewrec
() function extracts the exit code from the record and returnsDTRACE_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.