Go to main content

Oracle® Solaris Modular Debugger Guide

Exit Print View

Updated: October 2019
 
 

MDB 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. If the usage string begins with "|", this indicates that the dcmd's input must be from a pipe.

A string which describes how the dcmd may be invoked. If NULL, this is treated as an empty string. Certain aspects of the string determine how the dcmd must be invoked:

Begins with ':'

The dcmd requires an address (flags must include DCMD_ADDRSPEC)

Begins with '?'

The dcmd optionally takes an address (flags may include DCMD_ADDRSPEC)

Begins with '|'

The dcmd must have input from a pipe (flags must include DCMD_ADDRSPECand DCMD_PIPE)

Begins with neither ':' nor '?' nor '|'

The dcmd does not take an address (flags must not include DCMD_ADDRSPEC)

Ends with '|'

The dcmd supports outputting into a pipe (flags may include DCMD_PIPE_OUT)

Does not end with '|'

The dcmd does not support outputting into a pipe (flags must not include DCMD_PIPE_OUT)

The string is empty

Other than ':', '?', '|', and whitespace. No arguments are allowed (argc must be zero). The specified characters will be stripped from the usage string before it is printed.

These restrictions will be reflected in the usage message printed for the dcmd. If MDB_MI_ENFORCE_USAGE is set in the mdb_modinfo_t's mi_flags field, and the "nostrict" MDB option is not set, these restrictions will be enforced by MDB before invoking the dcmd.

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.