diff options
| -rw-r--r-- | docs/contributing.txt | 5 | ||||
| -rw-r--r-- | docs/style-guide.txt | 46 |
2 files changed, 50 insertions, 1 deletions
diff --git a/docs/contributing.txt b/docs/contributing.txt index 696e63c2c..d9a7d3d00 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -197,6 +197,11 @@ Janitorial Work These are dirty jobs, but somebody's gotta do 'em. + - Converting applets to use getopt() for option processing. Type 'grep -L + getopt *.c' to get a listing of the applets that currently don't use + getopt. If a .c file processes no options, it should have a line that + reads: /* no options, no getopt */ somewhere in the file. + - Security audits: http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html diff --git a/docs/style-guide.txt b/docs/style-guide.txt index 1f06662ac..b4c3bac02 100644 --- a/docs/style-guide.txt +++ b/docs/style-guide.txt @@ -26,7 +26,9 @@ Here is the order in which code should be laid out in a file: - commented author name and email address(es) - commented GPL boilerplate - commented longer description / notes for the program (if needed) - - #includes and #defines + - #includes of .h files with angle brackets (<>) around them + - #includes of .h files with quotes ("") around them + - #defines (if any, note the section below titled "Avoid the Preprocessor") - const and global variables - function declarations (if necessary) - function implementations @@ -607,3 +609,45 @@ illustrates emphasizing logical blocks: /* clean up */ free(line); } + + +Processing Options with getopt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your applet needs to process command-line switches, please use getopt() to +do so. Numerous examples can be seen in many of the existing applets, but +basically it boils down to two things: at the top of the .c file, have this +line in the midst of your #includes: + + #include <getopt.h> + +And a code block similar to the following near the top of your applet_main() +routine: + + while ((opt = getopt(argc, argv, "abc")) > 0) { + switch (opt) { + case 'a': + do_a_opt = 1; + break; + case 'b': + do_b_opt = 1; + break; + case 'c': + do_c_opt = 1; + break; + default: + show_usage(); /* in utility.c */ + } + } + +If your applet takes no options (such as 'init'), there should be a line +somewhere in the file reads: + + /* no options, no getopt */ + +That way, when people go grepping to see which applets need to be converted to +use getopt, they won't get false positives. + +Additional Note: Do not use the getopt_long library function and do not try to +hand-roll your own long option parsing. Busybox applets should only support +short options, plus explanations and examples in usage.h. |