diff options
Diffstat (limited to 'busybox/docs/style-guide.txt')
-rw-r--r-- | busybox/docs/style-guide.txt | 680 |
1 files changed, 680 insertions, 0 deletions
diff --git a/busybox/docs/style-guide.txt b/busybox/docs/style-guide.txt new file mode 100644 index 000000000..915d9b27d --- /dev/null +++ b/busybox/docs/style-guide.txt | |||
@@ -0,0 +1,680 @@ | |||
1 | Busybox Style Guide | ||
2 | =================== | ||
3 | |||
4 | This document describes the coding style conventions used in Busybox. If you | ||
5 | add a new file to Busybox or are editing an existing file, please format your | ||
6 | code according to this style. If you are the maintainer of a file that does | ||
7 | not follow these guidelines, please -- at your own convenience -- modify the | ||
8 | file(s) you maintain to bring them into conformance with this style guide. | ||
9 | Please note that this is a low priority task. | ||
10 | |||
11 | To help you format the whitespace of your programs, an ".indent.pro" file is | ||
12 | included in the main Busybox source directory that contains option flags to | ||
13 | format code as per this style guide. This way you can run GNU indent on your | ||
14 | files by typing 'indent myfile.c myfile.h' and it will magically apply all the | ||
15 | right formatting rules to your file. Please _do_not_ run this on all the files | ||
16 | in the directory, just your own. | ||
17 | |||
18 | |||
19 | |||
20 | Declaration Order | ||
21 | ----------------- | ||
22 | |||
23 | Here is the order in which code should be laid out in a file: | ||
24 | |||
25 | - commented program name and one-line description | ||
26 | - commented author name and email address(es) | ||
27 | - commented GPL boilerplate | ||
28 | - commented longer description / notes for the program (if needed) | ||
29 | - #includes of .h files with angle brackets (<>) around them | ||
30 | - #includes of .h files with quotes ("") around them | ||
31 | - #defines (if any, note the section below titled "Avoid the Preprocessor") | ||
32 | - const and global variables | ||
33 | - function declarations (if necessary) | ||
34 | - function implementations | ||
35 | |||
36 | |||
37 | |||
38 | Whitespace and Formatting | ||
39 | ------------------------- | ||
40 | |||
41 | This is everybody's favorite flame topic so let's get it out of the way right | ||
42 | up front. | ||
43 | |||
44 | |||
45 | Tabs vs. Spaces in Line Indentation | ||
46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
47 | |||
48 | The preference in Busybox is to indent lines with tabs. Do not indent lines | ||
49 | with spaces and do not indents lines using a mixture of tabs and spaces. (The | ||
50 | indentation style in the Apache and Postfix source does this sort of thing: | ||
51 | \s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is | ||
52 | multi-line comments that use an asterisk at the beginning of each line, i.e.: | ||
53 | |||
54 | /t/* | ||
55 | /t * This is a block comment. | ||
56 | /t * Note that it has multiple lines | ||
57 | /t * and that the beginning of each line has a tab plus a space | ||
58 | /t * except for the opening '/*' line where the slash | ||
59 | /t * is used instead of a space. | ||
60 | /t */ | ||
61 | |||
62 | Furthermore, The preference is that tabs be set to display at four spaces | ||
63 | wide, but the beauty of using only tabs (and not spaces) at the beginning of | ||
64 | lines is that you can set your editor to display tabs at *whatever* number of | ||
65 | spaces is desired and the code will still look fine. | ||
66 | |||
67 | |||
68 | Operator Spacing | ||
69 | ~~~~~~~~~~~~~~~~ | ||
70 | |||
71 | Put spaces between terms and operators. Example: | ||
72 | |||
73 | Don't do this: | ||
74 | |||
75 | for(i=0;i<num_items;i++){ | ||
76 | |||
77 | Do this instead: | ||
78 | |||
79 | for (i = 0; i < num_items; i++) { | ||
80 | |||
81 | While it extends the line a bit longer, the spaced version is more | ||
82 | readable. An allowable exception to this rule is the situation where | ||
83 | excluding the spacing makes it more obvious that we are dealing with a | ||
84 | single term (even if it is a compound term) such as: | ||
85 | |||
86 | if (str[idx] == '/' && str[idx-1] != '\\') | ||
87 | |||
88 | or | ||
89 | |||
90 | if ((argc-1) - (optind+1) > 0) | ||
91 | |||
92 | |||
93 | Bracket Spacing | ||
94 | ~~~~~~~~~~~~~~~ | ||
95 | |||
96 | If an opening bracket starts a function, it should be on the | ||
97 | next line with no spacing before it. However, if a bracket follows an opening | ||
98 | control block, it should be on the same line with a single space (not a tab) | ||
99 | between it and the opening control block statement. Examples: | ||
100 | |||
101 | Don't do this: | ||
102 | |||
103 | while (!done) | ||
104 | { | ||
105 | |||
106 | do | ||
107 | { | ||
108 | |||
109 | Don't do this either: | ||
110 | |||
111 | while (!done){ | ||
112 | |||
113 | do{ | ||
114 | |||
115 | And for heaven's sake, don't do this: | ||
116 | |||
117 | while (!done) | ||
118 | { | ||
119 | |||
120 | do | ||
121 | { | ||
122 | |||
123 | Do this instead: | ||
124 | |||
125 | while (!done) { | ||
126 | |||
127 | do { | ||
128 | |||
129 | |||
130 | Spacing around Parentheses | ||
131 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
132 | |||
133 | Put a space between C keywords and left parens, but not between function names | ||
134 | and the left paren that starts it's parameter list (whether it is being | ||
135 | declared or called). Examples: | ||
136 | |||
137 | Don't do this: | ||
138 | |||
139 | while(foo) { | ||
140 | for(i = 0; i < n; i++) { | ||
141 | |||
142 | Do this instead: | ||
143 | |||
144 | while (foo) { | ||
145 | for (i = 0; i < n; i++) { | ||
146 | |||
147 | But do functions like this: | ||
148 | |||
149 | static int my_func(int foo, char bar) | ||
150 | ... | ||
151 | baz = my_func(1, 2); | ||
152 | |||
153 | Also, don't put a space between the left paren and the first term, nor between | ||
154 | the last arg and the right paren. | ||
155 | |||
156 | Don't do this: | ||
157 | |||
158 | if ( x < 1 ) | ||
159 | strcmp( thisstr, thatstr ) | ||
160 | |||
161 | Do this instead: | ||
162 | |||
163 | if (x < 1) | ||
164 | strcmp(thisstr, thatstr) | ||
165 | |||
166 | |||
167 | Cuddled Elses | ||
168 | ~~~~~~~~~~~~~ | ||
169 | |||
170 | Also, please "cuddle" your else statements by putting the else keyword on the | ||
171 | same line after the right bracket that closes an 'if' statement. | ||
172 | |||
173 | Don't do this: | ||
174 | |||
175 | if (foo) { | ||
176 | stmt; | ||
177 | } | ||
178 | else { | ||
179 | stmt; | ||
180 | } | ||
181 | |||
182 | Do this instead: | ||
183 | |||
184 | if (foo) { | ||
185 | stmt; | ||
186 | } else { | ||
187 | stmt; | ||
188 | } | ||
189 | |||
190 | The exception to this rule is if you want to include a comment before the else | ||
191 | block. Example: | ||
192 | |||
193 | if (foo) { | ||
194 | stmts... | ||
195 | } | ||
196 | /* otherwise, we're just kidding ourselves, so re-frob the input */ | ||
197 | else { | ||
198 | other_stmts... | ||
199 | } | ||
200 | |||
201 | |||
202 | |||
203 | Variable and Function Names | ||
204 | --------------------------- | ||
205 | |||
206 | Use the K&R style with names in all lower-case and underscores occasionally | ||
207 | used to separate words (e.g., "variable_name" and "numchars" are both | ||
208 | acceptable). Using underscores makes variable and function names more readable | ||
209 | because it looks like whitespace; using lower-case is easy on the eyes. | ||
210 | |||
211 | Frowned upon: | ||
212 | |||
213 | hitList | ||
214 | TotalChars | ||
215 | szFileName | ||
216 | pf_Nfol_TriState | ||
217 | |||
218 | Preferred: | ||
219 | |||
220 | hit_list | ||
221 | total_chars | ||
222 | file_name | ||
223 | sensible_name | ||
224 | |||
225 | Exceptions: | ||
226 | |||
227 | - Enums, macros, and constant variables are occasionally written in all | ||
228 | upper-case with words optionally seperatedy by underscores (i.e. FIFOTYPE, | ||
229 | ISBLKDEV()). | ||
230 | |||
231 | - Nobody is going to get mad at you for using 'pvar' as the name of a | ||
232 | variable that is a pointer to 'var'. | ||
233 | |||
234 | |||
235 | Converting to K&R | ||
236 | ~~~~~~~~~~~~~~~~~ | ||
237 | |||
238 | The Busybox codebase is very much a mixture of code gathered from a variety of | ||
239 | sources. This explains why the current codebase contains such a hodge-podge of | ||
240 | different naming styles (Java, Pascal, K&R, just-plain-weird, etc.). The K&R | ||
241 | guideline explained above should therefore be used on new files that are added | ||
242 | to the repository. Furthermore, the maintainer of an existing file that uses | ||
243 | alternate naming conventions should, at his own convenience, convert those | ||
244 | names over to K&R style. Converting variable names is a very low priority | ||
245 | task. | ||
246 | |||
247 | If you want to do a search-and-replace of a single variable name in different | ||
248 | files, you can do the following in the busybox directory: | ||
249 | |||
250 | $ perl -pi -e 's/\bOldVar\b/new_var/g' *.[ch] | ||
251 | |||
252 | If you want to convert all the non-K&R vars in your file all at once, follow | ||
253 | these steps: | ||
254 | |||
255 | - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This | ||
256 | does not do the actual conversion, rather, it generates a script called | ||
257 | 'convertme.pl' that shows what will be converted, giving you a chance to | ||
258 | review the changes beforehand. | ||
259 | |||
260 | - Review the 'convertme.pl' script that gets generated in the busybox | ||
261 | directory and remove / edit any of the substitutions in there. Please | ||
262 | especially check for false positives (strings that should not be | ||
263 | converted). | ||
264 | |||
265 | - Type './convertme.pl same-files-as-before' to perform the actual | ||
266 | conversion. | ||
267 | |||
268 | - Compile and see if everything still works. | ||
269 | |||
270 | Please be aware of changes that have cascading effects into other files. For | ||
271 | example, if you're changing the name of something in, say utility.c, you | ||
272 | should probably run 'examples/mk2knr.pl utility.c' at first, but when you run | ||
273 | the 'convertme.pl' script you should run it on _all_ files like so: | ||
274 | './convertme.pl *.[ch]'. | ||
275 | |||
276 | |||
277 | |||
278 | Avoid The Preprocessor | ||
279 | ---------------------- | ||
280 | |||
281 | At best, the preprocessor is a necessary evil, helping us account for platform | ||
282 | and architecture differences. Using the preprocessor unnecessarily is just | ||
283 | plain evil. | ||
284 | |||
285 | |||
286 | The Folly of #define | ||
287 | ~~~~~~~~~~~~~~~~~~~~ | ||
288 | |||
289 | Use 'const <type> var' for declaring constants. | ||
290 | |||
291 | Don't do this: | ||
292 | |||
293 | #define var 80 | ||
294 | |||
295 | Do this instead, when the variable is in a header file and will be used in | ||
296 | several source files: | ||
297 | |||
298 | const int var = 80; | ||
299 | |||
300 | Or do this when the variable is used only in a single source file: | ||
301 | |||
302 | static const int var = 80; | ||
303 | |||
304 | Declaring variables as '[static] const' gives variables an actual type and | ||
305 | makes the compiler do type checking for you; the preprocessor does _no_ type | ||
306 | checking whatsoever, making it much more error prone. Declaring variables with | ||
307 | '[static] const' also makes debugging programs much easier since the value of | ||
308 | the variable can be easily queried and displayed. | ||
309 | |||
310 | |||
311 | The Folly of Macros | ||
312 | ~~~~~~~~~~~~~~~~~~~ | ||
313 | |||
314 | Use 'static inline' instead of a macro. | ||
315 | |||
316 | Don't do this: | ||
317 | |||
318 | #define mini_func(param1, param2) (param1 << param2) | ||
319 | |||
320 | Do this instead: | ||
321 | |||
322 | static inline int mini_func(int param1, param2) | ||
323 | { | ||
324 | return (param1 << param2); | ||
325 | } | ||
326 | |||
327 | Static inline functions are greatly preferred over macros. They provide type | ||
328 | safety, have no length limitations, no formatting limitations, have an actual | ||
329 | return value, and under gcc they are as cheap as macros. Besides, really long | ||
330 | macros with backslashes at the end of each line are ugly as sin. | ||
331 | |||
332 | |||
333 | The Folly of #ifdef | ||
334 | ~~~~~~~~~~~~~~~~~~~ | ||
335 | |||
336 | Code cluttered with ifdefs is difficult to read and maintain. Don't do it. | ||
337 | Instead, put your ifdefs at the top of your .c file (or in a header), and | ||
338 | conditionally define 'static inline' functions, (or *maybe* macros), which are | ||
339 | used in the code. | ||
340 | |||
341 | Don't do this: | ||
342 | |||
343 | ret = my_func(bar, baz); | ||
344 | if (!ret) | ||
345 | return -1; | ||
346 | #ifdef CONFIG_FEATURE_FUNKY | ||
347 | maybe_do_funky_stuff(bar, baz); | ||
348 | #endif | ||
349 | |||
350 | Do this instead: | ||
351 | |||
352 | (in .h header file) | ||
353 | |||
354 | #ifdef CONFIG_FEATURE_FUNKY | ||
355 | static inline void maybe_do_funky_stuff (int bar, int baz) | ||
356 | { | ||
357 | /* lotsa code in here */ | ||
358 | } | ||
359 | #else | ||
360 | static inline void maybe_do_funky_stuff (int bar, int baz) {} | ||
361 | #endif | ||
362 | |||
363 | (in the .c source file) | ||
364 | |||
365 | ret = my_func(bar, baz); | ||
366 | if (!ret) | ||
367 | return -1; | ||
368 | maybe_do_funky_stuff(bar, baz); | ||
369 | |||
370 | The great thing about this approach is that the compiler will optimize away | ||
371 | the "no-op" case (the empty function) when the feature is turned off. | ||
372 | |||
373 | Note also the use of the word 'maybe' in the function name to indicate | ||
374 | conditional execution. | ||
375 | |||
376 | |||
377 | |||
378 | Notes on Strings | ||
379 | ---------------- | ||
380 | |||
381 | Strings in C can get a little thorny. Here's some guidelines for dealing with | ||
382 | strings in Busybox. (There is surely more that could be added to this | ||
383 | section.) | ||
384 | |||
385 | |||
386 | String Files | ||
387 | ~~~~~~~~~~~~ | ||
388 | |||
389 | Put all help/usage messages in usage.c. Put other strings in messages.c. | ||
390 | Putting these strings into their own file is a calculated decision designed to | ||
391 | confine spelling errors to a single place and aid internationalization | ||
392 | efforts, if needed. (Side Note: we might want to use a single file - maybe | ||
393 | called 'strings.c' - instead of two, food for thought). | ||
394 | |||
395 | |||
396 | Testing String Equivalence | ||
397 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
398 | |||
399 | There's a right way and a wrong way to test for sting equivalence with | ||
400 | strcmp(): | ||
401 | |||
402 | The wrong way: | ||
403 | |||
404 | if (!strcmp(string, "foo")) { | ||
405 | ... | ||
406 | |||
407 | The right way: | ||
408 | |||
409 | if (strcmp(string, "foo") == 0){ | ||
410 | ... | ||
411 | |||
412 | The use of the "equals" (==) operator in the latter example makes it much more | ||
413 | obvious that you are testing for equivalence. The former example with the | ||
414 | "not" (!) operator makes it look like you are testing for an error. In a more | ||
415 | perfect world, we would have a streq() function in the string library, but | ||
416 | that ain't the world we're living in. | ||
417 | |||
418 | |||
419 | Avoid Dangerous String Functions | ||
420 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
421 | |||
422 | Unfortunately, the way C handles strings makes them prone to overruns when | ||
423 | certain library functions are (mis)used. The following table offers a summary | ||
424 | of some of the more notorious troublemakers: | ||
425 | |||
426 | function overflows preferred | ||
427 | ---------------------------------------- | ||
428 | strcpy dest string strncpy | ||
429 | strcat dest string strncat | ||
430 | gets string it gets fgets | ||
431 | getwd buf string getcwd | ||
432 | [v]sprintf str buffer [v]snprintf | ||
433 | realpath path buffer use with pathconf | ||
434 | [vf]scanf its arguments just avoid it | ||
435 | |||
436 | |||
437 | The above is by no means a complete list. Be careful out there. | ||
438 | |||
439 | |||
440 | |||
441 | Avoid Big Static Buffers | ||
442 | ------------------------ | ||
443 | |||
444 | First, some background to put this discussion in context: Static buffers look | ||
445 | like this in code: | ||
446 | |||
447 | /* in a .c file outside any functions */ | ||
448 | static char *buffer[BUFSIZ]; /* happily used by any function in this file, | ||
449 | but ick! big! */ | ||
450 | |||
451 | The problem with these is that any time any busybox app is run, you pay a | ||
452 | memory penalty for this buffer, even if the applet that uses said buffer is | ||
453 | not run. This can be fixed, thusly: | ||
454 | |||
455 | static char *buffer; | ||
456 | ... | ||
457 | other_func() | ||
458 | { | ||
459 | strcpy(buffer, lotsa_chars); /* happily uses global *buffer */ | ||
460 | ... | ||
461 | foo_main() | ||
462 | { | ||
463 | buffer = xmalloc(sizeof(char)*BUFSIZ); | ||
464 | ... | ||
465 | |||
466 | However, this approach trades bss segment for text segment. Rather than | ||
467 | mallocing the buffers (and thus growing the text size), buffers can be | ||
468 | declared on the stack in the *_main() function and made available globally by | ||
469 | assigning them to a global pointer thusly: | ||
470 | |||
471 | static char *pbuffer; | ||
472 | ... | ||
473 | other_func() | ||
474 | { | ||
475 | strcpy(pbuffer, lotsa_chars); /* happily uses global *pbuffer */ | ||
476 | ... | ||
477 | foo_main() | ||
478 | { | ||
479 | char *buffer[BUFSIZ]; /* declared locally, on stack */ | ||
480 | pbuffer = buffer; /* but available globally */ | ||
481 | ... | ||
482 | |||
483 | This last approach has some advantages (low code size, space not used until | ||
484 | it's needed), but can be a problem in some low resource machines that have | ||
485 | very limited stack space (e.g., uCLinux). | ||
486 | |||
487 | A macro is declared in busybox.h that implements compile-time selection | ||
488 | between xmalloc() and stack creation, so you can code the line in question as | ||
489 | |||
490 | RESERVE_CONFIG_BUFFER(buffer, BUFSIZ); | ||
491 | |||
492 | and the right thing will happen, based on your configuration. | ||
493 | |||
494 | |||
495 | |||
496 | Miscellaneous Coding Guidelines | ||
497 | ------------------------------- | ||
498 | |||
499 | The following are important items that don't fit into any of the above | ||
500 | sections. | ||
501 | |||
502 | |||
503 | Model Busybox Applets After GNU Counterparts | ||
504 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
505 | |||
506 | When in doubt about the proper behavior of a Busybox program (output, | ||
507 | formatting, options, etc.), model it after the equivalent GNU program. | ||
508 | Doesn't matter how that program behaves on some other flavor of *NIX; doesn't | ||
509 | matter what the POSIX standard says or doesn't say, just model Busybox | ||
510 | programs after their GNU counterparts and it will make life easier on (nearly) | ||
511 | everyone. | ||
512 | |||
513 | The only time we deviate from emulating the GNU behavior is when: | ||
514 | |||
515 | - We are deliberately not supporting a feature (such as a command line | ||
516 | switch) | ||
517 | - Emulating the GNU behavior is prohibitively expensive (lots more code | ||
518 | would be required, lots more memory would be used, etc.) | ||
519 | - The difference is minor or cosmetic | ||
520 | |||
521 | A note on the 'cosmetic' case: Output differences might be considered | ||
522 | cosmetic, but if the output is significant enough to break other scripts that | ||
523 | use the output, it should really be fixed. | ||
524 | |||
525 | |||
526 | Scope | ||
527 | ~~~~~ | ||
528 | |||
529 | If a const variable is used only in a single source file, put it in the source | ||
530 | file and not in a header file. Likewise, if a const variable is used in only | ||
531 | one function, do not make it global to the file. Instead, declare it inside | ||
532 | the function body. Bottom line: Make a conscious effort to limit declarations | ||
533 | to the smallest scope possible. | ||
534 | |||
535 | Inside applet files, all functions should be declared static so as to keep the | ||
536 | global name space clean. The only exception to this rule is the "applet_main" | ||
537 | function which must be declared extern. | ||
538 | |||
539 | If you write a function that performs a task that could be useful outside the | ||
540 | immediate file, turn it into a general-purpose function with no ties to any | ||
541 | applet and put it in the utility.c file instead. | ||
542 | |||
543 | |||
544 | Brackets Are Your Friends | ||
545 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
546 | |||
547 | Please use brackets on all if and else statements, even if it is only one | ||
548 | line. Example: | ||
549 | |||
550 | Don't do this: | ||
551 | |||
552 | if (foo) | ||
553 | stmt1; | ||
554 | stmt2 | ||
555 | stmt3; | ||
556 | |||
557 | Do this instead: | ||
558 | |||
559 | if (foo) { | ||
560 | stmt1; | ||
561 | } | ||
562 | stmt2 | ||
563 | stmt3; | ||
564 | |||
565 | The "bracketless" approach is error prone because someday you might add a line | ||
566 | like this: | ||
567 | |||
568 | if (foo) | ||
569 | stmt1; | ||
570 | new_line(); | ||
571 | stmt2 | ||
572 | stmt3; | ||
573 | |||
574 | And the resulting behavior of your program would totally bewilder you. (Don't | ||
575 | laugh, it happens to us all.) Remember folks, this is C, not Python. | ||
576 | |||
577 | |||
578 | Function Declarations | ||
579 | ~~~~~~~~~~~~~~~~~~~~~ | ||
580 | |||
581 | Do not use old-style function declarations that declare variable types between | ||
582 | the parameter list and opening bracket. Example: | ||
583 | |||
584 | Don't do this: | ||
585 | |||
586 | int foo(parm1, parm2) | ||
587 | char parm1; | ||
588 | float parm2; | ||
589 | { | ||
590 | .... | ||
591 | |||
592 | Do this instead: | ||
593 | |||
594 | int foo(char parm1, float parm2) | ||
595 | { | ||
596 | .... | ||
597 | |||
598 | The only time you would ever need to use the old declaration syntax is to | ||
599 | support ancient, antediluvian compilers. To our good fortune, we have access | ||
600 | to more modern compilers and the old declaration syntax is neither necessary | ||
601 | nor desired. | ||
602 | |||
603 | |||
604 | Emphasizing Logical Blocks | ||
605 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
606 | |||
607 | Organization and readability are improved by putting extra newlines around | ||
608 | blocks of code that perform a single task. These are typically blocks that | ||
609 | begin with a C keyword, but not always. | ||
610 | |||
611 | Furthermore, you should put a single comment (not necessarily one line, just | ||
612 | one comment) before the block, rather than commenting each and every line. | ||
613 | There is an optimal ammount of commenting that a program can have; you can | ||
614 | comment too much as well as too little. | ||
615 | |||
616 | A picture is really worth a thousand words here, the following example | ||
617 | illustrates how to emphasize logical blocks: | ||
618 | |||
619 | while (line = get_line_from_file(fp)) { | ||
620 | |||
621 | /* eat the newline, if any */ | ||
622 | chomp(line); | ||
623 | |||
624 | /* ignore blank lines */ | ||
625 | if (strlen(file_to_act_on) == 0) { | ||
626 | continue; | ||
627 | } | ||
628 | |||
629 | /* if the search string is in this line, print it, | ||
630 | * unless we were told to be quiet */ | ||
631 | if (strstr(line, search) && !be_quiet) { | ||
632 | puts(line); | ||
633 | } | ||
634 | |||
635 | /* clean up */ | ||
636 | free(line); | ||
637 | } | ||
638 | |||
639 | |||
640 | Processing Options with getopt | ||
641 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
642 | |||
643 | If your applet needs to process command-line switches, please use getopt() to | ||
644 | do so. Numerous examples can be seen in many of the existing applets, but | ||
645 | basically it boils down to two things: at the top of the .c file, have this | ||
646 | line in the midst of your #includes: | ||
647 | |||
648 | #include <getopt.h> | ||
649 | |||
650 | And a code block similar to the following near the top of your applet_main() | ||
651 | routine: | ||
652 | |||
653 | while ((opt = getopt(argc, argv, "abc")) > 0) { | ||
654 | switch (opt) { | ||
655 | case 'a': | ||
656 | do_a_opt = 1; | ||
657 | break; | ||
658 | case 'b': | ||
659 | do_b_opt = 1; | ||
660 | break; | ||
661 | case 'c': | ||
662 | do_c_opt = 1; | ||
663 | break; | ||
664 | default: | ||
665 | show_usage(); /* in utility.c */ | ||
666 | } | ||
667 | } | ||
668 | |||
669 | If your applet takes no options (such as 'init'), there should be a line | ||
670 | somewhere in the file reads: | ||
671 | |||
672 | /* no options, no getopt */ | ||
673 | |||
674 | That way, when people go grepping to see which applets need to be converted to | ||
675 | use getopt, they won't get false positives. | ||
676 | |||
677 | Additional Note: Do not use the getopt_long library function and do not try to | ||
678 | hand-roll your own long option parsing. Busybox applets should only support | ||
679 | short options. Explanations and examples of the short options should be | ||
680 | documented in usage.h. | ||