Mercurial > hg > toybox
annotate www/code.html @ 625:1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
| author | Rob Landley <rob@landley.net> |
|---|---|
| date | Sun, 15 Jul 2012 17:47:08 -0500 |
| parents | 2c1cb0d35031 |
| children | 7e846e281e38 |
| rev | line source |
|---|---|
| 200 | 1 <!--#include file="header.html" --> |
| 2 | |
| 529 | 3 <p><h1>Code style</h1></p> |
|
505
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
4 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
5 <p>The primary goal of toybox is _simple_ code. Keeping the code small is |
| 529 | 6 second, with speed and lots of features coming in somewhere after that. |
| 7 (For more on that, see the <a href=design.html>design</a> page.)</p> | |
|
505
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
8 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
9 <p>A simple implementation usually takes up fewer lines of source code, |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
10 meaning more code can fit on the screen at once, meaning the programmer can |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
11 see more of it on the screen and thus keep more if in their head at once. |
| 529 | 12 This helps code auditing and thus reduces bugs. That said, sometimes being |
| 13 more explicit is preferable to being clever enough to outsmart yourself: | |
| 14 don't be so terse your code is unreadable.</p> | |
| 217 | 15 |
| 16 <p>Toybox source is formatted to be read with 4-space tab stops. Each file | |
| 17 starts with a special comment telling vi to set the tab stop to 4. Note that | |
| 18 one of the bugs in Ubuntu 7.10 broke vi's ability to parse these comments; you | |
| 19 must either rebuild vim from source, or go ":ts=4" yourself each time you load | |
| 20 the file.</p> | |
| 21 | |
| 22 <p>Gotos are allowed for error handling, and for breaking out of | |
| 23 nested loops. In general, a goto should only jump forward (not back), and | |
| 24 should either jump to the end of an outer loop, or to error handling code | |
| 25 at the end of the function. Goto labels are never indented: they override the | |
| 26 block structure of the file. Putting them at the left edge makes them easy | |
| 27 to spot as overrides to the normal flow of control, which they are.</p> | |
| 28 | |
|
505
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
29 <p><h1>Building Toybox:</h1></p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
30 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
31 <p>Toybox is configured using the Kconfig language pioneered by the Linux |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
32 kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc). |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
33 This generates a ".config" file containing the selected options, which |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
34 controls which features to enable when building toybox.</p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
35 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
36 <p>Each configuration option has a default value. The defaults indicate the |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
37 "maximum sane configuration", I.E. if the feature defaults to "n" then it |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
38 either isn't complete or is a special-purpose option (such as debugging |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
39 code) that isn't intended for general purpose use.</p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
40 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
41 <p>The standard build invocation is:</p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
42 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
43 <ul> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
44 <li>make defconfig #(or menuconfig)</li> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
45 <li>make</li> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
46 <li>make install</li> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
47 </ul> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
48 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
49 <p>Type "make help" to see all available build options.</p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
50 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
51 <p>The file "configure" contains a number of environment variable definitions |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
52 which influence the build, such as specifying which compiler to use or where |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
53 to install the resulting binaries. This file is included by the build, but |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
54 accepts existing definitions of the environment variables, so it may be sourced |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
55 or modified by the developer before building and the definitions exported |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
56 to the environment will take precedence.</p> |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
57 |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
58 <p>(To clarify: "configure" describes the build and installation environment, |
|
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
59 ".config" lists the features selected by defconfig/menuconfig.)</p> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
60 |
| 200 | 61 <p><h1>Infrastructure:</h1></p> |
| 62 | |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
63 <p>The toybox source code is in following directories:</p> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
64 <ul> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
65 <li>The <a href="#top">top level directory</a> contains the file main.c (were |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
66 execution starts), the header file toys.h (included by every command), and |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
67 other global infrastructure.</li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
68 <li>The <a href="#lib">lib directory</a> contains common functions shared by |
|
625
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
69 multiple commands:</li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
70 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
71 <li><a href="#lib_lib">lib/lib.c</a></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
72 <li><a href="#lib_llist">lib/llist.c</a></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
73 <li><a href="#lib_args">lib/args.c</a></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
74 <li><a href="#lib_dirtree">lib/dirtree.c</a></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
75 </ul> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
76 <li>The <a href="#toys">toys directory</a> contains the C files implementating |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
77 each command.</li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
78 <li>The <a href="#scripts">scripts directory</a> contains the build and |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
79 test infrastructure.</li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
80 <li>The <a href="#kconfig">kconfig directory</a> contains the configuration |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
81 infrastructure implementing menuconfig (copied from the Linux kernel).</li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
82 <li>The <a href="#generated">generated directory</a> contains intermediate |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
83 files generated from other parts of the source code.</li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
84 </ul> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
85 |
|
501
8abb9e307d0c
Web page tweaks. Remove background image (makes it hard ot read for some people), and use local roadmap instead of third party wiki.
Rob Landley <rob@landley.net>
parents:
432
diff
changeset
|
86 <a name="adding" /> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
87 <p><h1>Adding a new command</h1></p> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
88 <p>To add a new command to toybox, add a C file implementing that command to |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
89 the toys directory. No other files need to be modified; the build extracts |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
90 all the information it needs (such as command line arguments) from specially |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
91 formatted comments and macros in the C file. (See the description of the |
|
505
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
92 <a href="#generated">"generated" directory</a> for details.)</p> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
93 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
94 <p>An easy way to start a new command is copy the file "hello.c" to |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
95 the name of the new command, and modify this copy to implement the new command. |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
96 This file is an example command meant to be used as a "skeleton" for |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
97 new commands (more or less by turning every instance of "hello" into the |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
98 name of your command, updating the command line arguments, globals, and |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
99 help data, and then filling out its "main" function with code that does |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
100 something interesting). It provides examples of all the build infrastructure |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
101 (including optional elements like command line argument parsing and global |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
102 variables that a "hello world" program doesn't strictly need).</p> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
103 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
104 <p>Here's a checklist of steps to turn hello.c into another command:</p> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
105 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
106 <ul> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
107 <li><p>First "cd toys" and "cp hello.c yourcommand.c". Note that the name |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
108 of this file is significant, it's the name of the new command you're adding |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
109 to toybox. Open your new file in your favorite editor.</p></li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
110 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
111 <li><p>Change the one line comment at the top of the file (currently |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
112 "hello.c - A hello world program") to describe your new file.</p></li> |
| 200 | 113 |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
114 <li><p>Change the copyright notice to your name, email, and the current |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
115 year.</p></li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
116 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
117 <li><p>Give a URL to the relevant standards document, or say "Not in SUSv4" if |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
118 there is no relevant standard. (Currently both lines are there, delete |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
119 whichever is inappropriate.) The existing link goes to the directory of SUSv4 |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
120 command line utility standards on the Open Group's website, where there's often |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
121 a relevant commandname.html file. Feel free to link to other documentation or |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
122 standards as appropriate.</p></li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
123 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
124 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
125 The NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
126 structure. The arguments to the NEWTOY macro are:</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
127 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
128 <ol> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
129 <li><p>the name used to run your command</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
130 <li><p>the command line argument <a href="#lib_args">option parsing string</a> (NULL if none)</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
131 <li><p>a bitfield of TOYFLAG values |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
132 (defined in toys.h) providing additional information such as where your |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
133 command should be installed on a running system, whether to blank umask |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
134 before running, whether or not the command must run as root (and thus should |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
135 retain root access if installed SUID), and so on.</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
136 </ol> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
137 </li> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
138 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
139 <li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
140 comment block) to supply your command's configuration and help |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
141 information. The uppper case config symbols are used by menuconfig, and are |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
142 also what the CFG_ and USE_() macros are generated from (see [TODO]). The |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
143 help information here is used by menuconfig, and also by the "help" command to |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
144 describe your new command. (See [TODO] for details.) By convention, |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
145 unfinished commands default to "n" and finished commands default to "y", |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
146 so "make defconfig" selects all finished commands. (Note, "finished" means |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
147 "ready to be used", not that it'll never change again.)<p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
148 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
149 <p>Each help block should start with a "usage: yourcommand" line explaining |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
150 any command line arguments added by this config option. The "help" command |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
151 outputs this text, and scripts/config2help.c in the build infrastructure |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
152 collates these usage lines for commands with multiple configuration |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
153 options when producing generated/help.h.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
154 </li> |
| 200 | 155 |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
156 <li><p>Update the DEFINE_GLOBALS() macro to contain your command's global |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
157 variables, and also change the name "hello" in the #define TT line afterwards |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
158 to the name of your command. If your command has no global variables, delete |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
159 this macro (and the #define TT line afterwards). Note that if you specified |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
160 two-character command line arguments in NEWTOY(), the first few global |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
161 variables will be initialized by the automatic argument parsing logic, and |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
162 the type and order of these variables must correspond to the arguments |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
163 specified in NEWTOY(). See [TODO] for details.</p></li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
164 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
165 <li><p>If you didn't delete the DEFINE_GLOBALS macro, change the "#define TT |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
166 this.hello" line to use your command name in place of the "hello". This is a |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
167 shortcut to access your global variables as if they were members of the global |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
168 struct "TT". (Access these members with a period ".", not a right arrow |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
169 "->".)</p></li> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
170 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
171 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
172 where execution of your command starts. See [TODO] to figure out what |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
173 happened to your command line arguments and how to access them.</p></li> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
174 </ul> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
175 |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
176 <p><a name="top" /><h2>Top level directory.</h2></p> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
177 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
178 <p>This directory contains global infrastructure.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
179 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
180 <h3>toys.h</h3> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
181 <p>Each command #includes "toys.h" as part of its standard prolog.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
182 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
183 <p>This file sucks in most of the commonly used standard #includes, so |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
184 individual files can just #include "toys.h" and not have to worry about |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
185 stdargs.h and so on. Individual commands still need to #include |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
186 special-purpose headers that may not be present on all systems (and thus would |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
187 prevent toybox from building that command on such a system with that command |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
188 enabled). Examples include regex support, any "linux/" or "asm/" headers, mtab |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
189 support (mntent.h and sys/mount.h), and so on.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
190 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
191 <p>The toys.h header also defines structures for most of the global variables |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
192 provided to each command by toybox_main(). These are described in |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
193 detail in the description for main.c, where they are initialized.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
194 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
195 <p>The global variables are grouped into structures (and a union) for space |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
196 savings, to more easily track the amount of memory consumed by them, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
197 so that they may be automatically cleared/initialized as needed, and so |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
198 that access to global variables is more easily distinguished from access to |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
199 local variables.</p> |
| 200 | 200 |
| 201 <h3>main.c</h3> | |
| 202 <p>Contains the main() function where execution starts, plus | |
| 203 common infrastructure to initialize global variables and select which command | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
204 to run. The "toybox" multiplexer command also lives here. (This is the |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
205 only command defined outside of the toys directory.)</p> |
| 200 | 206 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
207 <p>Execution starts in main() which trims any path off of the first command |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
208 name and calls toybox_main(), which calls toy_exec(), which calls toy_find() |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
209 and toy_init() before calling the appropriate command's function from |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
210 toy_list[] (via toys.which->toy_main()). |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
211 If the command is "toybox", execution recurses into toybox_main(), otherwise |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
212 the call goes to the appropriate commandname_main() from a C file in the toys |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
213 directory.</p> |
| 200 | 214 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
215 <p>The following global variables are defined in main.c:</p> |
| 200 | 216 <ul> |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
217 <a name="toy_list" /> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
218 <li><p><b>struct toy_list toy_list[]</b> - array describing all the |
| 200 | 219 commands currently configured into toybox. The first entry (toy_list[0]) is |
| 220 for the "toybox" multiplexer command, which runs all the other built-in commands | |
| 221 without symlinks by using its first argument as the name of the command to | |
| 222 run and the rest as that command's argument list (ala "./toybox echo hello"). | |
| 223 The remaining entries are the commands in alphabetical order (for efficient | |
| 224 binary search).</p> | |
| 225 | |
| 226 <p>This is a read-only array initialized at compile time by | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
227 defining macros and #including generated/newtoys.h.</p> |
| 200 | 228 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
229 <p>Members of struct toy_list (defined in "toys.h") include:</p> |
| 200 | 230 <ul> |
| 231 <li><p>char *<b>name</b> - the name of this command.</p></li> | |
| 232 <li><p>void (*<b>toy_main</b>)(void) - function pointer to run this | |
| 233 command.</p></li> | |
| 234 <li><p>char *<b>options</b> - command line option string (used by | |
| 235 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
236 entries in the toy's DEFINE_GLOBALS struct). When this is NULL, no option |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
237 parsing is done before calling toy_main().</p></li> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
238 <li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
239 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
240 <ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
241 <li><b>TOYFLAG_USR</b> - Install this command under /usr</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
242 <li><b>TOYFLAG_BIN</b> - Install this command under /bin</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
243 <li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
244 <li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
245 <li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li> |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
246 <li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
247 <li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
248 </ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
249 <br> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
250 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
251 <p>These flags are combined with | (or). For example, to install a command |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
252 in /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
253 </ul> |
| 200 | 254 </li> |
| 255 | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
256 <li><p><b>struct toy_context toys</b> - global structure containing information |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
257 common to all commands, initializd by toy_init() and defined in "toys.h". |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
258 Members of this structure include:</p> |
| 200 | 259 <ul> |
| 260 <li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list | |
| 261 structure. Mostly used to grab the name of the running command | |
| 262 (toys->which.name).</p> | |
| 263 </li> | |
| 264 <li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The | |
| 265 error_exit() functions will return 1 if this is zero, otherwise they'll | |
| 266 return this value.</p></li> | |
| 267 <li><p>char **<b>argv</b> - "raw" command line options, I.E. the original | |
| 268 unmodified string array passed in to main(). Note that modifying this changes | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
269 "ps" output, and is not recommended. This array is null terminated; a NULL |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
270 entry indicates the end of the array.</p> |
| 200 | 271 <p>Most commands don't use this field, instead the use optargs, optflags, |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
272 and the fields in the DEFINE_GLOBALS struct initialized by get_optflags().</p> |
| 200 | 273 </li> |
| 274 <li><p>unsigned <b>optflags</b> - Command line option flags, set by | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
275 <a href="#lib_args">get_optflags()</a>. Indicates which of the command line options listed in |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
276 toys->which.options occurred this time.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
277 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
278 <p>The rightmost command line argument listed in toys->which.options sets bit |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
279 1, the next one sets bit 2, and so on. This means the bits are set in the same |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
280 order the binary digits would be listed if typed out as a string. For example, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
281 the option string "abcd" would parse the command line "-c" to set optflags to 2, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
282 "-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
283 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
284 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2, |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
285 b=4, a=8. The punctuation after a letter initializes global variables |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
286 (see [TODO] DECLARE_GLOBALS() for details).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
287 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
288 <p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
289 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
290 </li> |
| 200 | 291 <li><p>char **<b>optargs</b> - Null terminated array of arguments left over |
| 292 after get_optflags() removed all the ones it understood. Note: optarg[0] is | |
| 293 the first argument, not the command name. Use toys.which->name for the command | |
| 294 name.</p></li> | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
295 <li><p>int <b>optc</b> - Optarg count, equivalent to argc but for |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
296 optargs[].<p></li> |
| 200 | 297 <li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message |
| 298 via help_main() before exiting. (True during option parsing, defaults to | |
| 299 false afterwards.)</p></li> | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
300 </ul> |
| 200 | 301 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
302 <li><p><b>union toy_union this</b> - Union of structures containing each |
| 200 | 303 command's global variables.</p> |
| 304 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
305 <p>Global variables are useful: they reduce the overhead of passing extra |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
306 command line arguments between functions, they conveniently start prezeroed to |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
307 save initialization costs, and the command line argument parsing infrastructure |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
308 can also initialize global variables with its results.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
309 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
310 <p>But since each toybox process can only run one command at a time, allocating |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
311 space for global variables belonging to other commands you aren't currently |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
312 running would be wasteful.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
313 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
314 <p>Toybox handles this by encapsulating each command's global variables in |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
315 a structure, and declaring a union of those structures with a single global |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
316 instance (called "this"). The DEFINE_GLOBALS() macro contains the global |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
317 variables that should go in the current command's global structure. Each |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
318 variable can then be accessed as "this.commandname.varname". |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
319 Generally, the macro TT is #defined to this.commandname so the variable |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
320 can then be accessed as "TT.variable". See toys/hello.c for an example.</p> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
321 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
322 <p>A command that needs global variables should declare a structure to |
| 200 | 323 contain them all, and add that structure to this union. A command should never |
| 324 declare global variables outside of this, because such global variables would | |
| 325 allocate memory when running other commands that don't use those global | |
| 326 variables.</p> | |
| 327 | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
328 <p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>, |
| 200 | 329 as specified by the options field off this command's toy_list entry. See |
| 330 the get_optargs() description in lib/args.c for details.</p> | |
| 331 </li> | |
| 332 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
333 <li><b>char toybuf[4096]</b> - a common scratch space buffer so |
| 200 | 334 commands don't need to allocate their own. Any command is free to use this, |
| 335 and it should never be directly referenced by functions in lib/ (although | |
| 336 commands are free to pass toybuf in to a library function as an argument).</li> | |
| 337 </ul> | |
| 338 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
339 <p>The following functions are defined in main.c:</p> |
| 200 | 340 <ul> |
| 341 <li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list | |
| 342 structure for this command name, or NULL if not found.</p></li> | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
343 <li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out |
|
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
344 the global toys structure, calling get_optargs() if necessary.</p></li> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
345 <li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
346 arguments.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
347 <p>Calls toy_find() on argv[0] (which must be just a command name |
| 200 | 348 without path). Returns if it can't find this command, otherwise calls |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
349 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p> |
| 200 | 350 |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
351 <p>Use the library function xexec() to fall back to external executables |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
352 in $PATH if toy_exec() can't find a built-in command. Note that toy_exec() |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
353 does not strip paths before searching for a command, so "./command" will |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
354 never match an internal command.</li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
355 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
356 <li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
357 command (I.E. "toybox"). Given a command name as its first argument, calls |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
358 toy_exec() on its arguments. With no arguments, it lists available commands. |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
359 If the first argument starts with "-" it lists each command with its default |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
360 install path prepended.</p></li> |
| 200 | 361 |
| 362 </ul> | |
| 363 | |
| 364 <h3>Config.in</h3> | |
| 365 | |
| 366 <p>Top level configuration file in a stylized variant of | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
367 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p> |
| 200 | 368 |
| 369 <p>These files are directly used by "make menuconfig" to select which commands | |
| 370 to build into toybox (thus generating a .config file), and by | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
371 scripts/config2help.py to create generated/help.h.</p> |
| 200 | 372 |
| 373 <h3>Temporary files:</h3> | |
| 374 | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
375 <p>There is one temporary file in the top level source directory:</p> |
| 200 | 376 <ul> |
| 377 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating | |
| 378 which commands (and options to commands) are currently enabled. Used | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
379 to make generated/config.h and determine which toys/*.c files to build.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
380 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
381 <p>You can create a human readable "miniconfig" version of this file using |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
382 <a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
383 instructions</a>.</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
384 </li> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
385 </ul> |
| 200 | 386 |
|
505
c08cd17224c0
Make documentation even fluffier.
Rob Landley <rob@landley.net>
parents:
501
diff
changeset
|
387 <a name="generated" /> |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
388 <p>The "generated/" directory contains files generated from other source code |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
389 in toybox. All of these files can be recreated by the build system, although |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
390 some (such as generated/help.h) are shipped in release versions to reduce |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
391 environmental dependencies (I.E. so you don't need python on your build |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
392 system).</p> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
393 |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
394 <ul> |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
395 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros, |
| 200 | 396 generated from .config by a sed invocation in the top level Makefile.</p> |
| 397 | |
| 398 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
399 disabled symbols. This allows the use of normal if() statements to remove |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
400 code at compile time via the optimizer's dead code elimination (which removes |
|
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
401 from the binary any code that cannot be reached). This saves space without |
| 200 | 402 cluttering the code with #ifdefs or leading to configuration dependent build |
| 403 breaks. (See the 1992 Usenix paper | |
|
415
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
404 <a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef |
| 200 | 405 Considered Harmful</a> for more information.)</p> |
| 406 | |
| 407 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol | |
| 408 is enabled, and nothing when the symbol is disabled. This can be used | |
| 409 for things like varargs or variable declarations which can't always be | |
|
256
20f1e3da0492
Partial update. Needs more work.
Rob Landley <rob@landley.net>
parents:
239
diff
changeset
|
410 eliminated by a simple test on CFG_SYMBOL. Note that |
| 200 | 411 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can |
| 412 still result in configuration dependent build breaks. Use with caution.</p> | |
| 413 </li> | |
| 414 </ul> | |
| 415 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
416 <p><h2>Directory toys/</h2></p> |
| 200 | 417 |
| 418 <h3>toys/Config.in</h3> | |
| 419 | |
| 420 <p>Included from the top level Config.in, contains one or more | |
| 421 configuration entries for each command.</p> | |
| 422 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
423 <p>Each command has a configuration entry matching the command name (although |
|
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
424 configuration symbols are uppercase and command names are lower case). |
| 200 | 425 Options to commands start with the command name followed by an underscore and |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
426 the option name. Global options are attached to the "toybox" command, |
| 200 | 427 and thus use the prefix "TOYBOX_". This organization is used by |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
428 scripts/cfg2files to select which toys/*.c files to compile for a given |
|
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
429 .config.</p> |
| 200 | 430 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
431 <p>A command with multiple names (or multiple similar commands implemented in |
| 200 | 432 the same .c file) should have config symbols prefixed with the name of their |
| 433 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names | |
| 434 have config symbols they're options (symbols with an underscore and suffix) | |
| 435 to the NEWTOY() name. (See toys/toylist.h)</p> | |
| 436 | |
| 437 <h3>toys/toylist.h</h3> | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
438 <p>The first half of this file prototypes all the structures to hold |
|
213
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
439 global variables for each command, and puts them in toy_union. These |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
440 prototypes are only included if the macro NEWTOY isn't defined (in which |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
441 case NEWTOY is defined to a default value that produces function |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
442 prototypes).</p> |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
443 |
|
213
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
444 <p>The second half of this file lists all the commands in alphabetical |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
445 order, along with their command line arguments and install location. |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
446 Each command has an appropriate configuration guard so only the commands that |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
447 are enabled wind up in the list.</p> |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
448 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
449 <p>The first time this header is #included, it defines structures and |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
450 produces function prototypes for the commands in the toys directory.</p> |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
451 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
452 |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
453 <p>The first time it's included, it defines structures and produces function |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
454 prototypes. |
|
db91356e3c43
More random unfinished code documentation.
Rob Landley <rob@landley.net>
parents:
210
diff
changeset
|
455 This |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
456 is used to initialize toy_list in main.c, and later in that file to initialize |
|
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
457 NEED_OPTIONS (to figure out whether the command like parsing logic is needed), |
|
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
458 and to put the help entries in the right order in toys/help.c.</p> |
| 200 | 459 |
| 460 <h3>toys/help.h</h3> | |
| 461 | |
| 462 <p>#defines two help text strings for each command: a single line | |
| 463 command_help and an additinal command_help_long. This is used by help_main() | |
| 464 in toys/help.c to display help for commands.</p> | |
| 465 | |
| 466 <p>Although this file is generated from Config.in help entries by | |
| 467 scripts/config2help.py, it's shipped in release tarballs so you don't need | |
| 468 python on the build system. (If you check code out of source control, or | |
| 469 modify Config.in, then you'll need python installed to rebuild it.)</p> | |
| 470 | |
| 471 <p>This file contains help for all commands, regardless of current | |
| 472 configuration, but only the currently enabled ones are entered into help_data[] | |
| 473 in toys/help.c.</p> | |
| 474 | |
|
536
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
475 <a name="lib"> |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
476 <h2>Directory lib/</h2> |
| 200 | 477 |
|
536
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
478 <p>TODO: document lots more here.</p> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
479 |
|
625
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
480 <p>lib: getmountlist(), error_msg/error_exit, xmalloc(), |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
481 strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(), |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
482 itoa().</p> |
|
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
483 |
|
536
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
484 <h3>lib/portability.h</h3> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
485 |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
486 <p>This file is automatically included from the top of toys.h, and smooths |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
487 over differences between platforms (hardware targets, compilers, C libraries, |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
488 operating systems, etc).</p> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
489 |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
490 <p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
491 |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
492 <p>A macro like SWAP_LE32(x) means "The value in x is stored as a little |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
493 endian 32 bit value, so perform the translation to/from whatever the native |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
494 32-bit format is". You do the swap once on the way in, and once on the way |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
495 out. If your target is already little endian, the macro is a NOP.</p> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
496 |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
497 <p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions. |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
498 In each case, the name of the macro refers to the _external_ representation, |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
499 and converts to/from whatever your native representation happens to be (which |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
500 can vary depending on what you're currently compiling for).</p> |
|
2c1cb0d35031
Add lib/portability.h description with explanation of SWAP() macros.
Rob Landley <rob@landley.net>
parents:
529
diff
changeset
|
501 |
|
625
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
502 <a name="lib_llist"><h3>lib/llist.c</h3> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
503 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
504 <p>Some generic single and doubly linked list functions, which take |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
505 advantage of a couple properties of C:</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
506 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
507 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
508 <li><p>Structure elements are laid out in memory in the order listed, and |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
509 the first element has no padding. This means you can always treat (typecast) |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
510 a pointer to a structure as a pointer to the first element of the structure, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
511 even if you don't know anything about the data following it.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
512 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
513 <li><p>An array of length zero at the end of a structure adds no space |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
514 to the sizeof() the structure, but if you calculate how much extra space |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
515 you want when you malloc() the structure it will be available at the end. |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
516 Since C has no bounds checking, this means each struct can have one variable |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
517 length array.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
518 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
519 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
520 <p>Toybox's list structures always have their <b>next</b> pointer as |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
521 the first entry of each struct, and singly linked lists end with a NULL pointer. |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
522 This allows generic code to traverse such lists without knowing anything |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
523 else about the specific structs composing them: if your pointer isn't NULL |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
524 typecast it to void ** and dereference once to get the next entry.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
525 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
526 <p><b>lib/lib.h</b> defines three structure types:</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
527 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
528 <li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>), |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
529 memory for which is allocated as part of the node. (I.E. llist_traverse(list, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
530 free); can clean up after this type of list.)</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
531 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
532 <li><p><b>struct arg_list</b> - stores a pointer to a single string |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
533 (<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
534 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
535 <li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
536 *prev</b> along with a <b>char *data</b> for payload.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
537 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
538 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
539 <b>List Functions</b> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
540 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
541 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
542 <li><p>void *<b>llist_pop</b>(void **list) - advances through a list ala |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
543 <b>node = llist_pop(&list);</b> This doesn't modify the list contents, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
544 but does advance the pointer you feed it (which is why you pass the _address_ |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
545 of that pointer, not the pointer itself).</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
546 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
547 <li><p>void <b>llist_traverse</b>(void *list, void (*using)(void *data)) - |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
548 iterate through a list calling a function on each node.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
549 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
550 <li><p>struct double_list *<b>dlist_add</b>(struct double_list **llist, char *data) |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
551 - append an entry to a circular linked list. |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
552 This function allocates a new struct double_list wrapper and returns the |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
553 pointer to the new entry (which you can usually ignore since it's llist->prev, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
554 but if llist was NULL you need it). The argument is the ->data field for the |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
555 new node.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
556 <ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
557 struct double_list *new) - append existing struct double_list to |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
558 list, does not allocate anything.</p></li></ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
559 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
560 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
561 <b>Trivia questions:</b> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
562 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
563 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
564 <li><p><b>Why do arg_list and double_list contain a char * payload instead of |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
565 a void *?</b> - Because you always have to typecast a void * to use it, and |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
566 typecasting a char * does no harm. Thus having it default to the most common |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
567 pointer type saves a few typecasts (strings are the most common payload), |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
568 and doesn't hurt anything otherwise.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
569 </li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
570 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
571 <li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
572 you to keep track of which one you're using, calling free(node->str) would |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
573 be bad, and _failing_ to free(node->arg) leaks memory.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
574 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
575 <li><p><b>Why does llist_pop() take a void * instead of void **?</b> - |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
576 because the stupid compiler complains about "type punned pointers" when |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
577 you typecast and dereference ont he same line, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
578 due to insane FSF developers hardwiring limitations of their optimizer |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
579 into gcc's warning system. Since C automatically typecasts any other |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
580 pointer _down_ to a void *, the current code works fine. It's sad that it |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
581 won't warn you if you forget the &, but the code crashes pretty quickly in |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
582 that case.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
583 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
584 <li><p><b>How do I assemble a singly-linked-list in order?</b> - use |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
585 a double_list, dlist_add() your entries, and then break the circle with |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
586 <b>list->prev->next = NULL;</b> when done.</li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
587 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
588 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
589 <a name="lib_args"><h3>lib/args.c</h3> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
590 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
591 <p>Toybox's main.c automatically parses command line options before calling the |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
592 command's main function. Option parsing starts in get_optflags(), which stores |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
593 results in the global structures "toys" (optflags and optargs) and "this".</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
594 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
595 <p>The option parsing infrastructure stores a bitfield in toys.optflags to |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
596 indicate which options the current command line contained. Arguments |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
597 attached to those options are saved into the command's global structure |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
598 ("this"). Any remaining command line arguments are collected together into |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
599 the null-terminated array toys.optargs, with the length in toys.optc. (Note |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
600 that toys.optargs does not contain the current command name at position zero, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
601 use "toys.which->name" for that.) The raw command line arguments get_optflags() |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
602 parsed are retained unmodified in toys.argv[].</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
603 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
604 <p>Toybox's option parsing logic is controlled by an "optflags" string, using |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
605 a format reminiscent of getopt's optargs but has several important differences. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
606 Toybox does not use the getopt() |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
607 function out of the C library, get_optflags() is an independent implementation |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
608 which doesn't permute the original arguments (and thus doesn't change how the |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
609 command is displayed in ps and top), and has many features not present in |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
610 libc optargs() (such as the ability to describe long options in the same string |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
611 as normal options).</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
612 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
613 <p>Each command's NEWTOY() macro has an optflags string as its middle argument, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
614 which sets toy_list.options for that command to tell get_optflags() what |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
615 command line arguments to look for, and what to do with them. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
616 If a command has no option |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
617 definition string (I.E. the argument is NULL), option parsing is skipped |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
618 for that command, which must look at the raw data in toys.argv to parse its |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
619 own arguments. (If no currently enabled command uses option parsing, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
620 get_optflags() is optimized out of the resulting binary by the compiler's |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
621 --gc-sections option.)</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
622 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
623 <p>You don't have to free the option strings, which point into the environment |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
624 space (I.E. the string data is not copied). A TOYFLAG_NOFORK command |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
625 that uses the linked list type "*" should free the list objects but not |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
626 the data they point to, via "llist_free(TT.mylist, NULL);". (If it's not |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
627 NOFORK, exit() will free all the malloced data anyway unless you want |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
628 to implement a CONFIG_TOYBOX_FREE cleanup for it.)</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
629 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
630 <h4>Optflags format string</h4> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
631 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
632 <p>Note: the optflags option description string format is much more |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
633 concisely described by a large comment at the top of lib/args.c.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
634 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
635 <p>The general theory is that letters set optflags, and punctuation describes |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
636 other actions the option parsing logic should take.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
637 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
638 <p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
639 is parsed using the optflags string "<b>a#b:c:d</b>". (I.E. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
640 toys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d", |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
641 "walrus", "-a", "42"]). When get_optflags() returns, the following data is |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
642 available to command_main(): |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
643 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
644 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
645 <li><p>In <b>struct toys</b>: |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
646 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
647 <li>toys.optflags = 13; // -a = 8 | -b = 4 | -d = 1</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
648 <li>toys.optargs[0] = "walrus"; // leftover argument</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
649 <li>toys.optargs[1] = NULL; // end of list</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
650 <li>toys.optc=1; // there was 1 leftover argument</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
651 <li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
652 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
653 <p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
654 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
655 <li><p>In <b>union this</b> (treated as <b>long this[]</b>): |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
656 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
657 <li>this[0] = NULL; // -c didn't get an argument this time, so get_optflags() didn't change it and toys_init() zeroed "this" during setup.)</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
658 <li>this[1] = (long)"fruit"; // argument to -b</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
659 <li>this[2] = 42; // argument to -a</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
660 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
661 </p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
662 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
663 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
664 <p>If the command's globals are:</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
665 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
666 <blockquote><pre> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
667 DECLARE_GLOBALS( |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
668 char *c; |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
669 char *b; |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
670 long a; |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
671 ) |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
672 #define TT this.command |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
673 </pre></blockquote> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
674 <p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
675 each entry that receives an argument must be a long or pointer, to line up |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
676 with the array position. Right to left in the optflags string corresponds to |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
677 top to bottom in DECLARE_GLOBALS().</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
678 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
679 <p><b>long toys.optflags</b></p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
680 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
681 <p>Each option in the optflags string corresponds to a bit position in |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
682 toys.optflags, with the same value as a corresponding binary digit. The |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
683 rightmost argument is (1<<0), the next to last is (1<<1) and so on. If |
|
432
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
684 the option isn't encountered while parsing argv[], its bit remains 0.</p> |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
685 |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
686 <p>For example, |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
687 the optflags string "abcd" would parse the command line argument "-c" to set |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
688 optflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
689 6 (I.E. 4|2), and "-a -c" would set optflags to 10 (2|8).</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
690 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
691 <p>Only letters are relevant to optflags, punctuation is skipped: in the |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
692 string "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
693 usually indicate that the option takes an argument.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
694 |
|
432
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
695 <p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
696 the amount a long would have on 32-bit platforms anyway; 64 bit code on |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
697 32 bit platforms is too expensive to require in common code used by almost |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
698 all commands.) Bit positions beyond the 1<<31 aren't recorded, but |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
699 parsing higher options can still set global variables.</p> |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
700 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
701 <p><b>Automatically setting global variables from arguments (union this)</b></p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
702 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
703 <p>The following punctuation characters may be appended to an optflags |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
704 argument letter, indicating the option takes an additional argument:</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
705 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
706 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
707 <li><b>:</b> - plus a string argument, keep most recent if more than one.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
708 <li><b>*</b> - plus a string argument, appended to a linked list.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
709 <li><b>@</b> - plus an occurrence counter (stored in a long)</li> |
|
415
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
710 <li><b>#</b> - plus a signed long argument. |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
711 <li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
712 <ul>The following can be appended to a float or double: |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
713 <li><b><123</b> - error if argument is less than this</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
714 <li><b>>123</b> - error if argument is greater than this</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
715 <li><b>=123</b> - default value if argument not supplied</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
716 </ul> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
717 <ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
718 is enabled. (Otherwise the code to determine where floating point constants |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
719 end drops out. When disabled, it can reserve a global data slot for the |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
720 argument so offsets won't change, but will never fill it out.). You can handle |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
721 this by using the USE_BLAH() macros with C string concatenation, ala: |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
722 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul> |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
723 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
724 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
725 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42"). |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
726 The command line argument "-abc" may be interepreted many different ways: |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
727 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
728 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
729 "c" as the argument to -b.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
730 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
731 <p>Options which have an argument fill in the corresponding slot in the global |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
732 union "this" (see generated/globals.h), treating it as an array of longs |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
733 with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
734 this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
735 the corresponding argument is not encountered.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
736 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
737 <p>This behavior is useful because the LP64 standard ensures long and pointer |
|
432
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
738 are the same size. C99 guarantees structure members will occur in memory |
|
01473712c9fe
Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same).
Rob Landley <rob@landley.net>
parents:
415
diff
changeset
|
739 in the same order they're declared, and that padding won't be inserted between |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
740 consecutive variables of register size. Thus the first few entries can |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
741 be longs or pointers corresponding to the saved arguments.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
742 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
743 <p><b>char *toys.optargs[]</b></p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
744 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
745 <p>Command line arguments in argv[] which are not consumed by option parsing |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
746 (I.E. not recognized either as -flags or arguments to -flags) will be copied |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
747 to toys.optargs[], with the length of that array in toys.optc. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
748 (When toys.optc is 0, no unrecognized command line arguments remain.) |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
749 The order of entries is preserved, and as with argv[] this new array is also |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
750 terminated by a NULL entry.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
751 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
752 <p>Option parsing can require a minimum or maximum number of optargs left |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
753 over, by adding "<1" (read "at least one") or ">9" ("at most nine") to the |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
754 start of the optflags string.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
755 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
756 <p>The special argument "--" terminates option parsing, storing all remaining |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
757 arguments in optargs. The "--" itself is consumed.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
758 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
759 <p><b>Other optflags control characters</b></p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
760 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
761 <p>The following characters may occur at the start of each command's |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
762 optflags string, before any options that would set a bit in toys.optflags:</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
763 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
764 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
765 <li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
766 <li><b>?</b> - allow unknown arguments (pass non-option arguments starting |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
767 with - through to optargs instead of erroring out).</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
768 <li><b>&</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
769 <li><b><</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
770 <li><b>></b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
771 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
772 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
773 <p>The following characters may be appended to an option character, but do |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
774 not by themselves indicate an extra argument should be saved in this[]. |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
775 (Technically any character not recognized as a control character sets an |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
776 optflag, but letters are never control characters.)</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
777 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
778 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
779 <li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
780 <li><b>|</b> - this option is required. If more than one marked, only one is required.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
781 <li><b>+X</b> enabling this option also enables option X (switch bit on).</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
782 <li><b>~X</b> enabling this option disables option X (switch bit off).</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
783 <li><b>!X</b> this option cannot be used in combination with X (die with error).</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
784 <li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
785 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
786 |
|
415
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
787 <p>The following may be appended to a float or double:</p> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
788 |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
789 <ul> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
790 <li><b><123</b> - error if argument is less than this</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
791 <li><b>>123</b> - error if argument is greater than this</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
792 <li><b>=123</b> - default value if argument not supplied</li> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
793 </ul> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
794 |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
795 <p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
796 is enabled. (Otherwise the code to determine where floating point constants |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
797 end drops out. When disabled, it can reserve a global data slot for the |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
798 argument so offsets won't change, but will never fill it out.). You can handle |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
799 this by using the USE_BLAH() macros with C string concatenation, ala:</p> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
800 |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
801 <blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote> |
|
2cbbd4c5eaaa
Add <>= to lib/args.c, with documentation.
Rob Landley <rob@landley.net>
parents:
403
diff
changeset
|
802 |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
803 <p><b>--longopts</b></p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
804 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
805 <p>The optflags string can contain long options, which are enclosed in |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
806 parentheses. They may be appended to an existing option character, in |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
807 which case the --longopt is a synonym for that option, ala "a:(--fred)" |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
808 which understands "-a blah" or "--fred blah" as synonyms.</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
809 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
810 <p>Longopts may also appear before any other options in the optflags string, |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
811 in which case they have no corresponding short argument, but instead set |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
812 their own bit based on position. So for "(walrus)#(blah)xy:z" "command |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
813 --walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8) |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
814 and would assign this[1] = 42;</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
815 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
816 <p>A short option may have multiple longopt synonyms, "a(one)(two)", but |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
817 each "bare longopt" (ala "(one)(two)abc" before any option characters) |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
818 always sets its own bit (although you can group them with +X).</p> |
|
239
4f1ca01db000
Fluff out hello.c to supply more example code as a skeleton for new commands,
Rob Landley <rob@landley.net>
parents:
217
diff
changeset
|
819 |
|
625
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
820 <a name="lib_dirtree"><h3>lib/dirtree.c</h3> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
821 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
822 <p>The directory tree traversal code should be sufficiently generic |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
823 that commands never need to use readdir(), scandir(), or the fts.h family |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
824 of functions.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
825 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
826 <p>These functions do not call chdir() or rely on PATH_MAX. Instead they |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
827 use openat() and friends, using one filehandle per directory level to |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
828 recurseinto subdirectories. (I.E. they can descend 1000 directories deep |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
829 if setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
830 in /proc/self/limits is generally 1024.)</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
831 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
832 <p>The basic dirtree functions are:</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
833 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
834 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
835 <li><p><b>dirtree_read(char *path, int (*callback)(struct dirtree node))</b> - |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
836 recursively read directories, either applying callback() or returning |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
837 a tree of struct dirtree if callback is NULL.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
838 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
839 <li><p><b>dirtree_path(struct dirtree *node, int *plen)</b> - malloc() a |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
840 string containing the path from the root of this tree to this node. If |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
841 plen isn't NULL then *plen is how many extra bytes to malloc at the end |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
842 of string.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
843 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
844 <li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
845 containing directory, for use with openat() and such.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
846 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
847 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
848 <p>The <b>dirtree_read()</b> function takes two arguments, a starting path for |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
849 the root of the tree, and a callback function. The callback takes a |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
850 <b>struct dirtree *</b> (from lib/lib.h) as its argument. If the callback is |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
851 NULL, the traversal uses a default callback (dirtree_notdotdot()) which |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
852 recursively assembles a tree of struct dirtree nodes for all files under |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
853 this directory and subdirectories (filtering out "." and ".." entries), |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
854 after which dirtree_read() returns the pointer to the root node of this |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
855 snapshot tree.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
856 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
857 <p>Otherwise the callback() is called on each entry in the directory, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
858 with struct dirtree * as its argument. This includes the initial |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
859 node created by dirtree_read() at the top of the tree.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
860 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
861 <p><b>struct dirtree</b></p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
862 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
863 <p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
864 st</b> entries describing a file, plus a <b>char *symlink</b> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
865 which is NULL for non-symlinks.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
866 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
867 <p>During a callback function, the <b>int data</b> field of directory nodes |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
868 contains a dirfd (for use with the openat() family of functions). This is |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
869 generally used by calling dirtree_parentfd() on the callback's node argument. |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
870 For symlinks, data contains the length of the symlink string. On the second |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
871 callback from DIRTREE_COMEAGAIN (depth-first traversal) data = -1 for |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
872 all nodes (that's how you can tell it's the second callback).</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
873 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
874 <p>Users of this code may put anything they like into the <b>long extra</b> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
875 field. For example, "cp" and "mv" use this to store a dirfd for the destination |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
876 directory (and use DIRTREE_COMEAGAIN to get the second callback so they can |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
877 close(node->extra) to avoid running out of filehandles). |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
878 This field is not directly used by the dirtree code, and |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
879 thanks to LP64 it's large enough to store a typecast pointer to an |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
880 arbitrary struct.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
881 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
882 <p>The return value of the callback combines flags (with boolean or) to tell |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
883 the traversal infrastructure how to behave:</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
884 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
885 <ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
886 <li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
887 this the struct dirtree is freed after the callback returns. Filtering out |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
888 siblings is fine, but discarding a parent while keeping its child leaks |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
889 memory.)</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
890 <li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
891 directory. (Does not propagate up tree: to abort entire traversal, |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
892 return DIRTREE_ABORT from parent callbacks too.)</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
893 <li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
894 non-directory entries. The remaining flags only take effect when |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
895 recursing into the children of a directory.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
896 <li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback a second time after |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
897 examining all directory contents, allowing depth-first traversal. |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
898 On the second call, dirtree->data = -1.</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
899 <li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
900 <b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
901 dirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
902 directories as directories. (Avoiding infinite recursion is the callback's |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
903 problem: the non-NULL dirtree->symlink can still distinguish between |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
904 them.)</p></li> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
905 </ul> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
906 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
907 <p>Each struct dirtree contains three pointers (next, parent, and child) |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
908 to other struct dirtree.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
909 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
910 <p>The <b>parent</b> pointer indicates the directory |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
911 containing this entry; even when not assembling a persistent tree of |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
912 nodes the parent entries remain live up to the root of the tree while |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
913 child nodes are active. At the top of the tree the parent pointer is |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
914 NULL, meaning the node's name[] is either an absolute path or relative |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
915 to cwd. The function dirtree_parentfd() gets the directory file descriptor |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
916 for use with openat() and friends, returning AT_FDCWD at the top of tree.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
917 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
918 <p>The <b>child</b> pointer points to the first node of the list of contents of |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
919 this directory. If the directory contains no files, or the entry isn't |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
920 a directory, child is NULL.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
921 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
922 <p>The <b>next</b> pointer indicates sibling nodes in the same directory as this |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
923 node, and since it's the first entry in the struct the llist.c traversal |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
924 mechanisms work to iterate over sibling nodes. Each dirtree node is a |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
925 single malloc() (even char *symlink points to memory at the end of the node), |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
926 so llist_free() works but its callback must descend into child nodes (freeing |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
927 a tree, not just a linked list), plus whatever the user stored in extra.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
928 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
929 <p>The <b>dirtree_read</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>() |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
930 to create a root node relative to the current directory, then calling |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
931 <b>handle_callback</b>() on that node (which recurses as instructed by the callback |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
932 return flags). Some commands (such as chgrp) bypass this wrapper, for example |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
933 to control whether or not to follow symlinks to the root node; symlinks |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
934 listed on the command line are often treated differently than symlinks |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
935 encountered during recursive directory traversal). |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
936 |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
937 <p>The ls command not only bypasses the wrapper, but never returns |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
938 <b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
939 from elsewhere in the program. This gives ls -lR manual control |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
940 of traversal order, which is neither depth first nor breadth first but |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
941 instead a sort of FIFO order requried by the ls standard.</p> |
|
1a368546afd9
Add documentation for lib/llist.c and lib/dirtree.c.
Rob Landley <rob@landley.net>
parents:
536
diff
changeset
|
942 |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
943 <h2>Directory scripts/</h2> |
| 200 | 944 |
| 945 <h3>scripts/cfg2files.sh</h3> | |
| 946 | |
| 947 <p>Run .config through this filter to get a list of enabled commands, which | |
| 948 is turned into a list of files in toys via a sed invocation in the top level | |
| 949 Makefile. | |
| 950 </p> | |
| 951 | |
|
210
a71c502a028c
Fluff out code.html a bit more.
Rob Landley <rob@landley.net>
parents:
200
diff
changeset
|
952 <h2>Directory kconfig/</h2> |
| 200 | 953 |
| 954 <p>Menuconfig infrastructure copied from the Linux kernel. See the | |
| 955 Linux kernel's Documentation/kbuild/kconfig-language.txt</p> | |
| 956 | |
|
403
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
957 <a name="generated"> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
958 <h2>Directory generated/</h2> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
959 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
960 <p>All the files in this directory except the README are generated by the |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
961 build. (See scripts/make.sh)</p> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
962 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
963 <ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
964 <li><p><b>config.h</b> - CFG_COMMAND and USE_COMMAND() macros set by menuconfig via .config.</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
965 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
966 <li><p><b>Config.in</b> - Kconfig entries for each command. Included by top level Config.in. The help text in here is used to generated help.h</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
967 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
968 <li><p><b>help.h</b> - Help text strings for use by "help" command. Building |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
969 this file requires python on the host system, so the prebuilt file is shipped |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
970 in the build tarball to avoid requiring python to build toybox.</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
971 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
972 <li><p><b>newtoys.h</b> - List of NEWTOY() or OLDTOY() macros for all available |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
973 commands. Associates command_main() functions with command names, provides |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
974 option string for command line parsing (<a href="#lib_args">see lib/args.c</a>), |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
975 specifies where to install each command and whether toysh should fork before |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
976 calling it.</p></li> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
977 </ul> |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
978 |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
979 <p>Everything in this directory is a derivative file produced from something |
|
f6ffc6685a9e
Fluff out documentation and skeleton code.
Rob Landley <rob@landley.net>
parents:
256
diff
changeset
|
980 else. The entire directory is deleted by "make distclean".</p> |
| 200 | 981 <!--#include file="footer.html" --> |