Dcmd Definitions

int dcmd(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv);

A dcmd is implemented with a function similar to the dcmd() declaration. This function receives four arguments and returns an integer status. The function arguments are:

addr

Current address, also called dot. At the start of the dcmd, this address corresponds to the value of the dot “.” variable in the debugger.

flags

Integer containing the logical OR of one or more of the following flags:

DCMD_ADDRSPEC

An explicit address was specified to the left of ::dcmd.

DCMD_LOOP

The dcmd was invoked in a loop using the ,count syntax, or the dcmd was invoked in a loop by a pipeline.

DCMD_LOOPFIRST

This invocation of the dcmd function corresponds to the first loop or pipeline invocation.

DCMD_PIPE

The dcmd was invoked with input from a pipeline.

DCMD_PIPE_OUT

The dcmd was invoked with output set to a pipeline.

As a convenience, the DCMD_HDRSPEC() macro is provided to allow a dcmd to test its flags to determine if it should print a header line (that is, it was not invoked as part of a loop, or it was invoked as the first iteration of a loop or pipeline).

argc

Number of arguments in the argv array.

argv

Array of arguments specified to the right of ::dcmd on the command line. These arguments can be either strings or integer values.

The dcmd function is expected to return one of the following integer values, defined in <sys/mdb_modapi.h>.

DCMD_OK

The dcmd completed successfully.

DCMD_ERR

The dcmd failed for some reason.

DCMD_USAGE

The dcmd failed because invalid arguments were specified. When this value is returned, the dcmd usage message (described below) prints automatically.

DCMD_NEXT

The next dcmd definition (if one is present) is automatically invoked with the same arguments.

DCMD_ABORT

The dcmd failed, and the current loop or pipeline should be aborted. This is like DCMD_ERR, but indicates that no further progress is possible in the current loop or pipe.

Each dcmd consists of a function defined according to the example dcmd() prototype, and a corresponding mdb_dcmd_t structure, as defined in <sys/mdb_modapi.h>. This structure consists of the following fields:

const char *dc_name

The string name of the dcmd, without the leading “::”. The name cannot contain any of the MDB meta-characters, such as $ or `.

const char *dc_usage

An optional usage string for the dcmd, to be printed when the dcmd returns DCMD_USAGE. For example, if the dcmd accepts options -a and -b, dc_usage might be specified as “[-ab]”. If the dcmd accepts no arguments, dc_usage can be set to NULL. If the usage string begins with “:”, this is shorthand for indicating that the dcmd requires an explicit address (that is, it requires DCMD_ADDRSPEC to be set in its flags parameter). If the usage string begins with “?”, this indicates that the dcmd optionally accepts an address. These hints modify the usage message accordingly.

const char *dc_descr

A mandatory description string, briefly explaining the purpose of the dcmd. This string should consist of only a single line of text.

mdb_dcmd_f *dc_funcp

A pointer to the function that will be called to execute the dcmd.

void (*dc_help)(void)

An optional function pointer to a help function for the dcmd. If this pointer is not NULL, this function will be called when the user executes ::help dcmd. This function can use mdb_printf() to display further information or examples.