From: Mark Whitley <markw@lineo.com>
Date: Sat, 3 Mar 2001 00:44:55 +0000 (-0000)
Subject: Added some words on use of getopt in applets.
X-Git-Tag: 0_50~126
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=9ead68975c05100e4d1fda0b750fbc3688e68cfd;p=oweals%2Fbusybox.git

Added some words on use of getopt in applets.
---

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.