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 willOR
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 optionc
is detected in theargv
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 returnMDB_LISTCB_OK
. Otherwise, <func> should print an error message withmdb_warn
() and returnMDB_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 theuintptr_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 theboolean_t
referenced by flag, and the integer argument following c in theuintptr_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 theuint64_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.