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).
This commit is contained in:
Denis Vlasenko
parent
b02ef82c99
commit
f0d6cc8ca9
@ -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"
|
||||
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...);
|
||||
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.
|
||||
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:
|
||||
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);
|
||||
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.
|
||||
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:
|
||||
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();
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user