Mu (Miscellaneous Utilities) ¶

1.1 Terms and Notation Used in this Manual ¶

There are several types of arguments dealt with in this manual: arguments to command line options; non-option, positional arguments passed on the command line; and parameters passed to functions. When we refer to arguments passed to command line options, we will use the term argument on its own. When we refer to non-option, positional arguments passed on the command line, we will use the term positional argument. When we refer to the value of an environment variable, we will use the term value. When we refer to parameters passed to functions, we will use the term parameter.

When referring to a field in a C struct or union, we will use the term field.

In examples, messages printed to standard output will be prefixed with “-|”, while messages printed to standard error will be prefixed with “error→”.

1.2 Using Mu in Your Program ¶

Mu is written in C, and currently no bindings exist for other languages. So (for now at least) you can only use Mu in C programs.

Several header files are provided by Mu. Each one provides a different category of functions. All header files are installed in the mu subdirectory. So to include, for example, compat.h, write #include <mu/compat.h>.

To link with the library, use -lmu as an argument to the linker.

Note: Since Mu is released under the terms of the GNU General Public License, you may not use it in proprietary programs. If your program links with Mu, it must be licensed under the GNU GPL or a compatible license. Please see GNU General Public License for more details.

Please note: Mu is not currently stable, and the API is subject to change. Feel free to use Mu, but please keep this in mind.

1.3 Reporting Bugs ¶

Please report bugs to the bug tracker at Savannah. You may also email bug reports to the libmu-bug@nongnu.org mailing list. See also the list information page for libmu-bug. Include enough information to reproduce the bug if possible, as well as the version of Mu, your machine architecture, operating system, etc. Make sure to read the documentation for the functions you are using, and ensure that you are using the functions correctly. You should also include any error messages if applicable, and a backtrace if you can. If possible, include a source file (preferably minimal) that causes the bug to occur.

If you are reporting a test failure (run by make check), include the file tests/testsuite.log in your report. Even if you’re not reporting a test failure, it can still be helpful to run make check and include tests/testsuite.log.

For more information on writing effective bug reports, I suggest reading Simon Tatham’s excellent essay, How to Report Bugs Effectively

You can also send reports for bugs in this manual itself to the bug tracker or mailing list.

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.

2.2 Aliases for Options and Environment Variables ¶

The fields long_opt, subopt_name, and env_var of the MU_OPT structure (see Option Structure) allow aliases separated by ‘|’. The short_opt field allows aliases to be specified as multiple characters in the string (which must be terminated by a null byte).

For example, the string ‘abc’, when specified as the short_opt field, indicates three equivalent short options: -a, -b, and -c. In the long_opt field, ‘foo|bar|baz’ would specify three equivalent long options: --foo, --bar, and --baz. The same goes for subopt_name and env_var (but see Parsing the Environment for more information on environment variable aliases).

Duplicate aliases are not allowed, and will be diagnosed as an error. For example, in the short_opt field, ‘abcb’ will be diagnosed because the ‘b’ is repeated. Likewise, ‘foo|bar|foo’ would be diagnosed in any of the long_option, subopt_name, or env_var fields. Empty aliases are diagnosed as well (including the entire string being empty). So ‘foo||bar’ would be diagnosed in any of the long_option, subopt_name, or env_var fields, because there is an empty alias between ‘foo’ and ‘bar’. In any of the same fields, in addition to short_opt, the empty string (‘’) will be diagnosed as well. Leave a field as NULL if you don’t want any options (or environment variables) of that type.

2.3 Negatable Options ¶

A negatable option is an option which can be specified later on the command line in a different form, to negate the effect of a previous specification. Short options are negated using ‘+’ rather than ‘-’ to specify the option. Long options and suboptions must be prefixed with ‘no-’ or the specified negation prefixes (see Negation Prefixes). For example,

$ prog --foo --no-foo

should act as though --foo were never specified. Only negatable options can be negated. For an option to be negatable, its negatable field must be set to a nonzero value (see Option Structure). Options that take arguments (i.e., options for which the has_arg field is not MU_OPT_NONE) may not be negated. Indeed, setting the negatable field to any value for an option which takes an argument results in undefined behavior.

Environment variables may not be negated. The reason for this is because it is not easy to control the order in which environment variables appear. Thus, if environment variable negation were allowed and FOO were a negatable environment variable,

$ FOO= NO_FOO= prog

may or may not act as though FOO were specified. So if an option for which the negatable field is nonzero also has a non-NULL env_var field, NO_FOO will be ignored. Note, however, that the callback_negatable callback should still be used (but it may be better not to use callbacks at all; see below). Rather than having an env_var field for a negatable option, it is instead better to make a separate environment variable that has a boolean value (see Option Argument Types).

Since environment variables may not be negated, specifying the negatable field for an environment variable which has no equivalent options is useless. Because of this, it is not allowed and will be diagnosed.

When option parsing is finished, the value that the found_opt field points to (if any) will be nonzero if the last instance of the option found on the command line was not negated, or zero if it was negated.

Negatable options should use the callback_negatable field if they are using a callback (see Option Callbacks), although it is usually preferable not to use a callback. Suppose you have a certain negatable option, and you want to, say, open a file when it is found. If you used a callback, you would need to open the file whenever value was nonzero, and then close it again when it is zero. Although in this case this would be fairly easy to implement (although far from ideal), it is still much better to simply wait until option parsing is finished, and then check the value that the found_opt field points to.

Here is an example illustrating how to parse negatable options:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

/* Print a message when we find the negatable option. Usually, we
   shouldn't use a callback for negatable options, but we are just
   using it to print a message. */
static int print_negatable(int value, void *data, char *err) {
  printf("    Found the negatable option, and it was%s negated.\n",
         value ? " not" : "");
  return 0;
}

