getopt_ulflags: fix indentation in comment (needs to be 8 _spaces_

in order to look correct to both 4 tab and 8 tab population).
Add comment about :: (which indicates optional argument).

1 files changed, 189 insertions, 183 deletions

diff --git a/libbb/getopt_ulflags.c b/libbb/getopt_ulflags.c
index 7ad26551a..988f3f9f5 100644
--- a/libbb/getopt_ulflags.c
+++ b/libbb/getopt_ulflags.c
@@ -10,268 +10,274 @@
 #include "libbb.h"
 #include <getopt.h>
 
-/*                  Documentation
+/*      Documentation
 
 unsigned long
 bb_getopt_ulflags(int argc, char **argv, const char *applet_opts, ...)
 
-        The command line options must be declared in const char
-        *applet_opts as a string of chars, for example:
+        The command line options must be declared in const char
+        *applet_opts as a string of chars, for example:
 
-        flags = bb_getopt_ulflags(argc, argv, "rnug");
+        flags = bb_getopt_ulflags(argc, argv, "rnug");
 
-        If one of the given options is found, a flag value is added to
-        the return value (an unsigned long).
+        If one of the given options is found, a flag value is added to
+        the return value (an unsigned long).
 
-        The flag value is determined by the position of the char in
-        applet_opts string.  For example, in the above case:
+        The flag value is determined by the position of the char in
+        applet_opts string.  For example, in the above case:
 
-        flags = bb_getopt_ulflags(argc, argv, "rnug");
+        flags = bb_getopt_ulflags(argc, argv, "rnug");
 
-        "r" will add 1    (bit 0)
-        "n" will add 2    (bit 1)
-        "u  will add 4    (bit 2)
-        "g" will add 8    (bit 3)
+        "r" will add 1    (bit 0)
+        "n" will add 2    (bit 1)
+        "u  will add 4    (bit 2)
+        "g" will add 8    (bit 3)
 
-        and so on.  You can also look at the return value as a bit
-        field and each option sets one bit.
+        and so on.  You can also look at the return value as a bit
+        field and each option sets one bit.
 
-        On exit, global variable optind is set so that if you
-        will do argc -= optind; argv += optind; then
-        argc will be equal to number of remaining non-option
-        arguments, first one would be in argv[0], next in argv[1] and so on
-        (options and their parameters will be moved into argv[]
-        positions prior to argv[optind]).
+        On exit, global variable optind is set so that if you
+        will do argc -= optind; argv += optind; then
+        argc will be equal to number of remaining non-option
+        arguments, first one would be in argv[0], next in argv[1] and so on
+        (options and their parameters will be moved into argv[]
+        positions prior to argv[optind]).
 
  ":"    If one of the options requires an argument, then add a ":"
-        after the char in applet_opts and provide a pointer to store
-        the argument.  For example:
+        after the char in applet_opts and provide a pointer to store
+        the argument.  For example:
 
-        char *pointer_to_arg_for_a;
-        char *pointer_to_arg_for_b;
-        char *pointer_to_arg_for_c;
-        char *pointer_to_arg_for_d;
+        char *pointer_to_arg_for_a;
+        char *pointer_to_arg_for_b;
+        char *pointer_to_arg_for_c;
+        char *pointer_to_arg_for_d;
 
-        flags = bb_getopt_ulflags(argc, argv, "a:b:c:d:",
-                        &pointer_to_arg_for_a, &pointer_to_arg_for_b,
-                        &pointer_to_arg_for_c, &pointer_to_arg_for_d);
+        flags = bb_getopt_ulflags(argc, argv, "a:b:c:d:",
+                        &pointer_to_arg_for_a, &pointer_to_arg_for_b,
+                        &pointer_to_arg_for_c, &pointer_to_arg_for_d);
 
-        The type of the pointer (char* or llist_t*) may be controlled
-        by the "::" special separator that is set in the external string
-        bb_opt_complementally (see below for more info).
+        The type of the pointer (char* or llist_t*) may be controlled
+        by the "::" special separator that is set in the external string
+        bb_opt_complementally (see below for more info).
+
+ "::"   If option can have an *optional* argument, then add a "::"
+        after its char in applet_opts and provide a pointer to store
+        the argument.  Note that optional arguments _must_
+        immediately follow the option: -oparam, not -o param.
 
  "+"    If the first character in the applet_opts string is a plus,
-        then option processing will stop as soon as a non-option is
-        encountered in the argv array.  Useful for applets like env
-        which should not process arguments to subprograms:
-        env -i ls -d /
-        Here we want env to process just the '-i', not the '-d'.
+        then option processing will stop as soon as a non-option is
+        encountered in the argv array.  Useful for applets like env
+        which should not process arguments to subprograms:
+        env -i ls -d /
+        Here we want env to process just the '-i', not the '-d'.
 
 const struct option *bb_applet_long_options
 
-        This struct allows you to define long options.  The syntax for
-        declaring the array is just like that of getopt's longopts.
-        (see getopt(3))
+        This struct allows you to define long options.  The syntax for
+        declaring the array is just like that of getopt's longopts.
+        (see getopt(3))
 
-        static const struct option applet_long_options[] = {
-                //name,has_arg,flag,val 
-                { "verbose", 0, 0, 'v' },
-                { 0, 0, 0, 0 }
-        };
-        bb_applet_long_options = applet_long_options;
+        static const struct option applet_long_options[] = {
+                //name,has_arg,flag,val 
+                { "verbose", 0, 0, 'v' },
+                { 0, 0, 0, 0 }
+        };
+        bb_applet_long_options = applet_long_options;
 
-        The last member of struct option (val) typically is set to
-        matching short option from applet_opts. If there is no matching
-        char in applet_opts, then:
-        - return bit have next position after short options
-        - if has_arg is not "no_argument", use ptr for arg also
-        - bb_opt_complementally affects it too
+        The last member of struct option (val) typically is set to
+        matching short option from applet_opts. If there is no matching
+        char in applet_opts, then:
+        - return bit have next position after short options
+        - if has_arg is not "no_argument", use ptr for arg also
+        - bb_opt_complementally affects it too
 
-        Note: a good applet will make long options configurable via the
-        config process and not a required feature.  The current standard
-        is to name the config option CONFIG_FEATURE_<applet>_LONG_OPTIONS.
+        Note: a good applet will make long options configurable via the
+        config process and not a required feature.  The current standard
+        is to name the config option CONFIG_FEATURE_<applet>_LONG_OPTIONS.
 
 const char *bb_opt_complementally
 
-        this should be bb_opt_complementary, but we'll just keep it as
-        bb_opt_complementally due to the Russian origins
+        this should be bb_opt_complementary, but we'll just keep it as
+        bb_opt_complementally due to the Russian origins
 
  ":"    The colon (":") is used to separate groups of two or more chars
-        and/or groups of chars and special characters (stating some
-        conditions to be checked).
+        and/or groups of chars and special characters (stating some
+        conditions to be checked).
 
  "abc"  If groups of two or more chars are specified, the first char
-        is the main option and the other chars are secondary options.
-        Their flags will be turned on if the main option is found even
-        if they are not specifed on the command line.  For example:
+        is the main option and the other chars are secondary options.
+        Their flags will be turned on if the main option is found even
+        if they are not specifed on the command line.  For example:
 
-        bb_opt_complementally = "abc";
-        flags = bb_getopt_ulflags(argc, argv, "abcd")
+        bb_opt_complementally = "abc";
+        flags = bb_getopt_ulflags(argc, argv, "abcd")
 
-        If getopt() finds "-a" on the command line, then
-        bb_getopt_ulflags's return value will be as if "-a -b -c" were
-        found.
+        If getopt() finds "-a" on the command line, then
+        bb_getopt_ulflags's return value will be as if "-a -b -c" were
+        found.
 
  "ww"   Adjacent double options have a counter associated which indicates
-        the number of occurences of the option.
-        For example the ps applet needs:
-        if w is given once, GNU ps sets the width to 132,
-        if w is given more than once, it is "unlimited"
-
-        int w_counter = 0;
-        bb_opt_complementally = "ww";
-        bb_getopt_ulflags(argc, argv, "w", &w_counter);
-        if (w_counter)
-                width = (w_counter == 1) ? 132 : INT_MAX;
-        else
-                get_terminal_width(...&width...);
-
-        w_counter is a pointer to an integer. It has to be passed to
-        bb_getopt_ulflags() after all other option argument sinks.
-
-        For example: accept multiple -v to indicate the level of verbosity
-        and for each -b optarg, add optarg to my_b. Finally, if b is given,
-        turn off c and vice versa:
-
-        llist_t *my_b = NULL;
-        int verbose_level = 0;
-        bb_opt_complementally = "vv:b::b-c:c-b";
-        f = bb_getopt_ulflags(argc, argv, "vb:c", &my_b, &verbose_level);
-        if (f & 2)       // -c after -b unsets -b flag
-                while (my_b) { dosomething_with(my_b->data); my_b = my_b->link; }
-        if (my_b)        // but llist is stored if -b is specified
-                free_llist(my_b);
-        if (verbose_level) bb_printf("verbose level is %d\n", verbose_level);
+        the number of occurences of the option.
+        For example the ps applet needs:
+        if w is given once, GNU ps sets the width to 132,
+        if w is given more than once, it is "unlimited"
+
+        int w_counter = 0;
+        bb_opt_complementally = "ww";
+        bb_getopt_ulflags(argc, argv, "w", &w_counter);
+        if (w_counter)
+                width = (w_counter == 1) ? 132 : INT_MAX;
+        else
+                get_terminal_width(...&width...);
+
+        w_counter is a pointer to an integer. It has to be passed to
+        bb_getopt_ulflags() after all other option argument sinks.
+
+        For example: accept multiple -v to indicate the level of verbosity
+        and for each -b optarg, add optarg to my_b. Finally, if b is given,
+        turn off c and vice versa:
+
+        llist_t *my_b = NULL;
+        int verbose_level = 0;
+        bb_opt_complementally = "vv:b::b-c:c-b";
+        f = bb_getopt_ulflags(argc, argv, "vb:c", &my_b, &verbose_level);
+        if (f & 2)       // -c after -b unsets -b flag
+                while (my_b) { dosomething_with(my_b->data); my_b = my_b->link; }
+        if (my_b)        // but llist is stored if -b is specified
+                free_llist(my_b);
+        if (verbose_level) bb_printf("verbose level is %d\n", verbose_level);
 
 Special characters:
 
  "-"    A dash between two options causes the second of the two
-        to be unset (and ignored) if it is given on the command line.
+        to be unset (and ignored) if it is given on the command line.
 
-        [FIXME: what if they are the same? like "x-x"? Is it ever useful?]
+        [FIXME: what if they are the same? like "x-x"? Is it ever useful?]
 
-        For example:
-        The du applet has the options "-s" and "-d depth".  If
-        bb_getopt_ulflags finds -s, then -d is unset or if it finds -d
-        then -s is unset.  (Note:  busybox implements the GNU
-        "--max-depth" option as "-d".)  To obtain this behavior, you
-        set bb_opt_complementally = "s-d:d-s".  Only one flag value is
-        added to bb_getopt_ulflags's return value depending on the
-        position of the options on the command line.  If one of the
-        two options requires an argument pointer (":" in applet_opts
-        as in "d:") optarg is set accordingly.
+        For example:
+        The du applet has the options "-s" and "-d depth".  If
+        bb_getopt_ulflags finds -s, then -d is unset or if it finds -d
+        then -s is unset.  (Note:  busybox implements the GNU
+        "--max-depth" option as "-d".)  To obtain this behavior, you
+        set bb_opt_complementally = "s-d:d-s".  Only one flag value is
+        added to bb_getopt_ulflags's return value depending on the
+        position of the options on the command line.  If one of the
+        two options requires an argument pointer (":" in applet_opts
+        as in "d:") optarg is set accordingly.
 
-        char *smax_print_depth;
+        char *smax_print_depth;
 
-        bb_opt_complementally = "s-d:d-s:x-x";
-        opt = bb_getopt_ulflags(argc, argv, "sd:x", &smax_print_depth);
+        bb_opt_complementally = "s-d:d-s:x-x";
+        opt = bb_getopt_ulflags(argc, argv, "sd:x", &smax_print_depth);
 
-        if (opt & 2)
-                max_print_depth = atoi(smax_print_depth);
-        if (opt & 4)
-                printf("Detected odd -x usage\n");
+        if (opt & 2)
+                max_print_depth = atoi(smax_print_depth);
+        if (opt & 4)
+                printf("Detected odd -x usage\n");
 
  "-"    A dash as the first char in a bb_opt_complementally group forces
-        all arguments to be treated as options, even if they have
-        no leading dashes. Next char in this case can't be a digit (0-9),
-        use ':' or end of line. For example:
+        all arguments to be treated as options, even if they have
+        no leading dashes. Next char in this case can't be a digit (0-9),
+        use ':' or end of line. For example:
 
-        bb_opt_complementally = "-:w-x:x-w";
-        bb_getopt_ulflags(argc, argv, "wx");
+        bb_opt_complementally = "-:w-x:x-w";
+        bb_getopt_ulflags(argc, argv, "wx");
 
-        Allows any arguments to be given without a dash (./program w x)
-        as well as with a dash (./program -x).
+        Allows any arguments to be given without a dash (./program w x)
+        as well as with a dash (./program -x).
 
  "-N"   A dash as the first char in a bb_opt_complementally group followed
-        by a single digit (0-9) means that at least N non-option
-        arguments must be present on the command line
+        by a single digit (0-9) means that at least N non-option
+        arguments must be present on the command line
 
  "V-"   An option with dash before colon or end-of-line results in
-        bb_show_usage being called if this option is encountered.
-        This is typically used to implement "print verbose usage message
-        and exit" option.
+        bb_show_usage being called if this option is encountered.
+        This is typically used to implement "print verbose usage message
+        and exit" option.
 
  "--"   A double dash between two options, or between an option and a group
-        of options, means that they are mutually exclusive.  Unlike
-        the "-" case above, an error will be forced if the options
-        are used together.
-
-        For example:
-        The cut applet must have only one type of list specified, so
-        -b, -c and -f are mutally exclusive and should raise an error
-        if specified together.  In this case you must set
-        bb_opt_complementally = "b--cf:c--bf:f--bc".  If two of the
-        mutually exclusive options are found, bb_getopt_ulflags's
-        return value will have the error flag set (BB_GETOPT_ERROR) so
-        that we can check for it:
-
-        if (flags & BB_GETOPT_ERROR)
-                bb_show_usage();
+        of options, means that they are mutually exclusive.  Unlike
+        the "-" case above, an error will be forced if the options
+        are used together.
+
+        For example:
+        The cut applet must have only one type of list specified, so
+        -b, -c and -f are mutally exclusive and should raise an error
+        if specified together.  In this case you must set
+        bb_opt_complementally = "b--cf:c--bf:f--bc".  If two of the
+        mutually exclusive options are found, bb_getopt_ulflags's
+        return value will have the error flag set (BB_GETOPT_ERROR) so
+        that we can check for it:
+
+        if (flags & BB_GETOPT_ERROR)
+                bb_show_usage();
 
  "x--x" Variation of the above, it means that -x option should occur
-        at most once.
+        at most once.
 
  "?"    A "?" as the first char in a bb_opt_complementally group means:
-        if BB_GETOPT_ERROR is detected, don't return, call bb_show_usage
-        and exit instead. Next char after '?' can't be a digit.
+        if BB_GETOPT_ERROR is detected, don't return, call bb_show_usage
+        and exit instead. Next char after '?' can't be a digit.
 
  "?N"   A "?" as the first char in a bb_opt_complementally group followed
-        by a single digit (0-9) means that at most N arguments must be present
-        on the command line.
+        by a single digit (0-9) means that at most N arguments must be present
+        on the command line.
 
  "::"   A double colon after a char in bb_opt_complementally means that the
-        option can occur multiple times. Each occurrence will be saved as
-        a llist_t element instead of char*.
+        option can occur multiple times. Each occurrence will be saved as
+        a llist_t element instead of char*.
 
-        For example:
-        The grep applet can have one or more "-e pattern" arguments.
-        In this case you should use bb_getopt_ulflags() as follows:
+        For example:
+        The grep applet can have one or more "-e pattern" arguments.
+        In this case you should use bb_getopt_ulflags() as follows:
 
-        llist_t *patterns = NULL;
+        llist_t *patterns = NULL;
 
-        (this pointer must be initializated to NULL if the list is empty
-        as required by *llist_add_to(llist_t *old_head, char *new_item).)
+        (this pointer must be initializated to NULL if the list is empty
+        as required by *llist_add_to(llist_t *old_head, char *new_item).)
 
-        bb_opt_complementally = "e::";
+        bb_opt_complementally = "e::";
 
-        bb_getopt_ulflags(argc, argv, "e:", &patterns);
-        $ grep -e user -e root /etc/passwd
-        root:x:0:0:root:/root:/bin/bash
-        user:x:500:500::/home/user:/bin/bash
+        bb_getopt_ulflags(argc, argv, "e:", &patterns);
+        $ grep -e user -e root /etc/passwd
+        root:x:0:0:root:/root:/bin/bash
+        user:x:500:500::/home/user:/bin/bash
 
  "--"   A double dash at the beginning of bb_opt_complementally means the
-        argv[1] string should always be treated as options, even if it isn't
-        prefixed with a "-".  This is useful for special syntax in applets
-        such as "ar" and "tar":
-        tar xvf foo.tar
+        argv[1] string should always be treated as options, even if it isn't
+        prefixed with a "-".  This is useful for special syntax in applets
+        such as "ar" and "tar":
+        tar xvf foo.tar
 
  "?"    An "?" between an option and a group of options means that
-        at least one of them is required to occur if the first option
-        occurs in preceding command line arguments.
+        at least one of them is required to occur if the first option
+        occurs in preceding command line arguments.
 
-        For example from "id" applet:
+        For example from "id" applet:
 
-        // Don't allow -n -r -rn -ug -rug -nug -rnug
-        bb_opt_complementally = "r?ug:n?ug:?u--g:g--u";
-        flags = bb_getopt_ulflags(argc, argv, "rnug");
+        // Don't allow -n -r -rn -ug -rug -nug -rnug
+        bb_opt_complementally = "r?ug:n?ug:?u--g:g--u";
+        flags = bb_getopt_ulflags(argc, argv, "rnug");
 
-        This example allowed only:
-        $ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng
+        This example allowed only:
+        $ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng
 
  "X"    A bb_opt_complementally group with just a single letter means
-        that this option is required. If more than one such group exists,
-        at least one option is required to occur (not all of them).
-        For example from "start-stop-daemon" applet:
+        that this option is required. If more than one such group exists,
+        at least one option is required to occur (not all of them).
+        For example from "start-stop-daemon" applet:
 
-        // Don't allow -KS -SK, but -S or -K is required
-        bb_opt_complementally = "K:S:?K--S:S--K";
-        flags = bb_getopt_ulflags(argc, argv, "KS...);
+        // Don't allow -KS -SK, but -S or -K is required
+        bb_opt_complementally = "K:S:?K--S:S--K";
+        flags = bb_getopt_ulflags(argc, argv, "KS...);
 
- Don't forget to use ':'. For example "?322-22-23X-x-a" is interpreted as
- "?3:22:-2:2-2:2-3Xa:2--x": max 3 args; count uses of '-2'; min 2 args;
- if there is a '-2' option then unset '-3', '-X' and '-a'; if there is
- a '-2' and after it a '-x' then error out.
 
+        Don't forget to use ':'. For example, "?322-22-23X-x-a"
+        is interpreted as "?3:22:-2:2-2:2-3Xa:2--x" -
+        max 3 args; count uses of '-2'; min 2 args; if there is
+        a '-2' option then unset '-3', '-X' and '-a'; if there is
+        a '-2' and after it a '-x' then error out.
 */
 
 /* this should be bb_opt_complementary, but we'll just keep it as