f0d6cc8ca
Denis Vlasenko
2006-09-29
Subject
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).
SOURCE BUG
This commit was genuinely broken at the time (not related to our build system): scripts/config/mkconfigs.c (2005-08-01 - 2006-10-05 arasi) uretilen bbconfigopts.h icine .config satirlarini kacissiz, ham newline'larla gömüyordu - gecerli C degildi, busybox'un kendi bb_mkdep araci bile parse edemiyordu (7d219aab7 ile duzeltildi, mkconfigs shell scripte cevrildi)
Binary
No binary (build failed)
Architecture & Compiler Flags
—
Build Log
(log yok)
Commit Diff GitHub →
libbb/getopt_ulflags.c+189 -183
| @@ -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 | |