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:
Current address, also called dot. At the start of the dcmd, this address corresponds to the value of the dot “.” variable in the debugger.
Integer containing the logical OR of one or more of the following flags:
An explicit address was specified to the left of ::dcmd.
The dcmd was invoked in a loop using the ,count syntax, or the dcmd was invoked in a loop by a pipeline.
This invocation of the dcmd function corresponds to the first loop or pipeline invocation.
The dcmd was invoked with input from a pipeline.
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).
Number of arguments in the argv array.
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>.
The dcmd completed successfully.
The dcmd failed for some reason.
The dcmd failed because invalid arguments were specified. When this value is returned, the dcmd usage message (described below) prints automatically.
The next dcmd definition (if one is present) is automatically invoked with the same arguments.
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.