int main(int argc, char **argv) {
  int found_negatable;
  int ret;
  const MU_OPT options[] = {
    {
     .short_opt          = "n",
     .long_opt           = "negatable",
     .has_arg            = MU_OPT_NONE,
     .negatable          = 1,
     .found_opt          = &found_negatable,
     .callback_negatable = print_negatable
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  /* Parse the options. */
  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  printf("It appears that the negatable option was%s given.\n",
         found_negatable ? "" : " not");

  return 0;
}

Here is the output of the above program:

$ ./option-negatable
-| It appears that the negatable option was not given.
$ ./option-negatable --negatable -n --no-negatable +n
-|     Found the negatable option, and it was not negated.
-|     Found the negatable option, and it was not negated.
-|     Found the negatable option, and it was negated.
-|     Found the negatable option, and it was negated.
-| It appears that the negatable option was not given.
$ ./option-negatable -n +n --negatable
-|     Found the negatable option, and it was not negated.
-|     Found the negatable option, and it was negated.
-|     Found the negatable option, and it was not negated.
-| It appears that the negatable option was given.

• Negation Prefixes

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x* */

/* Print a message when we find the negatable option. */
static int print_negatable(int value, void *data, char *err) {
  printf("    Found the negatable option, and it was%s negated.\n",
         value ? " not" : "");
  return 0;
}

int main(int argc, char **argv) {
  int ret;
  const MU_OPT options[] = {
    {
     .short_opt          = "n",
     .long_opt           = "negatable",
     .has_arg            = MU_OPT_NONE,
     .negatable          = 1,
     .callback_negatable = print_negatable
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);

  /* Set the negation prefixes. This must be done *before*
     mu_parse_opts() is called. */
  mu_opt_context_xset_no_prefixes(context, "negate-", "no-", "x", NULL);

  /* Now parse the options. */
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  return 0;
}

$ ./negation-prefixes --negatable
-|     Found the negatable option, and it was not negated.
$ ./negation-prefixes --negate-negatable
-|     Found the negatable option, and it was negated.
$ ./negation-prefixes --no-negatable
-|     Found the negatable option, and it was negated.
$ ./negation-prefixes --xnegatable
-|     Found the negatable option, and it was negated.
$ ./negation-prefixes --foo-negatable
error→ ./negation-prefixes: '--foo-negatable': invalid option

2.4 Option Arguments ¶

Options can take arguments and environment variables can have values (see Parsing the Environment). Some options and environment variables require arguments or values, while others may optionally take arguments or have values, while still others might take no arguments at all or not allow any values. Mu supports all of these types of options and environment variables through the has_arg field of the MU_OPT structure (see Option Structure).

Enumerated Type: enum MU_OPT_HAS_ARG ¶

MU_OPT_NONE ¶

This indicates that an option takes no arguments. If the MU_OPT_BUNDLE flag (see Option Parsing Flags) is not specified, then any text following a short option which doesn’t take an argument will be an error.³ An ‘=’ is an error in a long option that does not take an argument, because ‘=’ is used to specify arguments to long options.

*has_arg will always be set to 0 if has_arg is not NULL.

MU_OPT_OPTIONAL ¶

This indicates that an option may take an argument, but that the option doesn’t require an argument. Even if the MU_OPT_BUNDLE flag is passed (see Option Parsing Flags), short options with optional arguments may not be bundled except as the last option in a bundle. The reason for this is as follows: Suppose short option b takes an optional argument. And suppose short options a and c take no argument. Now what should -abc mean (assuming MU_OPT_BUNDLE was passed)? Is it three options without arguments, a, b, and c? Or is it two options, a and b, the latter of which taking an argument, ‘c’? It is in fact the latter, two options a and b, with b taking an argument, ‘c’. Note, however, that if b is specified as the last option like so: -acb, there is no ambiguity, because there is nothing following the b option (and if there is text following it in another argument, it will be treated as a positional argument; see below).

Short options taking an optional argument must have their arguments specified with the option itself. For example, if a short option, b, takes an optional argument, it must be specified as -barg, not -b arg. The reason for this is because -b arg could be a short option b with an argument arg, or a short option b with no argument, and a positional argument arg. Likewise, long options taking optional arguments must be specified as --long=arg, not --long arg.

If has_arg is not NULL, then *has_arg will be set to 1 if the option has an argument, or 0 if the option doesn’t have an argument.

MU_OPT_REQUIRED ¶

This indicates that an option requires an argument. If no argument is specified, it is an error. Like short options with optional arguments, short options with required arguments may not be bundled except as the last option in a bundle. See above for an explanation.

For short options with required arguments, the argument may be passed with the option itself like so: -rarg, or immediately after the argument like so: -r arg. Arguments to long options with required arguments may also be specified with the option itself like so: --required=arg, or immediately after the argument like so: --required arg.

*has_arg will always be set to 1 if has_arg is not NULL.

• Option Argument Types

2.5 Option Callbacks ¶

Option callbacks are useful when you have more advanced option parsing needs. Each option argument type has a different callback. There are also callbacks for options which don’t take arguments: callback_none for non-negatable options, and callback_negatable for negatable options (see Negatable Options). All callback names mentioned are members of the MU_OPT structure.

For a callback that is called when a positional argument is seen, use mu_opt_context_set_arg_callback (see Ordered Option Parsing).

The callback names and prototypes for each argument type are listed below (although MU_OPT_NONE is not a type, and should be passed in the has_arg field of the MU_OPT structure, not the arg_type field):

MU_OPT_NONE

If the negatable field is zero (see Option Structure):

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

Otherwise, if negatable is nonzero:

int (*callback_negatable) (int value, void *data, char *err)

MU_OPT_BOOL

int (*callback_bool) (int has_arg, int arg, void *data, char *err)

MU_OPT_INT

int (*callback_int) (int has_arg, long arg, void *data, char *err)

MU_OPT_FLOAT

int (*callback_float) (int has_arg, double arg, void *data, char *err)

MU_OPT_STRING

int (*callback_string) (int has_arg, const char *arg, void *data, char *err)

MU_OPT_FILE

int (*callback_file) (int has_arg, const char *filename, FILE *file, void *data, char *err)

MU_OPT_DIRECTORY

int (*callback_directory) (int has_arg, const char *dirname, DIR *directory, void *data, char *err)

MU_OPT_ENUM

int (*callback_enum) (int has_arg, int arg, void *data, char *err)

MU_OPT_SUBOPT

int (*callback_subopt) (int has_arg,   void *data, char *err)

A callback will be called as soon as an option is found, so callbacks are guaranteed to be called in the same order as the options appear on the command line. This means that if an option takes suboptions as arguments, the callback for the main option will be called before the callbacks for the suboptions (see Parsing Suboptions). The has_arg parameter will be passed as 1 if the option has an argument, or 0 if the option doesn’t have an argument (except for callback_none which doesn’t have a has_arg parameter).

If the option has an argument, arg will be set to that argument, except in the case of suboptions (see Parsing Suboptions). In the case of callaback_file and callback_directory, filename or dirname will be set to the name of the file or directory respectively.⁴ For callback_negatable, value will be zero if the option was negated, or nonzero if it wasn’t (see Negatable Options).

If you need to provide extra information to a callback, provide it in the cb_data field of the MU_OPT structure. This will then be passed as the data parameter to a callback. Note: a callback should not free this parameter even if it is dynamically allocated. In the case that cb_data is dynamically allocated and/or contains dynamically allocated data, you should also set the cb_data_destructor field to a function which will free all dynamically allocated data in cb_data.

When you call mu_opt_context_free (see Parsing Options and Environment) or mu_subopt_context_free (see Parsing Suboptions), each cb_data_destructor field is called with the corresponding cb_data in order to free that data. If an error occurs while freeing callback data (for example, an error closing a file), cb_data_destructor should return nonzero. Otherwise, cb_data_destructor should return zero.

For callback_file and callback_directory, the file or directory argument will be closed after the callback returns if you leave the arg field of the MU_OPT structure as NULL (see Option Structure). So you must not close the file or directory argument in the callback.

You also must not use the cb_data field to get the opened file/directory. For example, the following code is wrong:

#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

int file_callback(int has_arg, const char *filename,
                  FILE *file, void *data, char *err) {
  /* Make sure the file is named "foo". */
  if (strcmp(filename, "foo")) {
    snprintf(err, MU_OPT_ERR_MAX, "file is not named \"foo\"");
    return 1;
  }

  /* It is named "foo"; return `file' in `*data'.
     This is WRONG! Do not do this! */
  *(FILE **)data = file;

  return 0;
}

int main(int argc, char **argv) {
  FILE *file = NULL;
  char buf[256];
  size_t size;
  int ret;
  const MU_OPT options[] = {
    {
     .short_opt     = "f",
     .long_opt      = "file",
     .has_arg       = MU_OPT_REQUIRED,
     .arg_type      = MU_OPT_FILE,
     .file_mode     = "r",
     .callback_file = file_callback,
     .cb_data       = &file
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  /* Parse the options. */
  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  if (!file) {
    /* We weren't passed the `-f' option. */
    return 0;
  }

  /* Read the file. This invokes UNDEFINED BEHAVIOR because
     `file' was already closed by `mu_parse_opts'! */
  size = fread(buf, sizeof(*buf), sizeof(buf), file);
  if (ferror(file)) {
    fprintf(stderr, "%s: cannot read foo: %s\n",
            argv[0], strerror(errno));
    return 1;
  }
  fclose(file);

  /* Print the contents of the file to standard output. */
  fwrite(buf, sizeof(*buf), size, stdout);

  return 0;
}

When this program is run, it invokes undefined behavior. The correct way to do this is to not use the cb_data field, and instead set the arg field to &file. This way, mu_parse_opts will not close the file or directory after the callback returns.

If a callback needs to indicate an error (if its argument is in the wrong format, for example), it should return nonzero. Otherwise, on success, it should return 0. If a callback returns nonzero, you must write an error string to err which will then be used by mu_parse_opts to print an error message. You must not write more than MU_OPT_ERR_MAX characters to err (including the terminating null byte). However, if you write exactly MU_OPT_ERR_MAX bytes to err, you need not terminate err with a null byte.

Below is an example of how to use callbacks. Of course, this trivial example would be better expressed using enumerated argument parsing (see Parsing Enumerated Arguments to Options).

#include <stdio.h>
#include <string.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

enum selection { FOO, BAR, BAZ };

/* Parse a selection. `has_arg' will always be true because the option
   takes a required argument. */
int parse_selection(int has_arg, const char *arg,
                    void *data, char *err) {
  enum selection sel;

  if (!strcmp(arg, "foo"))
    sel = FOO;
  else if (!strcmp(arg, "bar"))
    sel = BAR;
  else if (!strcmp(arg, "baz"))
    sel = BAZ;
  else {
    /* `err' will be used by `mu_parse_opts' to print an error
       message. */
    snprintf(err, MU_OPT_ERR_MAX, "invalid selection: %s", arg);
    /* Indicate to `mu_parse_opts' that an error occured by returning
       a nonzero value. */
    return 1;
  }

  /* Store the selection in `*data'. */
  *(enum selection *)data = sel;

  /* Success! */
  return 0;
}

int main(int argc, char **argv) {
  enum selection sel;
  int found_sel;
  int ret;
  const MU_OPT options[] = {
    {
     .short_opt       = "s",
     .long_opt        = "selection",
     .has_arg         = MU_OPT_REQUIRED,
     .arg_type        = MU_OPT_STRING,
     .found_arg       = &found_sel,
     .callback_string = parse_selection,
     .cb_data         = &sel
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  /* Parse the options. */
  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1; /* `mu_parse_opts' will print an error message for us */

  if (found_sel) {
    /* Print the selection. */
    fputs("You selected: ", stdout);
    switch (sel) {
    case FOO:
      puts("FOO");
      break;
    case BAR:
      puts("BAR");
      break;
    case BAZ:
      puts("BAZ");
      break;
    default:
      puts("an unknown value!"); /* This should not happen */
    }
  }
  else
    puts("You didn't select anything.");

  return 0;
}

Here is what the output of the example program looks like:

$ ./option-callback
-| You didn't select anything.
$ ./option-callback -s foo
-| You selected: FOO
$ ./option-callback --selection=bar
-| You selected: BAR
$ ./option-callback -s qux
error→ ./option-callback: invalid selection: qux
$ ./option-callback -s
error→ ./option-callback: '-s': option requires argument

2.6 Parsing Enumerated Arguments to Options ¶

It is often useful to have an option which takes an argument which is a string that is restricted to a set of values. For example, GNU ls (and many other programs) take a --color option, which has an argument that can be ‘always’, ‘auto’, or ‘never’ (in addition to various synonyms). Mu supports similar argument parsing, called enumerated arguments.

Names and values for enumerated types are specified in the enum_values field of the MU_OPT structure (see Option Structure). enum_values is an array of MU_ENUM_VALUE structures as defined below. enum_values is terminated by an element with a name field of NULL.

If the enum_case_match field of the MU_OPT structure is nonzero (see Option Structure), matching is case sensitive. Otherwise, matching is case insensitive.

Like long options and suboptions, abbreviation is allowed when passing enumerated arguments, as long as it is not ambiguous.

Data Type: MU_ENUM_VALUE ¶

Unlike MU_OPT (see Option Structure), this structure is simple and it’s organization is guaranteed. Therefore, you may use positional initializers to initialize this structure. Of course, you can still use designated initializers if you prefer.

const char *name

This field specifies the name to match against when parsing the argument. Like long options, suboptions, and environment variables, name may have aliases separated by ‘|’ (see Aliases for Options and Environment Variables). Alternatively, aliases can be specified by using separate entries with the same value (see below).

Duplicates in this field, either duplicate aliases or duplicates between entries, are not allowed. Note that if enum_case_match is zero, case is not considered. So, if enum_case_match is zero, you cannot have two entries, ‘foo’ and ‘FOO’, nor can you have two aliases specified as ‘foo|FOO’.

int value

This is the value of the enumeration. It is the value passed as the arg parameter of callback_enum (see Option Callbacks), and, if the arg field of the MU_OPT structure is not NULL, it is the value stored in *arg.

The following example illustrates how to use both case insensitive enumerated argument parsing, and case sensitive enumerated argument parsing:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

enum selection { FOO, BAR, BAZ };

int main(int argc, char **argv) {
  enum selection sel;
  int found_sel;
  int ret;
  const MU_ENUM_VALUE enum_table[] = {
    /* Aliases can be specified for enumerated arguments. */
    { "foo|alias-foo", FOO },
    { "bar", BAR },
    /* Aliases can alternatively be specified like this. */
    { "alias-bar", BAR },
    { "baz", BAZ },
    /* This terminates the enumeration specification. */
    { 0 }
  };
  const MU_OPT options[] = {
    {
     .short_opt       = "s",
     .long_opt        = "selection",
     .has_arg         = MU_OPT_REQUIRED,
     .arg_type        = MU_OPT_ENUM,
     /* This indicates that matching should be case insensitive. */
     .enum_case_match = 0,
     .enum_values     = enum_table,
     .found_arg       = &found_sel,
     .arg             = &sel
    },
    {
     .short_opt       = "c",
     .long_opt        = "case-selection",
     .has_arg         = MU_OPT_REQUIRED,
     .arg_type        = MU_OPT_ENUM,
     /* This indicates that matching should be case sensitive. */
     .enum_case_match = 1,
     .enum_values     = enum_table,
     .found_arg       = &found_sel,
     .arg             = &sel
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  /* Parse the options. */
  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  if (found_sel) {
    /* Print the selection. */
    fputs("You selected: ", stdout);
    switch (sel) {
    case FOO:
      puts("FOO");
      break;
    case BAR:
      puts("BAR");
      break;
    case BAZ:
      puts("BAZ");
      break;
    default:
      /* This is guaranteed not to happen. */
      puts("an unknown value!");
    }
  }
  else
    puts("You didn't select anything.");

  return 0;
}

Here is the output of the above example, to show exactly how enumerated arguments are parsed:

$ ./option-enum --selection=foo
-| You selected: FOO
$ ./option-enum --selection=alias-foo
-| You selected: FOO
$ ./option-enum --selection=alias-bar
-| You selected: BAR
$ ./option-enum --selection=bAr
-| You selected: BAR
$ ./option-enum --selection=Ba
error→ ./option-enum: 'Ba': argument for '--selection' is ambiguous; possibilities:
error→   bar
error→   baz
$ ./option-enum --selection=qux
error→ ./option-enum: 'qux': invalid argument for '--selection'; must be one of 'foo', 'bar', 'alias-bar', or 'baz'
$ ./option-enum --case-selection=FoO
error→ ./option-enum: 'FoO': invalid argument for '--case-selection'; must be one of 'foo', 'bar', 'alias-bar', or 'baz'
$ ./option-enum --case-selection=foo
-| You selected: FOO

2.7 Parsing Suboptions ¶

Sometimes you may want to have an option which takes suboptions as arguments. You can do this through the subopts field of the MU_OPT structure. The subopts field is a list of MU_OPTs, terminated by a suboption with all fields equal to 0. Suboptions are in every way like regular options, except that they may not have suboptions of their own and they must use the subopt_name field instead of short_opt or long_opt. See Option Structure.

Suboptions may also specify the env_var field for an equivalent environment variables as well. Environment variables may also take suboptions as a value. See Parsing the Environment.

Note: even though environment variables may be specified for suboptions, you may not have a suboption which only specifies an environment variable. I.e., you may not have a suboption which has no subopt_name field (such an option will be considered as a terminator for the suboption list). If you want to do this, use a regular option instead.

Options which take suboptions as arguments may use the callback_subopt field as a callback (see Option Callbacks). If a callback is used and the option is found on the command line (or in the environment for an environment variable), the callback for that option is guaranteed to be called before any callbacks for the suboptions themselves. Note, however, that if a suboption has an equivalent environment variable (using the env_var field), the callback for the option which takes that suboption as an argument will not be called at all (though the callback for the suboption will be called). Indeed, it is impossible to call the callback for the option which takes the suboption as an argument, because two different options with different callbacks may take the same suboptions as arguments. Nor would it make any sense, because the option never actually appeared on the command line (or environment).

Suboptions are specified as a comma-separated list, with ‘=’ used to specify arguments. The commas must not contain spaces around them, and arguments cannot be specified any other way than with ‘=’.

Suboptions, like long options, may be abbreviated as long as they are not ambiguous. Note that this is in contrast to getsubopt, which does not allow abbreviation (see (libc)Suboptions).

Like regular options, suboptions should use the help field, which will be used in the help message (see Formatting Help and Option Structure). Suboptions may also use the arg_help field if they take arguments (see Option Arguments).

Normally, suboptions are parsed by mu_parse_opts from an argument to a regular option, using the subopts field. However, you may also parse suboptions in a user-specified string as well. Doing so is not too dissimilar from parsing regular options.

Data Type: MU_SUBOPT_CONTEXT ¶

This is an opaque context for parsing suboptions. It is allocated using mu_subopt_context_new and freed using mu_opt_context_free.

Function: MU_SUBOPT_CONTEXT * mu_subopt_context_new (const char *prog_name, const char *suboptstr, ¶

const MU_OPT *subopts)

Allocate and return a new suboption parsing context. The name the program was invoked as should be passed in prog_name (normally argv[0]), and is used for error reporting.

The suboptions will be parsed in suboptstr. A copy of suboptstr will be made, so you need not worry about it going out of scope or being modified (this copy will be freed by mu_subopt_context_free). The suboptions are specified in subopts.

Function: int mu_subopt_context_free (MU_SUBOPT_CONTEXT *context) ¶

Free the suboption context, context. Callback data is freed as for mu_opt_context_free (see Parsing Options and Environment). Like mu_opt_context_free, mu_subopt_context_free will return nonzero if any of the destructors returned nonzero, or zero if all destructors returned zero. Also like mu_opt_context_free, all destructors are called even if one or more of them return nonzero.

Function: int mu_parse_subopts (MU_SUBOPT_CONTEXT *context) ¶

Parse the suboptions given in context. Use mu_subopt_context_new (see above) to create the context. Zero is returned on success, or an error code on error (see Option Parsing Errors).

Note that you may not call this function more than once. To do so is an error and will be diagnosed.

The following example illustrates the use of suboptions:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x* */

int subopt_none(void *data, char *err) {
  puts("suboption found: none");
  return 0;
}

int subopt_opt(int has_arg, const char *arg,
               void *data, char *err) {
  puts("suboption found: opt");
  if (has_arg)
    printf("argument: %s\n", arg);
  return 0;
}

int subopt_req(int has_arg, const char *arg,
               void *data, char *err) {
  printf("suboption found: req\nargument: %s\n", arg);
  return 0;
}

int main(int argc, char **argv) {
  int ret;
  /* These are the suboptions that can be passed to the `-o'
     option. They are specified just like regular options, except
     that `subopt_name' is used instead of `long_opt' or
     `short_opt', and they may not have suboptions of their
     own. */
  const MU_OPT suboptions[] = {
    {
     .subopt_name     = "none",
     .has_arg         = MU_OPT_NONE,
     .callback_none   = subopt_none,
     .help            = "a suboption taking no arguments"
    },
    {
     .subopt_name     = "opt",
     .has_arg         = MU_OPT_OPTIONAL,
     .arg_type        = MU_OPT_STRING,
     .callback_string = subopt_opt,
     .help            = "a suboption taking an optional argument"
    },
    {
     .subopt_name     = "req",
     .has_arg         = MU_OPT_REQUIRED,
     .arg_type        = MU_OPT_STRING,
     .callback_string = subopt_req,
     .help            = "a suboption taking a required argument"
    },
    { 0 }
  };
  const MU_OPT options[] = {
    {
     .short_opt = "o",
     .long_opt  = "options",
     .has_arg   = MU_OPT_REQUIRED,
     .arg_type  = MU_OPT_SUBOPT,
     .subopts   = suboptions,
     .help      = "a regular option which takes suboptions"
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);

  /* Add the help option. */
  mu_opt_context_add_help(context, NULL, NULL, "Parse suboptions.",
                          NULL, "1", NULL, NULL, NULL);
  mu_opt_context_xadd_help_options(context, MU_HELP_BOTH);

  /* Parse the options. */
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  return 0;
}

And here is the output of the example program (note, the COLUMNS environment variable is set to 65 so that the help message will look good in this manual):

$ COLUMNS=65
$ export COLUMNS
$ ./subopts -o none,opt=foo
-| suboption found: none
-| suboption found: opt
-| argument: foo
$ ./subopts -o req
error→ ./subopts: 'req': suboption requires argument
$ ./subopts --help
-| Usage: ./subopts [OPTION]...
-| Parse suboptions.
-|  
-| Mandatory arguments to long options are mandatory for short options too.
-|   -o, --options=SUBOPTS   a regular option which takes suboptions
-|   -h, --help[=plain|man]  print this help in plain text format if 'plain', or as a man(1) page if
-|                             'man'; if the argument is omitted, it will default to 'plain'.
-|  
-| Suboptions for -o, --options:
-|   none                    a suboption taking no arguments
-|   opt[=STRING]            a suboption taking an optional argument
-|   req=STRING              a suboption taking a required argument

2.8 Parsing the Environment ¶

In addition to parsing options, mu_parse_opts supports parsing environment variables as well. Environment variables are specified using the env_var field (see Option Structure). Values of environment variables are specified in the same way as arguments are specified to options (see Option Arguments).

Unlike options, environment variables are parsed in the program environment (or the environment parameter to mu_opt_context_new_with_env), rather than in argv (see Parsing Options and Environment). And unlike long options and suboptions, environment variables may not be abbreviated. And whereas an invalid option will cause an error, an invalid environment variable will be ignored.

Environment variables may be specified for suboptions, and an environment variable may take suboptions as a value as well. For example, you might have an environment variable, ENV, which takes a suboption foo, which itself takes an optional string argument, say. And suppose foo has an equivalent environment variable, ENV_FOO. Then you might specify a value ‘bar’ to the foo suboption either by specifying a value to ENV like this: ENV=foo=bar, or by specifying a value directly to ENV_FOO like this: ENV_FOO=bar. The example shows how to do this as well. See Parsing Suboptions for more information on suboptions.

Environment variables are always parsed before command line options. Environment variables and long/short options may be specified in the same option, but if this is the case, the command line option(s) will take precedence over the environment variable, since the environment variables will always be parsed first.

If an environment variable has aliases (see Aliases for Options and Environment Variables), aliases specified first will take precedence. For example, if an environment variable is specified as ‘FOO|BAR’, and both FOO and BAR are in the environment, then the value of FOO will take precedence because it was specified as an alias before BAR. Note also that if both FOO and BAR are specified in the environment, the value of BAR will be completely ignored. The callback (if any) will only be called once, for FOO (see Option Callbacks).

Another thing to note is that if you have an environment variable with a has_arg value of MU_OPT_NONE, then if that environment variable is encountered, and it has a value other than the empty string, that will cause an error. This is not very user-friendly behavior, and you might consider using a has_arg of MU_OPT_OPTIONAL and an arg_type of MU_OPT_BOOL. Then, if the environment variable has no value, you can default to true. This is more user-friendly, because things like ENV_VAR=yes or ENV_VAR=no will do what is expected (assuming your environment variable is called ENV_VAR).

Traditionally, environment variable names are in ALL CAPS.

Here is an example of how environment variables can be parsed:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x* */

/* Print a message when an option is found. */
int print_opt(int has_arg, const char *arg,
              void *data, char *err) {
  const char *name = data;
  printf("Found an option/environment variable '%s'", name);
  if (has_arg)
    printf(" with an argument '%s'", arg);
  putchar('\n');
  return 0;
}

int main(int argc, char **argv) {
  int ret;
  const MU_OPT suboptions[] = {
    {
     .subopt_name     = "subopt",
     /* Suboptions can have environment variables as well. */
     .env_var         = "ENV_SUBOPT",
     .has_arg         = MU_OPT_OPTIONAL,
     .arg_type        = MU_OPT_STRING,
     .callback_string = print_opt,
     .cb_data         = "a suboption",
     .help            =
     "a suboption with an equivalent environment variable"
    },
    { 0 }
  };
  const MU_OPT options[] = {
    {
     .short_opt       = "a",
     .long_opt        = "an-option",
     /* AN_ENV_VAR will always take precedence over ALIAS since it is
        specified first below. */
     .env_var         = "AN_ENV_VAR|ALIAS",
     .has_arg         = MU_OPT_OPTIONAL,
     .arg_type        = MU_OPT_STRING,
     .callback_string = print_opt,
     .cb_data         = "an option",
     .help            =
     "an option with an equivalent environment variable"
    },
    {
     .short_opt       = "b",
     .long_opt        = "another-option",
     .has_arg         = MU_OPT_OPTIONAL,
     .arg_type        = MU_OPT_STRING,
     .callback_string = print_opt,
     .cb_data         = "another option",
     .help            =
     "an option without an equivalent environment variable"
    },
    {
     .env_var         = "ANOTHER_ENV_VAR",
     .has_arg         = MU_OPT_REQUIRED,
     /* Environment variables can have suboptions as well. */
     .arg_type        = MU_OPT_SUBOPT,
     .subopts         = suboptions,
     .help            =
     "an environment variable (which takes "
     "suboptions) without an equivalent option"
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_PERMUTE);

  /* Add the help option. */
  mu_opt_context_add_help(context, NULL, NULL,
                          "Parse options and environment variables.",
                          NULL, "1", NULL, NULL, NULL);
  mu_opt_context_xadd_help_options(context, MU_HELP_BOTH);

  /* Parse the options. */
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  if (MU_OPT_ERR(ret))
    return 1;

  return 0;
}

And here is the output of the above program (note, the COLUMNS environment variable is set to 65 so that the help message will look good in this manual):

$ COLUMNS=65
$ export COLUMNS
$ AN_ENV_VAR=foo ./environ --an-option=bar --another-option=baz
-| Found an option/environment variable 'an option' with an argument 'foo'
-| Found an option/environment variable 'an option' with an argument 'bar'
-| Found an option/environment variable 'another option' with an argument 'baz'
$ ANOTHER_ENV_VAR=subopt=foo ./environ
-| Found an option/environment variable 'a suboption' with an argument 'foo'
$ ENV_SUBOPT=foo ./environ
-| Found an option/environment variable 'a suboption' with an argument 'foo'
# AN_ENV_VAR will always take precedence over ALIAS. Also note that
# the callback is only called once, even though both aliases are
# specified.
$ AN_ENV_VAR=foo ALIAS=bar ./environ
-| Found an option/environment variable 'an option' with an argument 'foo'
$ ALIAS=bar AN_ENV_VAR=foo ./environ
-| Found an option/environment variable 'an option' with an argument 'foo'
$ ./environ --help
-| Usage: ./environ [OPTION]...
-| Parse options and environment variables.
-|  
-|   -a, --an-option[=STRING]       an option with an equivalent environment variable
-|   -b, --another-option[=STRING]  an option without an equivalent environment variable
-|   -h, --help[=plain|man]         print this help in plain text format if 'plain', or as a man(1)
-|                                    page if 'man'; if the argument is omitted, it will default to
-|                                    'plain'.
-|  
-| Suboptions for ANOTHER_ENV_VAR:
-|   subopt[=STRING]                a suboption with an equivalent environment variable
-|  
-| ENVIRONMENT
-|  
-|   AN_ENV_VAR, ALIAS[=STRING]     an option with an equivalent environment variable
-|   ANOTHER_ENV_VAR=SUBOPTS        an environment variable (which takes suboptions) without an
-|                                    equivalent option
-|   ENV_SUBOPT[=STRING]            a suboption with an equivalent environment variable

2.9 Option Parsing Flags ¶

There are several flags which affect option parsing in different ways. These flags are passed in the flags parameter to mu_opt_context_new (see Parsing Options and Environment).

Constant: MU_OPT_PERMUTE ¶

This flag indicates that mu_parse_opts should rearrange argv so that the options are at the beginning, and positional arguments are at the end.⁵ If this flag is not given, option parsing will stop as soon as the first non-option argument is encountered. Option parsing will also stop when the string ‘--’ is encountered, whether or not this flag was given. The ‘--’ string will be treated as an option, i.e., it will be counted in the return value of mu_parse_opts and, if this flag is set, it will be moved before all the other positional arguments in argv.

If the environment variable POSIXLY_CORRECT is set, or the MU_OPT_STOP_AT_ARG flag is used, mu_parse_opts will act as though this flag were not given even if it was. Note that POSIXLY_CORRECT is searched for in the env parameter given to mu_opt_context_new_with_env, or in the program environment if no env parameter is given or if mu_opt_context_new was used to create the option parsing context. If you want to ignore POSIXLY_CORRECT entirely, use the MU_OPT_IGNORE_POSIX flag.

Constant: MU_OPT_BUNDLE ¶

This flag enables bundling of short options. Without this flag, long options may be specified with a single ‘-’ or ‘--’. When this flag is set, long options may only be specified with ‘--’.

So when this flag is set, -abc will be treated as three short options, a, b, and c (assuming that a and b don’t take arguments⁶), whereas without this flag, -abc will be treated as a single long option, abc.

Note that when this flag is not set, short options with optional arguments take precedence over long options. So, if there is a short option, o, which takes an optional argument, and another long option, option (it doesn’t matter whether it takes an argument or not), then the string -option is a short option, o with an argument ‘ption’.

While this may seem counter-intuitive at first, the reason for this seemingly strange behavior becomes apparent when you consider a short option, o, which takes an optional argument and a long option, option. (Again, it doesn’t matter whether the long option takes an argument or not.) Suppose that instead, long options took precedence over short ones.⁷ Now lets look at the -option example again. It would be parsed as a single long option, option. But what if you wanted to pass the o short option an argument ‘ption’? Or indeed, even just ‘p’? It would be parsed as a long option, option. So there is no possible way to pass an argument to the o short option such that ‘ption’ begins with that argument (or is the argument). But, you ask, couldn’t you write -o ption? You could, if the o short option takes a required argument, but not if it takes an optional argument, because optional arguments to short options are required to be specified as part of the option itself (see Option Arguments). Note that you can still write the option long option as --option, which is unambiguous, so there is no issue.

Since this behavior can be confusing and counter-intuitive, long options take precedence when the short option that would match takes a required argument, and the long option matches exactly. Going back to the above example, if the o short option instead took a required argument, ‘-option’ would be the long option option, rather than the short option o, with an argument ‘ption’. Note, however, that ‘-opt’ would be the o short option with an argument ‘pt’. Also note that if the option long option did not exist, ‘-option’ would be the short option o with an argument ‘ption’. If you want to avoid ambiguity, you should always pass required arguments to short options in the next argument, and precede long options with two dashes like so: ‘-o arg --option’.

Constant: MU_OPT_CONTINUE ¶

This flag should be used if you are going to call mu_parse_opts more than once. See Ordered Option Parsing for more information on how to use this flag correctly.

If the POSIXLY_CORRECT environment variable is set, or the MU_OPT_STOP_AT_ARG flag is passed, all arguments after the first non-option arguments will be treated as non-option arguments as well. Note that POSIXLY_CORRECT is searched for in the env parameter given to mu_opt_context_new_with_env, or in the program environment if no env parameter is given or if mu_opt_context_new was used to create the option parsing context. If you want to ignore POSIXLY_CORRECT entirely, use the MU_OPT_IGNORE_POSIX flag.

Constant: MU_OPT_ALLOW_INVALID ¶

This flag makes mu_parse_opts treat invalid options as positional arguments. It can be useful if you are writing a function which parses some options, but then leaves the rest for the caller to parse. An example of a function which does this (although it does not use Mu) is gtk_init (see section Main loop and Events in GTK+ 3 Reference Manual).

Note: if you use mu_opt_context_add_help_options, the help option will only print the help for the context you called mu_opt_context_add_help_options with. mu_opt_context_add_help_options has no way of knowing what options will be parsed in the future. So if you are writing a function like that described above, you may wish instead to make your function take an option context as a parameter, and then add some standard ones using mu_opt_context_add_options (see Parsing Options and Environment).

Constant: MU_OPT_IGNORE_POSIX ¶

Ignore the POSIXLY_CORRECT environment variable even if it is set. This flag can be used for programs for which it would not make sense to parse options in a POSIXly correct way. For example, you might have an option which acts on the last positional argument given before it.

Constant: MU_OPT_STOP_AT_ARG ¶

Stop parsing options after the first positional argument. I.e., act as though the POSIXLY_CORRECT environment variable were set. If this flag is used, MU_OPT_IGNORE_POSIX has no effect.

Note that this behavior is the default, unless the MU_OPT_PERMUTE flag is used, the MU_OPT_CONTINUE flag is used, and/or an argument callback is used (see Ordered Option Parsing).

2.10 Ordered Option Parsing ¶

Sometimes it is useful to know where options appear on the command line. You can tell in which order options (and suboptions) appear by taking advantage of the fact that callbacks (see Option Callbacks) are called in the same order that the corresponding options appear on the command line. However, if you want to determine the ordering of non-option positional arguments as well as options, you must instead use an argument callback, or use the MU_OPT_CONTINUE flag (see Option Parsing Flags).

To use an argument callback, you must use the mu_opt_context_set_arg_callback function.

Function: void mu_opt_context_set_arg_callback (MU_OPT_CONTEXT *context, int callback (const char *arg, void *data, char *err), void *data, int destructor (void *data)) ¶

This function sets an argument callback in context. context must not have been created with the MU_OPT_CONTINUE flag (see Option Parsing Flags), and it must never have been passed to mu_parse_opts (see Parsing Options and Environment).

callback will be called for each positional argument found when mu_parse_opts is called. callback may not be NULL. data will be passed to callback as the data argument. When context is destroyed using mu_opt_context_free, destructor will be called with data passed as its data argument.

callback should indicate success by returning zero. If callback fails, it should return nonzero and copy an error string to err (not exceeding MU_OPT_ERR_MAX). See callback error indication for more information.

Note that if either of the flags MU_OPT_PERMUTE or MU_OPT_STOP_AT_ARG are used when the option parsing context is created (see Option Parsing Flags), then the successful return value of mu_parse_opts will not include the positional arguments parsed (see Parsing Options and Environment). This is so that, after shifting the arguments by the return value of mu_parse_opts with mu_shift_args, the remaining arguments will be the positional arguments.

Normally, however, when using an argument callback, you shouldn’t need the return value of mu_parse_opts except to check for errors.

If neither of the flags MU_OPT_PERMUTE nor MU_OPT_STOP_AT_ARG are given, then the return value of mu_parse_opts will include the positional arguments (i.e., a successful return from mu_parse_opts will always return the total number of arguments, options or otherwise). This is because, if neither MU_OPT_PERMUTE nor MU_OPT_STOP_AT_ARG are given, it cannot be guaranteed that all positional arguments will appear after all options. Thus, the return value of mu_parse_opts should not be used to shift the arguments, and should only be used to check for errors.

Here is an example of how to use argument callbacks:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

/* Callbacks to print a message when we find an option or argument. */

static int print_example(void *data, char *err) {
  puts("Option found: example");
  return 0;
}

static int print_another(void *data, char *err) {
  puts("Option found: another");
  return 0;
}

static int print_argument(const char *arg, void *data, char *err) {
  printf("Argument found: %s\n", arg);
  return 0;
}

int main(int argc, char **argv) {
  const MU_OPT options[] = {
    {
     .short_opt     = "e",
     .long_opt      = "example",
     .has_arg       = MU_OPT_NONE,
     .callback_none = print_example
    },
    {
     .short_opt     = "a",
     .long_opt      = "another",
     .has_arg       = MU_OPT_NONE,
     .callback_none = print_another
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;
  int ret;

  context = mu_opt_context_xnew(argc, argv, options, 0);
  mu_opt_context_set_arg_callback(context, print_argument,
                                  NULL, NULL);
  ret = mu_parse_opts(context);
  mu_opt_context_xfree(context);
  return MU_OPT_ERR(ret);
}

Here is the output of the example program:

$ ./option-ordered-callback foo -e bar --another baz
-| Argument found: foo
-| Option found: example
-| Argument found: bar
-| Option found: another
-| Argument found: baz
$ ./option-ordered-callback -a foo bar --example
-| Option found: another
-| Argument found: foo
-| Argument found: bar
-| Option found: example

Alternatively, you can also determine the order in which options and positional arguments appear using the MU_OPT_CONTINUE flag. If you use this flag, you should not use the MU_OPT_PERMUTE flag (otherwise, all options will be parsed at once and the MU_OPT_CONTINUE flag is rendered useless). The MU_OPT_STOP_AT_ARG is also useless if you use MU_OPT_CONTINUE, because if you use MU_OPT_STOP_AT_ARG, you might as well just parse the options once and then parse the rest of the arguments, which will only be positional arguments.

Using the MU_OPT_CONTINUE flag, you should parse options (maybe using callbacks if you care about the order of the options themselves), then parse positional arguments, and then options again until all arguments are used up. Note, however, that normally you must not call mu_parse_opts more than once, unless you pass the MU_OPT_CONTINUE flag

All the environment variables will be parsed on the first call of mu_parse_opts. They will not be parsed again in subsequent calls. See Parsing the Environment for more information.

After you parse each non-option argument, you must call mu_opt_context_shift on the option context in order to ensure that mu_parse_opts will not stop at the argument you just parsed.

Function: int mu_opt_context_shift (MU_OPT_CONTEXT *context, int amount) ¶

Update the internal index of context by amount. amount may be negative.

Normally, this function returns zero. However, in the case that the new index would be less that 1, the new index will instead be set to 1 and the amount that could not be shifted will be returned. And in the case that the new index would be greater than or equal to the number of arguments in context, the new index will instead be set to the number of arguments minus one, and again, the amount that could not be shifted is returned.

Here is an example illustrating how to parse options and positional arguments while preserving the order, without using argument callbacks:

#include <stdio.h>
#include <mu/options.h>
#include <mu/safe.h>            /* For mu_opt_context_x{new,free} */

/* Callbacks to print a message when we find an option. */

static int print_example(void *data, char *err) {
  puts("Option found: example");
  return 0;
}

static int print_another(void *data, char *err) {
  puts("Option found: another");
  return 0;
}

int main(int argc, char **argv) {
  const MU_OPT options[] = {
    {
     .short_opt     = "e",
     .long_opt      = "example",
     .has_arg       = MU_OPT_NONE,
     .callback_none = print_example
    },
    {
     .short_opt     = "a",
     .long_opt      = "another",
     .has_arg       = MU_OPT_NONE,
     .callback_none = print_another
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  context = mu_opt_context_xnew(argc, argv, options, MU_OPT_CONTINUE);
  while (argc > 1) {
    int ret;

    /* Parse options. */
    ret = mu_parse_opts(context);
    if (MU_OPT_ERR(ret))
      return 1;

    /* Shift the arguments (to get rid of the options we just
       parsed). */
    mu_shift_args(&argc, &argv, ret);

    if (argc > 1) {
      /* Print an argument (we don't have to print them all at once
         because if `mu_parse_opts' doesn't find any options, it will
         just return 0). */
      printf("Argument found: %s\n", argv[1]);
      /* Shift away this argument. */
      mu_shift_args(&argc, &argv, 1);
      mu_opt_context_shift(context, 1);
    }
  }
  mu_opt_context_xfree(context);

  return 0;
}

The behavior of the above program is identical to the one using argument callbacks (see argument callback example).

2.11 Formatting Help ¶

Many programs have a -h or --help option which prints out a short message describing how to use the program. Mu supports automatically generating a usage message through the use of the help and arg_help fields of the MU_OPT structure (see Option Structure).

Function: void mu_opt_context_add_help (MU_OPT_CONTEXT *context, const char *usage, const char *short_description, const char *description, const char *notes, const char *section, const char *section_name, const char *source, const char *date) ¶

Add usage information to context. The arguments are as follows:

usage

This is a short, human-readable description of the arguments your program takes. For example, ‘[OPTION]… [FILE]…’. If usage is left NULL, it will default to ‘[OPTION]…’ if there is a least one option in options or, if options is empty, it will default to ‘’ (the empty string). If you really want nothing to be printed for usage, pass ‘’ (the empty string) explicitly.

Alternative usages (including no arguments) can be specified, separated by newlines. For example, if your program is called prog and you pass a usage of ‘FOO\nBAR\n\nBAZ’ (note the two ‘\n’s after ‘BAR’), the help output will be as follows:

Usage: prog FOO
  or:  prog BAR
  or:  prog
  or:  prog BAZ
[...]

You can think of it as piping usage to

sed '1s/^/Usage: prog /; 2,/^/  or:  prog /'

(assuming your program is called prog).

short_description

This is a very short description (shorter than description) of the program. It is used as the description in the NAME section.

If this parameter is passed as NULL, a default will be substituted. This parameter is only used for man page output.

description

This is a short, human-readable description of whatever your program does. It is printed right below the usage line. It should be one or two sentences long. For example:

Frobnicate frobs. Nonexistent frobs will be treated as empty.

You may reference metasyntactic variables specified in usage here (e.g., ‘FILE’) if you like. If you set this to NULL, no description will be printed.

Note: you should not write

Mandatory arguments to long options are mandatory for short options too.

in description. This will automatically be added to the help text if it makes sense (i.e., if there exist long options with required arguments that have short option equivalents).

notes

This will be printed at the end of the help message, after the options. This is where you can put examples, bug report addresses, etc.

section

The section number of the manual page. This can be any string (but see section_name below), although it should be a number followed by an optional suffix. The optional suffix can be something like ncurses uses for its man pages, ‘NCURSES’ (so the full section would be ‘3NCURSES’). Most likely you should just set this to a number.

This parameter must not be NULL, unless man page output is not being used. This parameter is only used for man page output.

section_name

This is the name of the manual section. For example, ‘User Commands’.

If this parameter is passed as NULL, a default will be chosen based on section. In this case, section must start with a number between 1 and 9 inclusive except for 7. Section 7 does not have a default name because it is more of a “miscellaneous” section, and thus you must provide the name yourself.

This parameter is only used for man page output.

source

This is the “source” of your program. If your program is part of a suite, put the name and version of the suite here. Otherwise, put the name and version of your program here.

If this parameter is passed as NULL (not recommended), the name your program was invoked as will be used. This parameter is only used for man page output.

date

This is the date that the help text was last updated. Update date every time you change the help text for any option, or you change the name of an option or add a new one. You need not update this for trivial changes.

The format for date is conventionally ‘YYYY-MM-DD’.

If this parameter is passed as NULL (not recommended), the date at which your program was run to generate the man page will be used instead. Note that the date parameter is passed as NULL in the examples for simplicity, but this is still not recommended.

This parameter is only used for man page output.

Function: int mu_opt_context_add_help_options (MU_OPT_CONTEXT *context, int flags) ¶

Add help options to context based on flags. If MU_HELP_PREPEND is present in flags, the help options will be prepended to the current options, i.e., inserted before them. Othewise, if MU_HELP_PREPEND is not present in flags, the help options will be appended to the current options, i.e., inserted after them.

flags tells mu_opt_context_add_help_options what kind of help options/environment variables should be created, in addition to whether it should append or prepend the help options. The following values may be passed in flags, and can be combined with | (bitwise OR).

MU_HELP_PREPEND ¶

This indicates that mu_opt_context_add_help_options should add the help options before the current options, rather than after. Note that order of the help options themselves is unchanged.

MU_HELP_SHORT ¶

MU_HELP_LONG

MU_HELP_QUESTION_MARK

These flags tell mu_opt_context_add_help_options to create an option which takes a single optional argument, format. MU_HELP_SHORT will create a short option, -h, while MU_HELP_LONG will create a long option, --help, and MU_HELP_QUESTION_MARK will create a short option, -?. format specifies the output format to use when outputting help. It can either be ‘man’ to output in a format which can be parsed by the man program, or it can be ‘plain’ or ‘text’ to output in a human-readable, plain-text format.

If format is omitted, it will default to the value of the MU_HELP_FORMAT environment variable if MU_HELP_ENV is passed in flags. Otherwise, if the MU_HELP_FORMAT environment variable is not set or does not have a value or MU_HELP_ENV was not passed in flags, format will default to ‘plain’.

Note: MU_HELP_QUESTION_MARK is not included in MU_HELP_ALL (see below). If you want to pass all flags including MU_HELP_QUESTION_MARK, you must pass it explicitly, like so: MU_HELP_ALL | MU_HELP_QUESTION_MARK.

MU_HELP_MAN_SHORT ¶

MU_HELP_MAN_LONG

These flags tell mu_opt_context_add_help_options to create an option which takes no argument, and always outputs help in man format. MU_HELP_MAN_SHORT will create a short option, -m, while MU_HELP_MAN_LONG will create a long option, --man.

MU_HELP_ENV ¶

This flag tells mu_opt_context_add_help_options to create an environment variable, MU_HELP_FORMAT, which will specify an output format to use if none was specified to -h or --help. You must only use this flag if MU_HELP_SHORT or MU_HELP_LONG was also passed in flags.

MU_HELP_BOTH ¶

Equivalent to MU_HELP_SHORT | MU_HELP_LONG.

MU_HELP_MAN_BOTH ¶

Equivalent to MU_HELP_MAN_SHORT | MU_HELP_MAN_LONG.

MU_HELP_ALL ¶

Equivalent to passing all flags except for MU_HELP_QUESTION_MARK, i.e., MU_HELP_BOTH | MU_HELP_MAN_BOTH | MU_HELP_ENV.

Output formatted for the man program will be piped to man if standard output is a terminal (as determined by isatty), otherwise the raw roff code will be output to standard output. If standard output is a terminal but an error occurred while executing the man program, a warning message will be printed and the raw roff code will be output to standard output as if standard output was not a terminal.

Note: some systems may not provide the necessary functionality to run the man command. In that case, roff code will always be output, regardless of whether standard output is a terminal.

Function: int mu_format_help (FILE *stream, const MU_OPT_CONTEXT *context) ¶

Function: int mu_format_help_man (FILE *stream, const MU_OPT_CONTEXT *context) ¶

These functions format a help message, printing it to stream. If you’d like to automatically create a help option that does this, see mu_opt_context_add_help_options above. You might also want to call these functions manually, for example, if your program receives no arguments or if mu_parse_opts returns an error code (see Parsing Options and Environment and Option Parsing Errors).

mu_format_help will output a human-readable, plain text message, while mu_format_help_man will output roff code.

The strings passed to mu_opt_context_add_help are used in the help message, as well as the options in context.

Function: char * mu_format_help_string (const MU_OPT_CONTEXT *context, unsigned short goal, unsigned short width) ¶

Function: char * mu_format_help_man_string (const MU_OPT_CONTEXT *context) ¶

These functions are like mu_format_help and mu_format_help_man respectively (see above), except that they return the output as a string rather than printing it. If an error occurs, NULL will be returned and errno will be set to indicate the error. If the returned string is not NULL, it will by dynamically allocated and must be freed when you are done with it (see (libc)Freeing after Malloc).

Unlike mu_format_help, mu_format_help_string is unable to determine the goal and width to use, so you must specify these parameters yourself. See Formatting Text for the meanings of goal and width.

You should provide help text for individual options in the help and arg_help fields of the MU_OPT structure (see Option Structure).

arg_help is similar to the usage parameter to mu_format_help. It should be a simple string describing the kind of arguments the option takes. For example, you might write ‘FILE’ if your option takes a file argument, or ‘WxH’ if it takes a width and height argument, separated by an ‘x’. If this is left as NULL, a default will be chosen based on the type of argument your option takes, specified in the arg_type field of the MU_OPT structure.

Note: you should not use ‘[’ and ‘]’ in the arg_help string. The arg_help string will automatically be enclosed in ‘[’ and ‘]’ if the option takes an optional argument.

help is a short description of what the option does. Most GNU utilities use a single sentence, begun with a lowercase letter⁸ and ended without a period. However, you can format help however you like, but keep in mind that it should be fairly short. One sentence or, if you really must, two.

If the help field is left as NULL, the corresponding option will remain undocumented as if it did not exist. See Option Structure for more information.

Below is an example illustrating the usage of both mu_opt_context_add_help_options and mu_format_help. Note that the category field is used to denote option categories (see Option Structure).

#include <stdio.h>
#include <stdlib.h>
#include <mu/options.h>
#include <mu/compat.h>          /* For __attribute__() */
#include <mu/safe.h>            /* For mu_opt_context_x* */

__attribute__((noreturn))
int print_version(void *data, char *err) {
  puts("Version 1.0");
  exit(0);
}

int main(int argc, char **argv) {
  int ret;
  const MU_OPT opts_start[] = {
    {
     .short_opt = "n",
     .long_opt  = "none",
     .has_arg   = MU_OPT_NONE,
     .help      = "an option which takes no argument"
    },
    { .category = "Options taking arguments" },
    {
     .short_opt = "o",
     .long_opt  = "optional",
     .has_arg   = MU_OPT_OPTIONAL,
     .arg_type  = MU_OPT_STRING,
     .arg_help  = "OPTARG",
     .help      = "an option which optionally takes an argument"
    },
    {
     .short_opt = "r",
     .long_opt  = "required",
     .has_arg   = MU_OPT_REQUIRED,
     .arg_type  = MU_OPT_STRING,
     .arg_help  = "REQARG",
     .help      = "an option which requires an argument"
    },
    { .category = "Help options and environment variables" },
    { 0 }
  };
  /* Options to add after the help options. */
  const MU_OPT opts_end[] = {
    { .category = "Version information" },
    {
     .short_opt = "v",
     .long_opt  = "version",
     .has_arg   = MU_OPT_NONE,
     .callback_none = print_version,
     .help      = "print version information and exit"
    },
    { 0 }
  };
  MU_OPT_CONTEXT *context;

  context = mu_opt_context_xnew(argc, argv, opts_start,
                                MU_OPT_BUNDLE | MU_OPT_PERMUTE);

  /* Add the help data. */
  mu_opt_context_add_help(context, "[OPTION]...", "do stuff",
                          "Do stuff. If this text is really long, it "
                          "will be wrapped. Some more text to make "
                          "this text long enough to be wrapped.",
                          "Report bugs to <libmu-bug@nongnu.org>.",
                          "1", NULL, "Mu Examples", NULL);
  /* Create the help option. MU_HELP_ALL is equivalent to
     MU_HELP_SHORT | MU_HELP_LONG | MU_HELP_MAN_SHORT |
     MU_HELP_MAN_LONG | MU_HELP_ENV, so it will create the options
     '-h', '--help', '-m', and '--man', and it will create the
     environment variable 'MU_HELP_FORMAT'. */
  mu_opt_context_xadd_help_options(context, MU_HELP_ALL);
  /* Add the other options. */
  mu_opt_context_xadd_options(context, opts_end, MU_OPT_APPEND);

  /* Parse the options. */
  ret = mu_parse_opts(context);

  /* If there was an option parsing error, print a usage message so
     the user knows how to use us properly. */
  if (ret == MU_OPT_ERR_PARSE)
    mu_format_help(stderr, context);

  mu_opt_context_xfree(context);

  return !!MU_OPT_ERR(ret);
}

This is what the output looks like (note, the COLUMNS environment variable is set to 65 so that the output will look good in this manual):

$ COLUMNS=65
$ export COLUMNS
$ ./option-help --help
-| Usage: ./option-help [OPTION]...
-| Do stuff. If this text is really long, it will be wrapped. Some more text to make this text long
-| enough to be wrapped.
-|  
-| Mandatory arguments to long options are mandatory for short options too.
-|   -n, --none                  an option which takes no argument
-|  
-| Options taking arguments:
-|   -o, --optional[=OPTARG]     an option which optionally takes an argument
-|   -r, --required=REQARG       an option which requires an argument
-|  
-| Help options and environment variables:
-|   -h, --help[=plain|man]      print this help in plain text format if 'plain', or as a man(1) page
-|                                 if 'man'; if the argument is omitted, it will default to the value
-|                                 of the MU_HELP_FORMAT environment variable if set, otherwise
-|                                 'plain'.
-|   -m, --man                   print this help as a man(1) page
-|  
-| Version information:
-|   -v, --version               print version information and exit
-|  
-| ENVIRONMENT
-|  
-| Help options and environment variables:
-|   MU_HELP_FORMAT[=plain|man]  the default format for -h, --help
-|  
-| Report bugs to <libmu-bug@nongnu.org>.
$ ./option-help --foo
error→ ./option-help: '--foo': invalid option
error→ Usage: ./option-help [OPTION]...
error→ Do stuff. If this text is really long, it will be wrapped. Some more text to make this text long
error→ enough to be wrapped.
error→  
error→ Mandatory arguments to long options are mandatory for short options too.
error→   -n, --none                  an option which takes no argument
error→  
error→ Options taking arguments:
error→   -o, --optional[=OPTARG]     an option which optionally takes an argument
error→   -r, --required=REQARG       an option which requires an argument
error→  
error→ Help options and environment variables:
error→   -h, --help[=plain|man]      print this help in plain text format if 'plain', or as a man(1) page
error→                                 if 'man'; if the argument is omitted, it will default to the value
error→                                 of the MU_HELP_FORMAT environment variable if set, otherwise
error→                                 'plain'.
error→   -m, --man                   print this help as a man(1) page
error→  
error→ Version information:
error→   -v, --version               print version information and exit
error→  
error→ ENVIRONMENT
error→  
error→ Help options and environment variables:
error→   MU_HELP_FORMAT[=plain|man]  the default format for -h, --help
error→  
error→ Report bugs to <libmu-bug@nongnu.org>.

2.12 Option Parsing Errors ¶

mu_parse_opts and mu_parse_subopts can fail for several reasons. On failure, these functions will return an error code depending on the reason for failure. The error code can be one of the following:

Constant: MU_OPT_ERR_PARSE ¶

An option parsing error. This indicates that the user made an error when specifying options on the command line. You may wish to print a help message when mu_parse_opts returns this value (see Formatting Help for an example).

Constant: MU_OPT_ERR_IO ¶

This indicates that an input/output error occurred while parsing the arguments. This could indicate, for example, failure to open a file specified as an argument to an option which has a arg_type field of MU_OPT_FILE (see Option Structure).

Constant: MU_OPT_ERR_CALLBACK ¶

This value is returned from mu_parse_opts when a callback returns a nonzero value (see Option Callbacks). You can have your callback set an error flag if you want more details.

Macro: int MU_OPT_ERR (int retval) ¶

This macro returns true if retval is one of the above error codes.

3.1 Controlling Formatted Output ¶

Although the various formatting functions (see Formatting Text) differ slightly in usage, they each take a common set of arguments to control the formatted output. The meaning of each of these arguments is described in the table below:

goal ¶

This parameter is the goal width. Lines will be wrapped at this width as long as that does not cause words to be split into more than one line, but will be continued beyond this width if wrapping would split words into more than one line.

A goal of 0 is treated as infinite.

width ¶

This is the absolute maximum length lines are allowed to be. If a line is any longer than this, it will be wrapped even if that means splitting in the middle of a word. If the line is split in the middle of a word, a ‘-’ will be appended to the end of the line (if there is room⁹) to indicate that the word is continued on the next line.

A width of 0 is treated as infinite.

cursor

This is the address of an unsigned short which holds the current column of output text. You should initialize the value whose address is cursor to 0 before calling any of the formatting functions for the first time with that cursor argument. See Formatting Example for an example of how this is used.

Note: cursor may not be NULL.

indent ¶

This specifies the column that the first line of text should be indented to. If *cursor is already greater than indent, then no indentation will be performed (i.e., it will be as though indent were 0).

Lines following the first one are indented according to subindent.

subindent ¶

This is the indentation to use for lines after the first one (see above). Note that this only applies to a single call of a formatting function. For example, if you do this:

unsigned short cursor = 0;
mu_format(stdout, 0, 0, &cursor, 10, 5, "foo\n");
mu_format(stdout, 0, 0, &cursor, 10, 5, "bar\n");

both ‘foo’ and ‘bar’ will be indented 10 characters. If you want ‘bar’ to be indented 5 characters, say that explicitly by passing indent as 5 (i.e., mu_format(stdout, 0, 0, &cursor, 5, 5, "bar\n")).

3.2 Formatting Example ¶

Here is an example illustrating the use of mu_format and mu_format_string:

#include <stdio.h>
#include <stdlib.h>
#include <mu/format.h>

int main(void) {
  char *str;
  unsigned short cursor = 0;

  /* Format a message to standard output. */
  puts("===== mu_format =====");
  mu_format(stdout, &cursor, 40, 50, 4, 2, "\
This is some text. The first line will be indented 4 \
characters, while following lines will be indented 2. Lines \
will be wrapped at 40 characters, except \
reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaally \
long words, which will be wrapped at 50 characters. A line \
break will appear here:\nno matter what.\n");

  /* Write a similarly formatted message to a string. */
  str = mu_format_string(&cursor, 40, 50, 4, 2,
                         "This text is similarly formatted "
                         "to the text above.\n");

  /* Print the string to standard output. */
  puts("===== mu_format_string =====");
  fputs(str, stdout);

  /* We must free the string since `mu_format_string' dynamically
     allocates it. */
  free(str);

  return 0;
}

And here is the output:

$ ./format
-| ===== mu_format =====
-|     This is some text. The first line
-|   will be indented 4 characters, while
-|   following lines will be indented 2.
-|   Lines will be wrapped at 40
-|   characters, except
-|   reaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-
-|   aaaaaaaaaally long words, which will
-|   be wrapped at 50 characters. A line
-|   break will appear here:
-|   no matter what.
-| ===== mu_format_string =====
-|     This text is similarly formatted to
-|   the text above.