Whitespace and documentation cleanup from Dennis Vlasenko.

This commit is contained in:
Rob Landley 2006-05-03 21:23:15 +00:00
parent 425e7584a4
commit f76cd964ec

View File

@ -26,7 +26,7 @@
#include <stdlib.h> #include <stdlib.h>
#include "libbb.h" #include "libbb.h"
/* Documentation ! /* Documentation
unsigned long unsigned long
bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...) bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
@ -44,13 +44,13 @@ bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
flags = bb_getopt_ulflags(argc, argv, "rnug"); flags = bb_getopt_ulflags(argc, argv, "rnug");
"r" will add 1 (bit 1 : 0x01) "r" will add 1 (bit 0)
"n" will add 2 (bit 2 : 0x02) "n" will add 2 (bit 1)
"u will add 4 (bit 3 : 0x03) "u will add 4 (bit 2)
"g" will add 8 (bit 4 : 0x04) "g" will add 8 (bit 3)
and so on. You can also look at the return value as a bit and so on. You can also look at the return value as a bit
field and each option sets one of bits. field and each option sets one bit.
":" If one of the options requires an argument, then add a ":" ":" If one of the options requires an argument, then add a ":"
after the char in applet_opts and provide a pointer to store after the char in applet_opts and provide a pointer to store
@ -65,7 +65,7 @@ bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
&pointer_to_arg_for_a, &pointer_to_arg_for_b, &pointer_to_arg_for_a, &pointer_to_arg_for_b,
&pointer_to_arg_for_c, &pointer_to_arg_for_d); &pointer_to_arg_for_c, &pointer_to_arg_for_d);
The type of the pointer (char* or llist_t *) may be controlled The type of the pointer (char* or llist_t*) may be controlled
by the "::" special separator that is set in the external string by the "::" special separator that is set in the external string
bb_opt_complementally (see below for more info). bb_opt_complementally (see below for more info).
@ -76,23 +76,24 @@ bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
env -i ls -d / env -i ls -d /
Here we want env to process just the '-i', not the '-d'. Here we want env to process just the '-i', not the '-d'.
static const struct option bb_default_long_options[] const struct option *bb_applet_long_options
This struct allows you to define long options. The syntax for This struct allows you to define long options. The syntax for
declaring the array is just like that of getopt's longopts. declaring the array is just like that of getopt's longopts.
(see getopt(3)) (see getopt(3))
static const struct option applet_long_options[] = { static const struct option applet_long_options[] = {
{ "verbose", 0, 0, v }, { "verbose", 0, 0, 'v' },
{ 0, 0, 0, 0 } { 0, 0, 0, 0 }
}; };
bb_applet_long_options = applet_long_options; bb_applet_long_options = applet_long_options;
The last argument (val) can undefined from applet_opts. The last member of struct option (val) typically is set to
If you use this, then: matching short option from applet_opts. If there is no matching
char in applet_opts, then:
- return bit have next position after short options - return bit have next position after short options
- if has_arg is not "no_argument", use ptr for arg also - if has_arg is not "no_argument", use ptr for arg also
- bb_opt_complementally have effects for this too - bb_opt_complementally affects it too
Note: a good applet will make long options configurable via the Note: a good applet will make long options configurable via the
config process and not a required feature. The current standard config process and not a required feature. The current standard
@ -120,7 +121,7 @@ const char *bb_opt_complementally
found. found.
"ww" Adjacent double options have a counter associated which indicates "ww" Adjacent double options have a counter associated which indicates
the number of occurances of the option. the number of occurences of the option.
For example the ps applet needs: For example the ps applet needs:
if w is given once, GNU ps sets the width to 132, if w is given once, GNU ps sets the width to 132,
if w is given more than once, it is "unlimited" if w is given more than once, it is "unlimited"
@ -144,17 +145,18 @@ const char *bb_opt_complementally
int verbose_level = 0; int verbose_level = 0;
bb_opt_complementally = "vv:b::b-c:c-b"; bb_opt_complementally = "vv:b::b-c:c-b";
f = bb_getopt_ulflags(argc, argv, "vb:c", &my_b, &verbose_level); f = bb_getopt_ulflags(argc, argv, "vb:c", &my_b, &verbose_level);
if((f & 2)) // -c after -b unset this -b flag if((f & 2)) // -c after -b unsets -b flag
while (my_b) { dosomething_with(my_b->data) ; my_b = my_b->link; } while(my_b) { dosomething_with(my_b->data) ; my_b = my_b->link; }
if(my_b) // but llist stored always if -b found if(my_b) // but llist is stored if -b is specified
free_llist(my_b); free_llist(my_b);
if (verbose_level) bb_printf("verbose level is %d\n", verbose_level); if(verbose_level) bb_printf("verbose level is %d\n", verbose_level);
Special characters: Special characters:
"-" A dash between two options causes the second of the two "-" A dash between two options causes the second of the two
to be unset (and ignored or triggered) if it is given on to be unset (and ignored) if it is given on the command line.
the command line.
[FIXME: what if they are the same? like "x-x"? Is it ever useful?]
For example: For example:
The du applet has the options "-s" and "-d depth". If The du applet has the options "-s" and "-d depth". If
@ -172,28 +174,30 @@ Special characters:
bb_opt_complementally = "s-d:d-s:x-x"; bb_opt_complementally = "s-d:d-s:x-x";
opt = bb_getopt_ulflags(argc, argv, "sd:x", &smax_print_depth); opt = bb_getopt_ulflags(argc, argv, "sd:x", &smax_print_depth);
if (opt & 2) { if (opt & 2)
max_print_depth = atoi(smax_print_depth); max_print_depth = atoi(smax_print_depth);
} if (opt & 4)
if(opt & 4) printf("Detected odd -x usage\n");
printf("Detected odd -x usaging\n");
"-" A dash as the first char in a bb_opt_complementally group means to "-" A dash as the first char in a bb_opt_complementally group forces
convert the arguments as option. Next char for this case can't set all arguments to be treated as options, even if they have
[0-9], recomended use ':' or end of line. For example: 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_opt_complementally = "-:w-x:x-w";
bb_getopt_ulflags(argc, argv, "wx"); bb_getopt_ulflags(argc, argv, "wx");
Allows any arguments to be given without a dash (./program w x) Allows any arguments to be given without a dash (./program w x)
as well as with a dash (./program -x). Why unset -w see above. as well as with a dash (./program -x).
"-N" A dash as the first char in a bb_opt_complementally group with "-N" A dash as the first char in a bb_opt_complementally group followed
number 0-9 as one char is means check minimal arguments required. by a single digit (0-9) means that at least N non-option
arguments must be present on the command line
"V-" A option with dash before colon or end line indicate: call "V-" An option with dash before colon or end-of-line results in
bb_show_usage if this option give, for example verbose bb_show_usage being called if this option is encountered.
usage option. 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 "--" A double dash between two options, or between an option and a group
of options, means that they are mutually exclusive. Unlike of options, means that they are mutually exclusive. Unlike
@ -212,16 +216,17 @@ Special characters:
if (flags & BB_GETOPT_ERROR) if (flags & BB_GETOPT_ERROR)
bb_show_usage(); bb_show_usage();
"?" A "ask" as the first char in a bb_opt_complementally group give: "?" A "?" as the first char in a bb_opt_complementally group means:
if previous point set BB_GETOPT_ERROR, don't return and if BB_GETOPT_ERROR is detected, don't return, call bb_show_usage
call previous example internally. Next char for this case can't and exit instead. Next char after '?' can't be a digit.
set to [0-9], recomended use ':' or end of line.
"?N" A "ask" as the first char in a bb_opt_complementally group with "?N" A "?" as the first char in a bb_opt_complementally group followed
number 0-9 as one char is means check maximal arguments possible. 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 "::" A double colon after a char in bb_opt_complementally means that the
option can occur multiple times: option can occur multiple times. Each occurrence will be saved as
a llist_t element instead of char*.
For example: For example:
The grep applet can have one or more "-e pattern" arguments. The grep applet can have one or more "-e pattern" arguments.
@ -245,8 +250,10 @@ Special characters:
such as "ar" and "tar": such as "ar" and "tar":
tar xvf foo.tar tar xvf foo.tar
"?" An "ask" between main and group options causes the second of the two "?" An "?" between an option and a group of options means that
to be depending required as or if first is given on the command line. 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 // Don't allow -n -r -rn -ug -rug -nug -rnug
@ -256,22 +263,22 @@ Special characters:
This example allowed only: This example allowed only:
$ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng $ id; id -u; id -g; id -ru; id -nu; id -rg; id -ng; id -rnu; id -rng
"X" A one options in bb_opt_complementally group means "X" A bb_opt_complementally group with just a single letter means
requires this option always with "or" logic if more one specified, that this this option is required. If more than one such group exists,
checked after switch off from complementally logic. at least one option is required to occur (not all of them).
For example from "start-stop-daemon" applet: For example from "start-stop-daemon" applet:
// Don't allow -KS -SK, but -S or -K required // Don't allow -KS -SK, but -S or -K is required
bb_opt_complementally = "K:S:?K--S:S--K"; bb_opt_complementally = "K:S:?K--S:S--K";
flags = bb_getopt_ulflags(argc, argv, "KS...); flags = bb_getopt_ulflags(argc, argv, "KS...);
"x--x" give error if double or more used -x option "x--x" give error if double or more used -x option
Don't forget ':' store. For example "?322-22-23X-x-a" interpretet as 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 args is 3, count -2 usaged, min args is 2, "?3:22:-2:2-2:2-3Xa:2--x": max 3 args; count uses of '-2'; min 2 args;
-2 option triggered, unset -3 and -X and -a if -2 any usaged, give error if if there is a '-2' option then unset '-3', '-X' and '-a'; if there is
after -2 the -x option usaged. a '-2' and after it a '-x' then error out.
*/ */