source: MondoRescue/branches/stable/mindi-busybox/docs/style-guide.txt

Last change on this file was 1770, checked in by Bruno Cornec, 16 years ago
  • Better output for mindi-busybox revision
  • Remove dummy file created on NFS - report from Arnaud Tiger <arnaud.tiger_at_hp.com>
  • strace useful for debug
  • fix new versions for pb (2.0.0 for mindi and 1.7.2 for mindi-busybox)
  • fix build process for mindi-busybox + options used in that version (dd for label-partitions-as-necessary)
  • fix typo in label-partitions-as-necessary which doesn't seem to work
  • Update to busybox 1.7.2
  • perl is now required at restore time to support uuid swap partitions (and will be used for many other thigs

in the future for sure)

  • next mindi version will be 2.0.0 due to all the changes made in it (udev may break working distros)
  • small optimization in mindi on keyboard handling (one single find instead of multiple)
  • better interaction for USB device when launching mindi manually
  • attempt to automatically guess block disk size for ramdisk
  • fix typos in bkphw
  • Fix the remaining problem with UUID support for swap partitions
  • Updates mondoarchive man page for USB support
  • Adds preliminary Hardware support to mindi (Proliant SSSTK)
  • Tries to add udev support also for rhel4
  • Fix UUID support which was still broken.
  • Be conservative in test for the start-nfs script
  • Update config file for mindi-busybox for 1.7.2 migration
  • Try to run around a busybox bug (1.2.2 pb on inexistant links)
  • Add build content for mindi-busybox in pb
  • Remove distributions content for mindi-busybox
  • Fix a warning on inexistant raidtab
  • Solve problem on tmpfs in restore init (Problem of inexistant symlink and busybox)
  • Create MONDO_CACHE and use it everywhere + creation at start
  • Really never try to eject a USB device
  • Fix a issue with &> usage (replaced with 1> and 2>)
  • Adds magic file to depllist in order to have file working + ldd which helps for debugging issues
  • tty modes correct to avoid sh error messages
  • Use ext3 normally and not ext2 instead
  • USB device should be corrected after reading (take 1st part)
  • Adds a mount_USB_here function derived from mount_CDROM_here
  • usb detection place before /dev detection in device name at restore time
  • Fix when restoring from USB: media is asked in interactive mode
  • Adds USB support for mondorestore
  • mount_cdrom => mount_media
  • elilo.efi is now searched throughout /boot/efi and not in a fixed place as there is no standard
  • untar-and-softlink => untar (+ interface change)
  • suppress useless softlinks creation/removal in boot process
  • avoids udevd messages on groups
  • Increase # of disks to 99 as in mindi at restore time (should be a conf file parameter)
  • skip existing big file creation
  • seems to work correctly for USB mindi boot
  • Adds group and tty link to udev conf
  • Always load usb-torage (even 2.6) to initiate USB bus discovery
  • Better printing of messages
  • Attempt to fix a bug in supporting OpenSusE 10.3 kernel for initramfs (mindi may now use multiple regex for kernel initrd detection)
  • Links were not correctly done as non relative for modules in mindi
  • exclusion of modules denied now works
  • Also create modules in their ordinary place, so that classical modprobe works + copy modules.dep
  • Fix bugs for DENY_MODS handling
  • Add device /dev/console for udev
  • ide-generic should now really be excluded
  • Fix a bug in major number for tty
  • If udev then adds modprobe/insmod to rootfs
  • tty0 is also cretaed with udev
  • ide-generic put rather in DENY_MODS
  • udevd remove from deplist s handled in mindi directly
  • better default for mindi when using --usb
  • Handles dynamically linked busybox (in case we want to use it soon ;-)
  • Adds fixed devices to create for udev
  • ide-generic should not be part of the initrd when using libata v2
  • support a dynamically linked udev (case on Ubuntu 7.10 and Mandriva 2008.0 so should be quite generic) This will give incitation to move to dyn. linked binaries in the initrd which will help for other tasks (ia6 4)
  • Improvement in udev support (do not use cl options not available in busybox)
  • Udev in mindi
    • auto creation of the right links at boot time with udev-links.conf(from Mandriva 2008.0)
    • rework startup of udev as current makes kernel crash (from Mandriva 2008.0)
    • add support for 64 bits udev
  • Try to render MyInsmod silent at boot time
  • Adds udev support (mandatory for newest distributions to avoid remapping of devices in a different way as on the original system)
  • We also need vaft format support for USB boot
  • Adds libusual support (Ubuntu 7.10 needs it for USB)
  • Improve Ubuntu/Debian keyboard detection and support
  • pbinit adapted to new pb (0.8.10). Filtering of docs done in it
  • Suppress some mondo warnings and errors on USB again
  • Tries to fix lack of files in deb mindi package
  • Verify should now work for USB devices
  • More log/mesages improvement for USB support
  • - Supress g_erase_tmpdir_and_scratchdir
  • Improve some log messages for USB support
  • Try to improve install in mindi to avoid issues with isolinux.cfg not installed vene if in the pkg :-(
  • Improve mindi-busybox build
  • In conformity with pb 0.8.9
  • Add support for Ubuntu 7.10 in build process
  • Add USB Key button to Menu UI (CD streamer removed)
  • Attempt to fix error messages on tmp/scratch files at the end by removing those dir at the latest possible.
  • Fix a bug linked to the size of the -E param which could be used (Arnaud Tiger/René Ribaud).
  • Integrate ~/.pbrc content into mondorescue.pb (required project-builder >= 0.8.7)
  • Put mondorescue in conformity with new pb filtering rules
  • Add USB support at restore time (no test done yet). New start-usb script PB varibale added where useful
  • Unmounting USB device before removal of temporary scratchdir
  • Stil refining USB copy back to mondo (one command was not executed)
  • No need to have the image subdor in the csratchdir when USB.
  • umount the USB partition before attempting to use it
  • Remove useless copy from mindi to mondo at end of USB handling

(risky merge, we are raising the limits of 2 diverging branches. The status of stable is not completely sure as such. Will need lots of tests, but it's not yet done :-()
(merge -r1692:1769 $SVN_M/branches/2.2.5)

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