---

2.1 Option Structure ¶

Data Type: MU_OPT ¶

This structure specifies a single option, the arguments the option takes, and the actions to perform when the option is found. If all fields are 0, that will indicate that this is the end of the options list.

Unless otherwise specified, these fields may be used both in regular options and suboptions. If an option takes suboptions as arguments, there are some fields which it may not use. Likewise, if an option does not take suboptions as arguments, there are a few fields which it may not use. See below for details. See Parsing Suboptions for more information on suboptions.

const char *category

This field, if used, is a category for the options following the one in which this field appears. It has no effect on option parsing, only on help and man output (see Formatting Help). This field may not contain newlines (‘\n’).

If this field is the empty string, the following options will be separated by a newline in help output, and it will have no effect in man page output.

If this field is used, it must be the only field used. You may not set any other fields if this field is set.

For an example of how this field is used, see Formatting Help.

const char *short_opt

This is the short option character if any, possibly including aliases, or NULL if this option does not have a short option equivalent.

You may specify multiple aliases by simply including more characters in the short_opt (see Aliases for Options and Environment Variables). Note that if short_opt is not NULL, it must be terminated by a null byte.

This field must not be used in suboptions (see Parsing Suboptions).

const char *long_opt

This is the long option string (without leading dashes), or NULL if this option does not have a short option equivalent. long_opt must not contain the ‘=’ character, because that is used for passing arguments.

You may specify aliases separated by ‘|’ (see Aliases for Options and Environment Variables).

This field must not be used in suboptions (see Parsing Suboptions).

When matching against long_opt, abbreviation is allowed as long as it is unambiguous.

const char *subopt_name

This is the name of the suboption. Like long_opt, it may not contain the ‘=’ character. Also like long_opt, matching allows abbreviation as long as it is not ambiguous.

You may specify aliases separated by ‘|’ (see Aliases for Options and Environment Variables).

This field must only be used in suboptions (see Parsing Suboptions).

const char *env_var

This is the name of an environment variable. Environment variables act exactly like options, except that they are passed in the environment rather than on the command line. Like long_opt, env_var must not contain the ‘=’ character, because that is used for indicating the value of an environment variable.

Unlike long_opt and subopt_name (above), abbreviation is not allowed.

You may specify aliases separated by ‘|’ (see Aliases for Options and Environment Variables).

See Parsing the Environment for more information about parsing the environment with mu_parse_opts and (libc)Environment Variables for more information on environment variables in general.

enum MU_OPT_HAS_ARG has_arg

This specifies whether the option takes an argument or not, and whether the argument is optional or required if the option does take an argument. has_arg can have the value MU_OPT_NONE if the option takes no argument, MU_OPT_OPTIONAL if the option may optionally take an argument, or MU_OPT_REQUIRED if the option requires an argument. See Option Arguments for more information on how required and optional arguments are parsed and handled differently.

enum MU_OPT_ARG_TYPE arg_type

The type of the argument if has_arg is not MU_OPT_NONE. See Option Argument Types.

int negatable

If this is nonzero, the option may be negated. For short options, this means using ‘+’ instead of ‘-’, and for long options and suboptions, it means prefixing the option with ‘no-’ or the specified negation prefixes (see Negation Prefixes). Environment variables may not be negated. See Negatable Options for more details.

This field may only be used if has_arg is MU_OPT_NONE.

int *found_opt

If found_opt is not NULL, *found_opt will be set to 1 if the option was found, or 0 if the option was not found.

int *found_arg

If found_arg is not NULL, *found_arg will be set to 1 if an argument to the option was found, or 0 if no argument was found.

void *arg

If arg is not NULL, *arg will be set to the argument if an argument was found. To test if an argument was found, use found_arg. The type of the argument is determined by arg_type (see Option Argument Types).

This field must only be used if has_arg is not MU_OPT_NONE and arg_type is not MU_OPT_SUBOPT (see Option Arguments and Parsing Suboptions).

int bool_default

long int_default

double float_default

const char *string_default

FILE *file_default

DIR *dir_default

int enum_default

The default values for *arg (see above) if the option is not found. bool_default should be used for arguments of type MU_OPT_BOOL, int_default should be used for arguments of type MU_OPT_INT and so on. See Option Argument Types for more information.

These fields may only be used if has_arg is not MU_OPT_NONE.

const char **argstr

If argstr in not NULL, *argstr will be set to the raw, unprocessed argument unless otherwise specified in Option Argument Types. *argstr is equal to *arg if and only if arg_type is MU_OPT_STRING.

