mdb_getopts() Function

int mdb_getopts(int argc, const mdb_arg_t *argv, ...);

Parse and process options and option arguments from the specified argument array (argv). The argc parameter denotes the length of the argument array. This function processes each argument in order, and stops and returns the array index of the first argument that could not be processed. If all arguments are processed successfully, argc is returned.

Following the argc and argv parameters, the mdb_getopts() function accepts a variable list of arguments describing the options that are expected to appear in the argv array. Each option is described by an option letter (char argument), an option type (uint_t argument), and one or two additional arguments, as shown in the table below. The list of option arguments is terminated with a NULL argument. The type should be one of the following:

MDB_OPT_SETBITS

The option will OR the specified bits into a flag word. The option is described by these parameters:

char c, uint_t type, uint_t bits, uint_t *p

If type is MDB_OPT_SETBITS and option c is detected in the argv list, the debugger will OR bits into the integer referenced by pointer p.

MDB_OPT_CLRBITS

The option clears the specified bits from a flag word. The option is described by these parameters:

char c, uint_t type, uint_t bits, uint_t *p

If type is MDB_OPT_CLRBITS and option c is detected in the argv list, the debugger clears bits from the integer referenced by pointer p.

MDB_OPT_LISTCB

The option will separate any arguments into ','-separated portions, and, call the callback function on each portion. The option is described by these parameters:

char c, uint_t type, mdb_opt_listcb_f *func, void *arg

Where mdb_opt_listcb_f() is a function type:

typedef int mdb_opt_listcb_f(char c, char *buf, size_t len, void
*arg)

If type is MDB_OPT_LISTCB and option c is detected in the argv list, the string argument is split up into ','-separated pieces, each piece is copied into a temporary array, and <func> is called with <c>, a pointer to the temporary copy, the length of the temporary copy (including the terminating NULL), and <arg>. If successful, <func> should return MDB_LISTCB_OK. Otherwise, <func> should print an error message with mdb_warn() and return MDB_LISTCB_FAIL, which will cause option processing to stop.

MDB_OPT_STR

The option accepts a string argument. The option is described by these parameters:

char c, uint_t type, const char **p

If type is MDB_OPT_STR and option c is detected in the argv list, the debugger stores a pointer to the string argument following c in the pointer referenced by p.

MDB_OPT_UINTPTR

The option accepts a uintptr_t argument. The option is described by these parameters:

char c, uint_t type, uintptr_t *p

If type is MDB_OPT_UINTPTR and option c is detected in the argv list, the debugger stores the integer argument following c in the uintptr_t referenced by p.

MDB_OPT_UINTPTR_SET

The option accepts a uintptr_t argument. The option is described by these parameters:

char c, uint_t type, boolean_t *flag, uintptr_t *p

If type is MDB_OPT_UINTPTR_SET and option c is detected in the argv list, the debugger stores the value '1' (TRUE) into the boolean_t referenced by flag, and the integer argument following c in the uintptr_t referenced by p.

MDB_OPT_UINT64

The option accepts a uint64_t argument. The option is described by these parameters:

char c, uint_t type, uint64_t *p

If type is MDB_OPT_UINT64 and option c is detected in the argv list, the debugger stores the integer argument following c in the uint64_t referenced by p.

For example, the following source code:

int
dcmd(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv)
{
        uint_t opt_v = FALSE;
        const char *opt_s = NULL;

        if (mdb_getopts(argc, argv,
            'v', MDB_OPT_SETBITS, TRUE, &opt_v,
            's', MDB_OPT_STR, &opt_s, NULL) != argc)
                return (DCMD_USAGE);

        /* ... */
}

demonstrates how mdb_getopts() might be used in a dcmd to accept a boolean option "-v" that sets the opt_v variable to TRUE, and an option "-s" that accepts a string argument that is stored in the opt_s variable. The mdb_getopts() function also automatically issues warning messages if it detects an invalid option letter or missing option argument before returning to the caller. The storage for argument strings and the argv array is automatically garbage-collected by the debugger upon completion of the dcmd.