This field must only be used if has_arg is not MU_OPT_NONE and arg_type is not MU_OPT_SUBOPT (see Option Arguments and Parsing Suboptions).

int (*callback_none) (void *, char *)

int (*callback_negatable) (int, void *, char *)

int (*callback_bool) (int, int, void *, char *)

int (*callback_int) (int, long, void *, char *)

int (*callback_float) (int, double, void *, char *)

int (*callback_string) (int, const char *, void *, char *)

int (*callback_file) (int, const char *, FILE *, void *, char *)

int (*callback_directory) (int, const char *, DIR *, void *, char *)

int (*callback_enum) (int, int, void *, char *)

int (*callback_subopt) (int, void *, char *)

If the corresponding callback for arg_type is set (see Option Argument Types), it will be called when the option is found. See Option Callbacks for a description of the arguments these callbacks take and their return values.

Note: only one of the callbacks may be set at a time.

callback_none may only be used if has_arg is MU_OPT_NONE and negatable is zero. callback_negatable may only be used if has_arg is MU_OPT_NONE and negatable is nonzero.

void *cb_data

The data argument to pass to the above callbacks. See Option Callbacks.

This field must not be used if arg_type is MU_OPT_SUBOPT (see Parsing Suboptions and Option Argument Types).

int (*cb_data_destructor) (void *data)

If cb_data contains dynamically allocated data or anything else that needs to be released back to the system (e.g., file descriptors), set cb_data_destructor to a function which will release all of that data, including cb_data itself if it was dynamically allocated as well. If an error occurred, e.g., when closing a file descriptor, cb_data_destructor should return nonzero.

As a simple example, if cb_data was dynamically allocated but does not contain dynamically allocated data, you can set this to a function which will call free(data) and return 0.

This field must not be used if arg_type is MU_OPT_SUBOPT (see Parsing Suboptions and Option Argument Types).

long ibound.lower

long ibound.upper

Lower and upper bounds (inclusive) for integer arguments. If you don’t want any bounds, set ibound.lower to LONG_MIN and ibound.upper to LONG_MAX.

These fields must only be used if arg_type is MU_OPT_INT (see Option Argument Types).

double fbound.lower

double fbound.upper

Lower and upper bounds (inclusive) for floating point arguments. If you don’t want any bounds, set fbound.lower to -HUGE_VAL and fbound.upper to HUGE_VAL.

These fields must only be used if arg_type is MU_OPT_FLOAT (see Option Argument Types).

const char *file_mode

The file mode to pass to fopen when opening a file argument. See (libc)Opening Streams.

This field must only be used if arg_type is MU_OPT_FILE (see Option Argument Types).

const MU_ENUM_VALUE *enum_values

The enumeration specification. See Parsing Enumerated Arguments to Options for more information.

This field must only be used if arg_type is MU_OPT_ENUM (see Option Argument Types).

int enum_case_match

If this is nonzero, enumerated arguments will be matched against the values in enum_values case sensitively. Otherwise, matching will be case insensitive. See Parsing Enumerated Arguments to Options for more information.

This field must only be used if arg_type is MU_OPT_ENUM (see Option Argument Types).

const MU_OPT *subopts

This is a list of valid suboptions for this option. See Parsing Suboptions.

This field must only be used if arg_type is MU_OPT_SUBOPT (see Option Argument Types).

const char *arg_help

This is a string which will be displayed in the help message as the argument for your option (see Formatting Help). For example, ‘FILE’, ‘NAME’, or, if you’re not feeling very imaginative, ‘ARG’. This field may not contain newlines (‘\n’).

If you leave this as NULL, a default will be chosen based on arg_type (see Option Argument Types).

const char *help

The full help text for your option, used when formatting the help message (see Formatting Help). This text may make references to the string passed in arg_help. There should be no newlines in this string (even if it is quite long²) unless you really want a line break in a certain place. Normally, you should just let line wrapping happen automatically.

If this field is left as NULL, the option will not be documented in either help or man output (see Formatting Help). Of course, the option will still be parsed as usual.

const char *negated_help

The help text for the negated option. If this is left as NULL and help (see above) is not NULL, it will default to ‘negate option’, where option is the non-negated option or suboption (including aliases). However, if negated_help is NULL and help is also NULL, neither the option nor the negated option will be documented. If negated_help is non-NULL but help is NULL, only the negated option will be documented.

This field may only be used if has_arg is MU_OPT_NONE and negatable is nonzero.