blob: 754835647c71aa89d79a622c27d2091f7ef3c163 [file] [log] [blame]
Rob Landley4e68de12007-12-13 07:00:27 -06001<!--#include file="header.html" -->
2
Rob Landleyed6ed622012-03-06 20:49:03 -06003<p><h1>Code style</h1></p>
Rob Landleye7c9a6d2012-02-28 06:34:09 -06004
5<p>The primary goal of toybox is _simple_ code. Keeping the code small is
Rob Landleyed6ed622012-03-06 20:49:03 -06006second, 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>
Rob Landleye7c9a6d2012-02-28 06:34:09 -06008
9<p>A simple implementation usually takes up fewer lines of source code,
10meaning more code can fit on the screen at once, meaning the programmer can
11see more of it on the screen and thus keep more if in their head at once.
Rob Landleyed6ed622012-03-06 20:49:03 -060012This helps code auditing and thus reduces bugs. That said, sometimes being
13more explicit is preferable to being clever enough to outsmart yourself:
14don't be so terse your code is unreadable.</p>
Rob Landley5a0660f2007-12-27 21:36:44 -060015
Rob Landley7aa651a2012-11-13 17:14:08 -060016<p>Toybox source uses two spaces per indentation level, and wraps at 80
17columns.</p>
Rob Landley5a0660f2007-12-27 21:36:44 -060018
19<p>Gotos are allowed for error handling, and for breaking out of
20nested loops. In general, a goto should only jump forward (not back), and
21should either jump to the end of an outer loop, or to error handling code
22at the end of the function. Goto labels are never indented: they override the
23block structure of the file. Putting them at the left edge makes them easy
24to spot as overrides to the normal flow of control, which they are.</p>
25
Rob Landleye7c9a6d2012-02-28 06:34:09 -060026<p><h1>Building Toybox:</h1></p>
27
28<p>Toybox is configured using the Kconfig language pioneered by the Linux
29kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc).
30This generates a ".config" file containing the selected options, which
Rob Landley7aa651a2012-11-13 17:14:08 -060031controls which features are included when compiling toybox.</p>
Rob Landleye7c9a6d2012-02-28 06:34:09 -060032
33<p>Each configuration option has a default value. The defaults indicate the
34"maximum sane configuration", I.E. if the feature defaults to "n" then it
35either isn't complete or is a special-purpose option (such as debugging
36code) that isn't intended for general purpose use.</p>
37
38<p>The standard build invocation is:</p>
39
40<ul>
41<li>make defconfig #(or menuconfig)</li>
42<li>make</li>
43<li>make install</li>
44</ul>
45
46<p>Type "make help" to see all available build options.</p>
47
48<p>The file "configure" contains a number of environment variable definitions
49which influence the build, such as specifying which compiler to use or where
50to install the resulting binaries. This file is included by the build, but
51accepts existing definitions of the environment variables, so it may be sourced
52or modified by the developer before building and the definitions exported
53to the environment will take precedence.</p>
54
55<p>(To clarify: "configure" describes the build and installation environment,
56".config" lists the features selected by defconfig/menuconfig.)</p>
Rob Landley6882ee82008-02-12 18:41:34 -060057
Rob Landley4e68de12007-12-13 07:00:27 -060058<p><h1>Infrastructure:</h1></p>
59
Rob Landley7c04f012008-01-20 19:00:16 -060060<p>The toybox source code is in following directories:</p>
61<ul>
62<li>The <a href="#top">top level directory</a> contains the file main.c (were
63execution starts), the header file toys.h (included by every command), and
64other global infrastructure.</li>
65<li>The <a href="#lib">lib directory</a> contains common functions shared by
Rob Landleyc8d0da52012-07-15 17:47:08 -050066multiple commands:</li>
67<ul>
68<li><a href="#lib_lib">lib/lib.c</a></li>
69<li><a href="#lib_llist">lib/llist.c</a></li>
70<li><a href="#lib_args">lib/args.c</a></li>
71<li><a href="#lib_dirtree">lib/dirtree.c</a></li>
72</ul>
Rob Landley7c04f012008-01-20 19:00:16 -060073<li>The <a href="#toys">toys directory</a> contains the C files implementating
Rob Landleyc0e56ed2012-10-08 00:02:30 -050074each command. Currently it contains three subdirectories:
75posix, lsb, and other.</li>
Rob Landley7c04f012008-01-20 19:00:16 -060076<li>The <a href="#scripts">scripts directory</a> contains the build and
77test infrastructure.</li>
78<li>The <a href="#kconfig">kconfig directory</a> contains the configuration
79infrastructure implementing menuconfig (copied from the Linux kernel).</li>
80<li>The <a href="#generated">generated directory</a> contains intermediate
81files generated from other parts of the source code.</li>
82</ul>
Rob Landley4e68de12007-12-13 07:00:27 -060083
Rob Landleybbe500e2012-02-26 21:53:15 -060084<a name="adding" />
Rob Landley7c04f012008-01-20 19:00:16 -060085<p><h1>Adding a new command</h1></p>
Rob Landleyc0e56ed2012-10-08 00:02:30 -050086<p>To add a new command to toybox, add a C file implementing that command under
Rob Landley7c04f012008-01-20 19:00:16 -060087the toys directory. No other files need to be modified; the build extracts
Rob Landley6882ee82008-02-12 18:41:34 -060088all the information it needs (such as command line arguments) from specially
Rob Landley7c04f012008-01-20 19:00:16 -060089formatted comments and macros in the C file. (See the description of the
Rob Landleye7c9a6d2012-02-28 06:34:09 -060090<a href="#generated">"generated" directory</a> for details.)</p>
Rob Landley4e68de12007-12-13 07:00:27 -060091
Rob Landleyc0e56ed2012-10-08 00:02:30 -050092<p>Currently there are three subdirectories under "toys", one for commands
93defined by the POSIX standard, one for commands defined by the Linux Standard
94Base, and one for all other commands. (This is just for developer convenience
95sorting them, the directories are otherwise functionally identical.)</p>
96
97<p>An easy way to start a new command is copy the file "toys/other/hello.c" to
Rob Landley7c04f012008-01-20 19:00:16 -060098the name of the new command, and modify this copy to implement the new command.
Rob Landley6882ee82008-02-12 18:41:34 -060099This file is an example command meant to be used as a "skeleton" for
Rob Landley7c04f012008-01-20 19:00:16 -0600100new commands (more or less by turning every instance of "hello" into the
101name of your command, updating the command line arguments, globals, and
102help data, and then filling out its "main" function with code that does
Rob Landley6882ee82008-02-12 18:41:34 -0600103something interesting). It provides examples of all the build infrastructure
104(including optional elements like command line argument parsing and global
105variables that a "hello world" program doesn't strictly need).</p>
Rob Landley7c04f012008-01-20 19:00:16 -0600106
107<p>Here's a checklist of steps to turn hello.c into another command:</p>
108
109<ul>
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500110<li><p>First "cd toys/other" and "cp hello.c yourcommand.c". Note that the name
Rob Landley7c04f012008-01-20 19:00:16 -0600111of this file is significant, it's the name of the new command you're adding
112to toybox. Open your new file in your favorite editor.</p></li>
113
114<li><p>Change the one line comment at the top of the file (currently
115"hello.c - A hello world program") to describe your new file.</p></li>
116
117<li><p>Change the copyright notice to your name, email, and the current
118year.</p></li>
119
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500120<li><p>Give a URL to the relevant standards document, where applicable.
121(Sample links to SUSv4 and LSB are provided, feel free to link to other
122documentation or standards as appropriate.)</p></li>
Rob Landley7c04f012008-01-20 19:00:16 -0600123
Rob Landley66a69d92012-01-16 01:44:17 -0600124<li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line.
125The NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a>
126structure. The arguments to the NEWTOY macro are:</p>
127
128<ol>
129<li><p>the name used to run your command</p></li>
130<li><p>the command line argument <a href="#lib_args">option parsing string</a> (NULL if none)</p></li>
131<li><p>a bitfield of TOYFLAG values
132(defined in toys.h) providing additional information such as where your
133command should be installed on a running system, whether to blank umask
134before running, whether or not the command must run as root (and thus should
135retain root access if installed SUID), and so on.</p></li>
136</ol>
137</li>
Rob Landley7c04f012008-01-20 19:00:16 -0600138
139<li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the
140comment block) to supply your command's configuration and help
141information. The uppper case config symbols are used by menuconfig, and are
142also what the CFG_ and USE_() macros are generated from (see [TODO]). The
143help information here is used by menuconfig, and also by the "help" command to
144describe your new command. (See [TODO] for details.) By convention,
Rob Landley66a69d92012-01-16 01:44:17 -0600145unfinished commands default to "n" and finished commands default to "y",
146so "make defconfig" selects all finished commands. (Note, "finished" means
147"ready to be used", not that it'll never change again.)<p>
148
149<p>Each help block should start with a "usage: yourcommand" line explaining
150any command line arguments added by this config option. The "help" command
151outputs this text, and scripts/config2help.c in the build infrastructure
152collates these usage lines for commands with multiple configuration
153options when producing generated/help.h.</p>
154</li>
Rob Landley7c04f012008-01-20 19:00:16 -0600155
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500156<li><p>Change the "#define FOR_hello" line to "#define FOR_yourcommand" right
157before the "#include <toys.h>". (This selects the appropriate FLAG_ macros and
158does a "#define TT this.yourcommand" so you can access the global variables
159out of the space-saving union of structures. If you aren't using any command
160flag bits and aren't defining a GLOBAL block, you can delete this line.)</p></li>
Rob Landley7c04f012008-01-20 19:00:16 -0600161
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500162<li><p>Update the GLOBALS() macro to contain your command's global
163variables. If your command has no global variables, delete this macro.</p>
164
165<p>Variables in the GLOBALS() block are are stored in a space saving
166<a href="#toy_union">union of structures</a> format, which may be accessed
167using the TT macro as if TT were a global structure (so TT.membername).
168If you specified two-character command line arguments in
169NEWTOY(), the first few global variables will be initialized by the automatic
170argument parsing logic, and the type and order of these variables must
171correspond to the arguments specified in NEWTOY().
172(See <a href="#lib_args">lib/args.c</a> for details.)</p></li>
Rob Landley7c04f012008-01-20 19:00:16 -0600173
174<li><p>Rename hello_main() to yourcommand_main(). This is the main() function
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500175where execution of your command starts. Your command line options are
176already sorted into this.optflags, this.optargs, this.optc, and the GLOBALS()
177as appropriate by the time this function is called. (See
178<a href="#lib_args">get_optflags()</a> for details.</p></li>
Rob Landley7c04f012008-01-20 19:00:16 -0600179</ul>
180
181<p><a name="top" /><h2>Top level directory.</h2></p>
182
Rob Landley66a69d92012-01-16 01:44:17 -0600183<p>This directory contains global infrastructure.</p>
184
185<h3>toys.h</h3>
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500186<p>Each command #includes "toys.h" as part of its standard prolog. It
187may "#define FOR_commandname" before doing so to get some extra entries
188specific to this command.</p>
Rob Landley66a69d92012-01-16 01:44:17 -0600189
190<p>This file sucks in most of the commonly used standard #includes, so
191individual files can just #include "toys.h" and not have to worry about
192stdargs.h and so on. Individual commands still need to #include
193special-purpose headers that may not be present on all systems (and thus would
194prevent toybox from building that command on such a system with that command
195enabled). Examples include regex support, any "linux/" or "asm/" headers, mtab
196support (mntent.h and sys/mount.h), and so on.</p>
197
198<p>The toys.h header also defines structures for most of the global variables
199provided to each command by toybox_main(). These are described in
200detail in the description for main.c, where they are initialized.</p>
201
202<p>The global variables are grouped into structures (and a union) for space
203savings, to more easily track the amount of memory consumed by them,
204so that they may be automatically cleared/initialized as needed, and so
205that access to global variables is more easily distinguished from access to
206local variables.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600207
208<h3>main.c</h3>
209<p>Contains the main() function where execution starts, plus
210common infrastructure to initialize global variables and select which command
Rob Landley6882ee82008-02-12 18:41:34 -0600211to run. The "toybox" multiplexer command also lives here. (This is the
Rob Landley7c04f012008-01-20 19:00:16 -0600212only command defined outside of the toys directory.)</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600213
Rob Landley6882ee82008-02-12 18:41:34 -0600214<p>Execution starts in main() which trims any path off of the first command
215name and calls toybox_main(), which calls toy_exec(), which calls toy_find()
Rob Landley66a69d92012-01-16 01:44:17 -0600216and toy_init() before calling the appropriate command's function from
217toy_list[] (via toys.which->toy_main()).
Rob Landley6882ee82008-02-12 18:41:34 -0600218If the command is "toybox", execution recurses into toybox_main(), otherwise
219the call goes to the appropriate commandname_main() from a C file in the toys
220directory.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600221
Rob Landley6882ee82008-02-12 18:41:34 -0600222<p>The following global variables are defined in main.c:</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600223<ul>
Rob Landley66a69d92012-01-16 01:44:17 -0600224<a name="toy_list" />
225<li><p><b>struct toy_list toy_list[]</b> - array describing all the
Rob Landley4e68de12007-12-13 07:00:27 -0600226commands currently configured into toybox. The first entry (toy_list[0]) is
227for the "toybox" multiplexer command, which runs all the other built-in commands
228without symlinks by using its first argument as the name of the command to
229run and the rest as that command's argument list (ala "./toybox echo hello").
230The remaining entries are the commands in alphabetical order (for efficient
231binary search).</p>
232
233<p>This is a read-only array initialized at compile time by
Rob Landley6882ee82008-02-12 18:41:34 -0600234defining macros and #including generated/newtoys.h.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600235
Rob Landley66a69d92012-01-16 01:44:17 -0600236<p>Members of struct toy_list (defined in "toys.h") include:</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600237<ul>
238<li><p>char *<b>name</b> - the name of this command.</p></li>
239<li><p>void (*<b>toy_main</b>)(void) - function pointer to run this
240command.</p></li>
241<li><p>char *<b>options</b> - command line option string (used by
242get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500243entries in the toy's GLOBALS struct). When this is NULL, no option
Rob Landley66a69d92012-01-16 01:44:17 -0600244parsing is done before calling toy_main().</p></li>
Rob Landley6882ee82008-02-12 18:41:34 -0600245<li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p>
246
247<ul>
248<li><b>TOYFLAG_USR</b> - Install this command under /usr</li>
249<li><b>TOYFLAG_BIN</b> - Install this command under /bin</li>
250<li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li>
251<li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li>
252<li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li>
Rob Landley66a69d92012-01-16 01:44:17 -0600253<li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li>
254<li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li>
Rob Landley6882ee82008-02-12 18:41:34 -0600255</ul>
256<br>
257
258<p>These flags are combined with | (or). For example, to install a command
259in /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p>
260</ul>
Rob Landley4e68de12007-12-13 07:00:27 -0600261</li>
262
Rob Landley66a69d92012-01-16 01:44:17 -0600263<li><p><b>struct toy_context toys</b> - global structure containing information
264common to all commands, initializd by toy_init() and defined in "toys.h".
265Members of this structure include:</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600266<ul>
267<li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list
268structure. Mostly used to grab the name of the running command
269(toys->which.name).</p>
270</li>
271<li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The
272error_exit() functions will return 1 if this is zero, otherwise they'll
273return this value.</p></li>
274<li><p>char **<b>argv</b> - "raw" command line options, I.E. the original
275unmodified string array passed in to main(). Note that modifying this changes
Rob Landley66a69d92012-01-16 01:44:17 -0600276"ps" output, and is not recommended. This array is null terminated; a NULL
277entry indicates the end of the array.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600278<p>Most commands don't use this field, instead the use optargs, optflags,
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500279and the fields in the GLOBALS struct initialized by get_optflags().</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600280</li>
281<li><p>unsigned <b>optflags</b> - Command line option flags, set by
Rob Landley66a69d92012-01-16 01:44:17 -0600282<a href="#lib_args">get_optflags()</a>. Indicates which of the command line options listed in
Rob Landley6882ee82008-02-12 18:41:34 -0600283toys->which.options occurred this time.</p>
284
285<p>The rightmost command line argument listed in toys->which.options sets bit
2861, the next one sets bit 2, and so on. This means the bits are set in the same
287order the binary digits would be listed if typed out as a string. For example,
288the option string "abcd" would parse the command line "-c" to set optflags to 2,
289"-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p>
290
291<p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2,
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500292b=4, a=8. Punctuation after a letter initializes global variables at the
293start of the GLOBALS() block (see <a href="#toy_union">union toy_union this</a>
294for details).</p>
295
296<p>The build infrastructure creates FLAG_ macros for each option letter,
297corresponding to the bit position, so you can check (toys.optflags & FLAG_x)
298to see if a flag was specified. (The correct set of FLAG_ macros is selected
299by defining FOR_mycommand before #including toys.h. The macros live in
300toys/globals.h which is generated by scripts/make.sh.)</p>
Rob Landley6882ee82008-02-12 18:41:34 -0600301
Rob Landley66a69d92012-01-16 01:44:17 -0600302<p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p>
Rob Landley6882ee82008-02-12 18:41:34 -0600303
304</li>
Rob Landley4e68de12007-12-13 07:00:27 -0600305<li><p>char **<b>optargs</b> - Null terminated array of arguments left over
306after get_optflags() removed all the ones it understood. Note: optarg[0] is
307the first argument, not the command name. Use toys.which->name for the command
308name.</p></li>
Rob Landley6882ee82008-02-12 18:41:34 -0600309<li><p>int <b>optc</b> - Optarg count, equivalent to argc but for
310optargs[].<p></li>
Rob Landley4e68de12007-12-13 07:00:27 -0600311<li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message
312via help_main() before exiting. (True during option parsing, defaults to
313false afterwards.)</p></li>
Rob Landley66a69d92012-01-16 01:44:17 -0600314</ul>
Rob Landley4e68de12007-12-13 07:00:27 -0600315
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500316<a name="toy_union" />
Rob Landley66a69d92012-01-16 01:44:17 -0600317<li><p><b>union toy_union this</b> - Union of structures containing each
Rob Landley4e68de12007-12-13 07:00:27 -0600318command's global variables.</p>
319
Rob Landley6882ee82008-02-12 18:41:34 -0600320<p>Global variables are useful: they reduce the overhead of passing extra
321command line arguments between functions, they conveniently start prezeroed to
322save initialization costs, and the command line argument parsing infrastructure
323can also initialize global variables with its results.</p>
324
325<p>But since each toybox process can only run one command at a time, allocating
326space for global variables belonging to other commands you aren't currently
327running would be wasteful.</p>
328
329<p>Toybox handles this by encapsulating each command's global variables in
Rob Landley66a69d92012-01-16 01:44:17 -0600330a structure, and declaring a union of those structures with a single global
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500331instance (called "this"). The GLOBALS() macro contains the global
Rob Landley66a69d92012-01-16 01:44:17 -0600332variables that should go in the current command's global structure. Each
333variable can then be accessed as "this.commandname.varname".
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500334If you #defined FOR_commandname before including toys.h, the macro TT is
335#defined to this.commandname so the variable can then be accessed as
336"TT.variable". See toys/hello.c for an example.</p>
Rob Landley6882ee82008-02-12 18:41:34 -0600337
Rob Landley66a69d92012-01-16 01:44:17 -0600338<p>A command that needs global variables should declare a structure to
Rob Landley4e68de12007-12-13 07:00:27 -0600339contain them all, and add that structure to this union. A command should never
340declare global variables outside of this, because such global variables would
341allocate memory when running other commands that don't use those global
342variables.</p>
343
Rob Landley66a69d92012-01-16 01:44:17 -0600344<p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>,
Rob Landley4e68de12007-12-13 07:00:27 -0600345as specified by the options field off this command's toy_list entry. See
346the get_optargs() description in lib/args.c for details.</p>
347</li>
348
Rob Landley81b899d2007-12-18 02:02:47 -0600349<li><b>char toybuf[4096]</b> - a common scratch space buffer so
Rob Landley4e68de12007-12-13 07:00:27 -0600350commands don't need to allocate their own. Any command is free to use this,
351and it should never be directly referenced by functions in lib/ (although
352commands are free to pass toybuf in to a library function as an argument).</li>
353</ul>
354
Rob Landley6882ee82008-02-12 18:41:34 -0600355<p>The following functions are defined in main.c:</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600356<ul>
357<li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list
358structure for this command name, or NULL if not found.</p></li>
Rob Landley81b899d2007-12-18 02:02:47 -0600359<li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out
360the global toys structure, calling get_optargs() if necessary.</p></li>
Rob Landley6882ee82008-02-12 18:41:34 -0600361<li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with
362arguments.</p>
363<p>Calls toy_find() on argv[0] (which must be just a command name
Rob Landley4e68de12007-12-13 07:00:27 -0600364without path). Returns if it can't find this command, otherwise calls
Rob Landley6882ee82008-02-12 18:41:34 -0600365toy_init(), toys->which.toy_main(), and exit() instead of returning.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600366
Rob Landley6882ee82008-02-12 18:41:34 -0600367<p>Use the library function xexec() to fall back to external executables
368in $PATH if toy_exec() can't find a built-in command. Note that toy_exec()
369does not strip paths before searching for a command, so "./command" will
370never match an internal command.</li>
371
372<li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer
373command (I.E. "toybox"). Given a command name as its first argument, calls
374toy_exec() on its arguments. With no arguments, it lists available commands.
375If the first argument starts with "-" it lists each command with its default
376install path prepended.</p></li>
Rob Landley4e68de12007-12-13 07:00:27 -0600377
378</ul>
379
380<h3>Config.in</h3>
381
382<p>Top level configuration file in a stylized variant of
Rob Landley6882ee82008-02-12 18:41:34 -0600383<a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600384
385<p>These files are directly used by "make menuconfig" to select which commands
386to build into toybox (thus generating a .config file), and by
Rob Landley6882ee82008-02-12 18:41:34 -0600387scripts/config2help.py to create generated/help.h.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600388
389<h3>Temporary files:</h3>
390
Rob Landley6882ee82008-02-12 18:41:34 -0600391<p>There is one temporary file in the top level source directory:</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600392<ul>
393<li><p><b>.config</b> - Configuration file generated by kconfig, indicating
394which commands (and options to commands) are currently enabled. Used
Rob Landley6882ee82008-02-12 18:41:34 -0600395to make generated/config.h and determine which toys/*.c files to build.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600396
Rob Landley6882ee82008-02-12 18:41:34 -0600397<p>You can create a human readable "miniconfig" version of this file using
Rob Landley66a69d92012-01-16 01:44:17 -0600398<a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these
Rob Landley6882ee82008-02-12 18:41:34 -0600399instructions</a>.</p>
400</li>
401</ul>
402
Rob Landleye7c9a6d2012-02-28 06:34:09 -0600403<a name="generated" />
Rob Landley6882ee82008-02-12 18:41:34 -0600404<p>The "generated/" directory contains files generated from other source code
405in toybox. All of these files can be recreated by the build system, although
406some (such as generated/help.h) are shipped in release versions to reduce
407environmental dependencies (I.E. so you don't need python on your build
408system).</p>
409
410<ul>
411<li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
Rob Landley4e68de12007-12-13 07:00:27 -0600412generated from .config by a sed invocation in the top level Makefile.</p>
413
414<p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
Rob Landley6882ee82008-02-12 18:41:34 -0600415disabled symbols. This allows the use of normal if() statements to remove
416code at compile time via the optimizer's dead code elimination (which removes
417from the binary any code that cannot be reached). This saves space without
Rob Landley4e68de12007-12-13 07:00:27 -0600418cluttering the code with #ifdefs or leading to configuration dependent build
419breaks. (See the 1992 Usenix paper
Rob Landleyb6063de2012-01-29 13:54:13 -0600420<a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef
Rob Landley4e68de12007-12-13 07:00:27 -0600421Considered Harmful</a> for more information.)</p>
422
423<p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
424is enabled, and nothing when the symbol is disabled. This can be used
425for things like varargs or variable declarations which can't always be
Rob Landley6882ee82008-02-12 18:41:34 -0600426eliminated by a simple test on CFG_SYMBOL. Note that
Rob Landley4e68de12007-12-13 07:00:27 -0600427(unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
428still result in configuration dependent build breaks. Use with caution.</p>
429</li>
430</ul>
431
Rob Landley81b899d2007-12-18 02:02:47 -0600432<p><h2>Directory toys/</h2></p>
Rob Landley4e68de12007-12-13 07:00:27 -0600433
434<h3>toys/Config.in</h3>
435
436<p>Included from the top level Config.in, contains one or more
437configuration entries for each command.</p>
438
Rob Landley81b899d2007-12-18 02:02:47 -0600439<p>Each command has a configuration entry matching the command name (although
440configuration symbols are uppercase and command names are lower case).
Rob Landley4e68de12007-12-13 07:00:27 -0600441Options to commands start with the command name followed by an underscore and
Rob Landley66a69d92012-01-16 01:44:17 -0600442the option name. Global options are attached to the "toybox" command,
Rob Landley4e68de12007-12-13 07:00:27 -0600443and thus use the prefix "TOYBOX_". This organization is used by
Rob Landley81b899d2007-12-18 02:02:47 -0600444scripts/cfg2files to select which toys/*.c files to compile for a given
445.config.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600446
Rob Landley66a69d92012-01-16 01:44:17 -0600447<p>A command with multiple names (or multiple similar commands implemented in
Rob Landley4e68de12007-12-13 07:00:27 -0600448the same .c file) should have config symbols prefixed with the name of their
449C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
450have config symbols they're options (symbols with an underscore and suffix)
451to the NEWTOY() name. (See toys/toylist.h)</p>
452
453<h3>toys/toylist.h</h3>
Rob Landley81b899d2007-12-18 02:02:47 -0600454<p>The first half of this file prototypes all the structures to hold
Rob Landleyda09b7f2007-12-20 06:29:59 -0600455global variables for each command, and puts them in toy_union. These
456prototypes are only included if the macro NEWTOY isn't defined (in which
457case NEWTOY is defined to a default value that produces function
458prototypes).</p>
Rob Landley81b899d2007-12-18 02:02:47 -0600459
Rob Landleyda09b7f2007-12-20 06:29:59 -0600460<p>The second half of this file lists all the commands in alphabetical
461order, along with their command line arguments and install location.
462Each command has an appropriate configuration guard so only the commands that
463are enabled wind up in the list.</p>
464
465<p>The first time this header is #included, it defines structures and
466produces function prototypes for the commands in the toys directory.</p>
467
468
469<p>The first time it's included, it defines structures and produces function
470prototypes.
471 This
Rob Landley81b899d2007-12-18 02:02:47 -0600472is used to initialize toy_list in main.c, and later in that file to initialize
473NEED_OPTIONS (to figure out whether the command like parsing logic is needed),
474and to put the help entries in the right order in toys/help.c.</p>
Rob Landley4e68de12007-12-13 07:00:27 -0600475
476<h3>toys/help.h</h3>
477
478<p>#defines two help text strings for each command: a single line
479command_help and an additinal command_help_long. This is used by help_main()
480in toys/help.c to display help for commands.</p>
481
482<p>Although this file is generated from Config.in help entries by
483scripts/config2help.py, it's shipped in release tarballs so you don't need
484python on the build system. (If you check code out of source control, or
485modify Config.in, then you'll need python installed to rebuild it.)</p>
486
487<p>This file contains help for all commands, regardless of current
488configuration, but only the currently enabled ones are entered into help_data[]
489in toys/help.c.</p>
490
Rob Landley137bf342012-03-09 08:33:57 -0600491<a name="lib">
Rob Landley81b899d2007-12-18 02:02:47 -0600492<h2>Directory lib/</h2>
Rob Landley4e68de12007-12-13 07:00:27 -0600493
Rob Landley137bf342012-03-09 08:33:57 -0600494<p>TODO: document lots more here.</p>
495
Rob Landleyc8d0da52012-07-15 17:47:08 -0500496<p>lib: getmountlist(), error_msg/error_exit, xmalloc(),
Rob Landley7c04f012008-01-20 19:00:16 -0600497strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
498itoa().</p>
499
Rob Landley137bf342012-03-09 08:33:57 -0600500<h3>lib/portability.h</h3>
501
502<p>This file is automatically included from the top of toys.h, and smooths
503over differences between platforms (hardware targets, compilers, C libraries,
504operating systems, etc).</p>
505
506<p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p>
507
508<p>A macro like SWAP_LE32(x) means "The value in x is stored as a little
509endian 32 bit value, so perform the translation to/from whatever the native
51032-bit format is". You do the swap once on the way in, and once on the way
511out. If your target is already little endian, the macro is a NOP.</p>
512
513<p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions.
514In each case, the name of the macro refers to the _external_ representation,
515and converts to/from whatever your native representation happens to be (which
516can vary depending on what you're currently compiling for).</p>
517
Rob Landleyc8d0da52012-07-15 17:47:08 -0500518<a name="lib_llist"><h3>lib/llist.c</h3>
519
520<p>Some generic single and doubly linked list functions, which take
521advantage of a couple properties of C:</p>
522
523<ul>
524<li><p>Structure elements are laid out in memory in the order listed, and
525the first element has no padding. This means you can always treat (typecast)
526a pointer to a structure as a pointer to the first element of the structure,
527even if you don't know anything about the data following it.</p></li>
528
529<li><p>An array of length zero at the end of a structure adds no space
530to the sizeof() the structure, but if you calculate how much extra space
531you want when you malloc() the structure it will be available at the end.
532Since C has no bounds checking, this means each struct can have one variable
533length array.</p></li>
534</ul>
535
536<p>Toybox's list structures always have their <b>next</b> pointer as
537the first entry of each struct, and singly linked lists end with a NULL pointer.
538This allows generic code to traverse such lists without knowing anything
539else about the specific structs composing them: if your pointer isn't NULL
540typecast it to void ** and dereference once to get the next entry.</p>
541
542<p><b>lib/lib.h</b> defines three structure types:</p>
543<ul>
544<li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>),
545memory for which is allocated as part of the node. (I.E. llist_traverse(list,
546free); can clean up after this type of list.)</p></li>
547
548<li><p><b>struct arg_list</b> - stores a pointer to a single string
549(<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li>
550
551<li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list
552*prev</b> along with a <b>char *data</b> for payload.</p></li>
553</ul>
554
555<b>List Functions</b>
556
557<ul>
558<li><p>void *<b>llist_pop</b>(void **list) - advances through a list ala
559<b>node = llist_pop(&list);</b> This doesn't modify the list contents,
560but does advance the pointer you feed it (which is why you pass the _address_
561of that pointer, not the pointer itself).</p></li>
562
563<li><p>void <b>llist_traverse</b>(void *list, void (*using)(void *data)) -
564iterate through a list calling a function on each node.</p></li>
565
566<li><p>struct double_list *<b>dlist_add</b>(struct double_list **llist, char *data)
567- append an entry to a circular linked list.
568This function allocates a new struct double_list wrapper and returns the
569pointer to the new entry (which you can usually ignore since it's llist->prev,
570but if llist was NULL you need it). The argument is the ->data field for the
571new node.</p></li>
572<ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist,
573struct double_list *new) - append existing struct double_list to
574list, does not allocate anything.</p></li></ul>
575</ul>
576
577<b>Trivia questions:</b>
578
579<ul>
580<li><p><b>Why do arg_list and double_list contain a char * payload instead of
581a void *?</b> - Because you always have to typecast a void * to use it, and
582typecasting a char * does no harm. Thus having it default to the most common
583pointer type saves a few typecasts (strings are the most common payload),
584and doesn't hurt anything otherwise.</p>
585</li>
586
587<li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force
588you to keep track of which one you're using, calling free(node->str) would
589be bad, and _failing_ to free(node->arg) leaks memory.</p></li>
590
591<li><p><b>Why does llist_pop() take a void * instead of void **?</b> -
592because the stupid compiler complains about "type punned pointers" when
593you typecast and dereference ont he same line,
594due to insane FSF developers hardwiring limitations of their optimizer
595into gcc's warning system. Since C automatically typecasts any other
596pointer _down_ to a void *, the current code works fine. It's sad that it
597won't warn you if you forget the &, but the code crashes pretty quickly in
598that case.</p></li>
599
600<li><p><b>How do I assemble a singly-linked-list in order?</b> - use
601a double_list, dlist_add() your entries, and then break the circle with
602<b>list->prev->next = NULL;</b> when done.</li>
603</ul>
604
Rob Landley66a69d92012-01-16 01:44:17 -0600605<a name="lib_args"><h3>lib/args.c</h3>
Rob Landley7c04f012008-01-20 19:00:16 -0600606
Rob Landley66a69d92012-01-16 01:44:17 -0600607<p>Toybox's main.c automatically parses command line options before calling the
608command's main function. Option parsing starts in get_optflags(), which stores
609results in the global structures "toys" (optflags and optargs) and "this".</p>
610
611<p>The option parsing infrastructure stores a bitfield in toys.optflags to
612indicate which options the current command line contained. Arguments
613attached to those options are saved into the command's global structure
614("this"). Any remaining command line arguments are collected together into
615the null-terminated array toys.optargs, with the length in toys.optc. (Note
616that toys.optargs does not contain the current command name at position zero,
617use "toys.which->name" for that.) The raw command line arguments get_optflags()
618parsed are retained unmodified in toys.argv[].</p>
619
620<p>Toybox's option parsing logic is controlled by an "optflags" string, using
621a format reminiscent of getopt's optargs but has several important differences.
622Toybox does not use the getopt()
623function out of the C library, get_optflags() is an independent implementation
624which doesn't permute the original arguments (and thus doesn't change how the
625command is displayed in ps and top), and has many features not present in
626libc optargs() (such as the ability to describe long options in the same string
627as normal options).</p>
628
629<p>Each command's NEWTOY() macro has an optflags string as its middle argument,
630which sets toy_list.options for that command to tell get_optflags() what
631command line arguments to look for, and what to do with them.
632If a command has no option
633definition string (I.E. the argument is NULL), option parsing is skipped
634for that command, which must look at the raw data in toys.argv to parse its
635own arguments. (If no currently enabled command uses option parsing,
636get_optflags() is optimized out of the resulting binary by the compiler's
637--gc-sections option.)</p>
638
639<p>You don't have to free the option strings, which point into the environment
640space (I.E. the string data is not copied). A TOYFLAG_NOFORK command
641that uses the linked list type "*" should free the list objects but not
642the data they point to, via "llist_free(TT.mylist, NULL);". (If it's not
643NOFORK, exit() will free all the malloced data anyway unless you want
644to implement a CONFIG_TOYBOX_FREE cleanup for it.)</p>
645
646<h4>Optflags format string</h4>
647
648<p>Note: the optflags option description string format is much more
649concisely described by a large comment at the top of lib/args.c.</p>
650
651<p>The general theory is that letters set optflags, and punctuation describes
652other actions the option parsing logic should take.</p>
653
654<p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b>
655is parsed using the optflags string "<b>a#b:c:d</b>". (I.E.
656toys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d",
657"walrus", "-a", "42"]). When get_optflags() returns, the following data is
658available to command_main():
659
660<ul>
661<li><p>In <b>struct toys</b>:
662<ul>
663<li>toys.optflags = 13; // -a = 8 | -b = 4 | -d = 1</li>
664<li>toys.optargs[0] = "walrus"; // leftover argument</li>
665<li>toys.optargs[1] = NULL; // end of list</li>
666<li>toys.optc=1; // there was 1 leftover argument</li>
667<li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments
668</ul>
669<p></li>
670
671<li><p>In <b>union this</b> (treated as <b>long this[]</b>):
672<ul>
673<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>
674<li>this[1] = (long)"fruit"; // argument to -b</li>
675<li>this[2] = 42; // argument to -a</li>
676</ul>
677</p></li>
678</ul>
679
680<p>If the command's globals are:</p>
681
682<blockquote><pre>
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500683GLOBALS(
Rob Landley66a69d92012-01-16 01:44:17 -0600684 char *c;
685 char *b;
686 long a;
687)
Rob Landley66a69d92012-01-16 01:44:17 -0600688</pre></blockquote>
689<p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember,
690each entry that receives an argument must be a long or pointer, to line up
691with the array position. Right to left in the optflags string corresponds to
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500692top to bottom in GLOBALS().</p>
Rob Landley66a69d92012-01-16 01:44:17 -0600693
694<p><b>long toys.optflags</b></p>
695
696<p>Each option in the optflags string corresponds to a bit position in
697toys.optflags, with the same value as a corresponding binary digit. The
698rightmost argument is (1<<0), the next to last is (1<<1) and so on. If
Rob Landleyb4a0efa2012-02-06 21:15:19 -0600699the option isn't encountered while parsing argv[], its bit remains 0.</p>
700
701<p>For example,
Rob Landley66a69d92012-01-16 01:44:17 -0600702the optflags string "abcd" would parse the command line argument "-c" to set
703optflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to
7046 (I.E. 4|2), and "-a -c" would set optflags to 10 (2|8).</p>
705
706<p>Only letters are relevant to optflags, punctuation is skipped: in the
707string "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter
708usually indicate that the option takes an argument.</p>
709
Rob Landleyb4a0efa2012-02-06 21:15:19 -0600710<p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is
711the amount a long would have on 32-bit platforms anyway; 64 bit code on
71232 bit platforms is too expensive to require in common code used by almost
713all commands.) Bit positions beyond the 1<<31 aren't recorded, but
714parsing higher options can still set global variables.</p>
715
Rob Landley66a69d92012-01-16 01:44:17 -0600716<p><b>Automatically setting global variables from arguments (union this)</b></p>
717
718<p>The following punctuation characters may be appended to an optflags
719argument letter, indicating the option takes an additional argument:</p>
720
721<ul>
722<li><b>:</b> - plus a string argument, keep most recent if more than one.</li>
723<li><b>*</b> - plus a string argument, appended to a linked list.</li>
Rob Landley66a69d92012-01-16 01:44:17 -0600724<li><b>@</b> - plus an occurrence counter (stored in a long)</li>
Rob Landleyb6063de2012-01-29 13:54:13 -0600725<li><b>#</b> - plus a signed long argument.
726<li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li>
727<ul>The following can be appended to a float or double:
728<li><b>&lt;123</b> - error if argument is less than this</li>
729<li><b>&gt;123</b> - error if argument is greater than this</li>
730<li><b>=123</b> - default value if argument not supplied</li>
731</ul>
732<ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
733is enabled. (Otherwise the code to determine where floating point constants
734end drops out. When disabled, it can reserve a global data slot for the
735argument so offsets won't change, but will never fill it out.). You can handle
736this by using the USE_BLAH() macros with C string concatenation, ala:
737"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul>
Rob Landley66a69d92012-01-16 01:44:17 -0600738</ul>
739
740<p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
741The command line argument "-abc" may be interepreted many different ways:
742the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
743and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
744"c" as the argument to -b.</p>
745
746<p>Options which have an argument fill in the corresponding slot in the global
747union "this" (see generated/globals.h), treating it as an array of longs
748with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set
749this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if
750the corresponding argument is not encountered.</p>
751
752<p>This behavior is useful because the LP64 standard ensures long and pointer
Rob Landleyb4a0efa2012-02-06 21:15:19 -0600753are the same size. C99 guarantees structure members will occur in memory
754in the same order they're declared, and that padding won't be inserted between
Rob Landley66a69d92012-01-16 01:44:17 -0600755consecutive variables of register size. Thus the first few entries can
756be longs or pointers corresponding to the saved arguments.</p>
757
758<p><b>char *toys.optargs[]</b></p>
759
760<p>Command line arguments in argv[] which are not consumed by option parsing
761(I.E. not recognized either as -flags or arguments to -flags) will be copied
762to toys.optargs[], with the length of that array in toys.optc.
763(When toys.optc is 0, no unrecognized command line arguments remain.)
764The order of entries is preserved, and as with argv[] this new array is also
765terminated by a NULL entry.</p>
766
767<p>Option parsing can require a minimum or maximum number of optargs left
768over, by adding "<1" (read "at least one") or ">9" ("at most nine") to the
769start of the optflags string.</p>
770
771<p>The special argument "--" terminates option parsing, storing all remaining
772arguments in optargs. The "--" itself is consumed.</p>
773
774<p><b>Other optflags control characters</b></p>
775
776<p>The following characters may occur at the start of each command's
777optflags string, before any options that would set a bit in toys.optflags:</p>
778
779<ul>
780<li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li>
781<li><b>?</b> - allow unknown arguments (pass non-option arguments starting
782with - through to optargs instead of erroring out).</li>
783<li><b>&amp;</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li>
784<li><b>&lt;</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li>
785<li><b>&gt;</b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li>
786</ul>
787
788<p>The following characters may be appended to an option character, but do
789not by themselves indicate an extra argument should be saved in this[].
790(Technically any character not recognized as a control character sets an
791optflag, but letters are never control characters.)</p>
792
793<ul>
794<li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li>
795<li><b>|</b> - this option is required. If more than one marked, only one is required.</li>
796<li><b>+X</b> enabling this option also enables option X (switch bit on).</li>
797<li><b>~X</b> enabling this option disables option X (switch bit off).</li>
798<li><b>!X</b> this option cannot be used in combination with X (die with error).</li>
799<li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li>
800</ul>
801
Rob Landleyb6063de2012-01-29 13:54:13 -0600802<p>The following may be appended to a float or double:</p>
803
804<ul>
805<li><b>&lt;123</b> - error if argument is less than this</li>
806<li><b>&gt;123</b> - error if argument is greater than this</li>
807<li><b>=123</b> - default value if argument not supplied</li>
808</ul>
809
810<p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
811is enabled. (Otherwise the code to determine where floating point constants
812end drops out. When disabled, it can reserve a global data slot for the
813argument so offsets won't change, but will never fill it out.). You can handle
814this by using the USE_BLAH() macros with C string concatenation, ala:</p>
815
816<blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote>
817
Rob Landley66a69d92012-01-16 01:44:17 -0600818<p><b>--longopts</b></p>
819
820<p>The optflags string can contain long options, which are enclosed in
821parentheses. They may be appended to an existing option character, in
822which case the --longopt is a synonym for that option, ala "a:(--fred)"
823which understands "-a blah" or "--fred blah" as synonyms.</p>
824
825<p>Longopts may also appear before any other options in the optflags string,
826in which case they have no corresponding short argument, but instead set
827their own bit based on position. So for "(walrus)#(blah)xy:z" "command
828--walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8)
829and would assign this[1] = 42;</p>
830
831<p>A short option may have multiple longopt synonyms, "a(one)(two)", but
832each "bare longopt" (ala "(one)(two)abc" before any option characters)
833always sets its own bit (although you can group them with +X).</p>
Rob Landley7c04f012008-01-20 19:00:16 -0600834
Rob Landleyc8d0da52012-07-15 17:47:08 -0500835<a name="lib_dirtree"><h3>lib/dirtree.c</h3>
836
837<p>The directory tree traversal code should be sufficiently generic
838that commands never need to use readdir(), scandir(), or the fts.h family
839of functions.</p>
840
841<p>These functions do not call chdir() or rely on PATH_MAX. Instead they
842use openat() and friends, using one filehandle per directory level to
843recurseinto subdirectories. (I.E. they can descend 1000 directories deep
844if setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default
845in /proc/self/limits is generally 1024.)</p>
846
847<p>The basic dirtree functions are:</p>
848
849<ul>
850<li><p><b>dirtree_read(char *path, int (*callback)(struct dirtree node))</b> -
851recursively read directories, either applying callback() or returning
852a tree of struct dirtree if callback is NULL.</p></li>
853
854<li><p><b>dirtree_path(struct dirtree *node, int *plen)</b> - malloc() a
855string containing the path from the root of this tree to this node. If
856plen isn't NULL then *plen is how many extra bytes to malloc at the end
857of string.</p></li>
858
859<li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of
860containing directory, for use with openat() and such.</p></li>
861</ul>
862
863<p>The <b>dirtree_read()</b> function takes two arguments, a starting path for
864the root of the tree, and a callback function. The callback takes a
865<b>struct dirtree *</b> (from lib/lib.h) as its argument. If the callback is
866NULL, the traversal uses a default callback (dirtree_notdotdot()) which
867recursively assembles a tree of struct dirtree nodes for all files under
868this directory and subdirectories (filtering out "." and ".." entries),
869after which dirtree_read() returns the pointer to the root node of this
870snapshot tree.</p>
871
872<p>Otherwise the callback() is called on each entry in the directory,
873with struct dirtree * as its argument. This includes the initial
874node created by dirtree_read() at the top of the tree.</p>
875
876<p><b>struct dirtree</b></p>
877
878<p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat
879st</b> entries describing a file, plus a <b>char *symlink</b>
880which is NULL for non-symlinks.</p>
881
882<p>During a callback function, the <b>int data</b> field of directory nodes
883contains a dirfd (for use with the openat() family of functions). This is
884generally used by calling dirtree_parentfd() on the callback's node argument.
885For symlinks, data contains the length of the symlink string. On the second
886callback from DIRTREE_COMEAGAIN (depth-first traversal) data = -1 for
887all nodes (that's how you can tell it's the second callback).</p>
888
889<p>Users of this code may put anything they like into the <b>long extra</b>
890field. For example, "cp" and "mv" use this to store a dirfd for the destination
891directory (and use DIRTREE_COMEAGAIN to get the second callback so they can
892close(node->extra) to avoid running out of filehandles).
893This field is not directly used by the dirtree code, and
894thanks to LP64 it's large enough to store a typecast pointer to an
895arbitrary struct.</p>
896
897<p>The return value of the callback combines flags (with boolean or) to tell
898the traversal infrastructure how to behave:</p>
899
900<ul>
901<li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without
902this the struct dirtree is freed after the callback returns. Filtering out
903siblings is fine, but discarding a parent while keeping its child leaks
904memory.)</p></li>
905<li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this
906directory. (Does not propagate up tree: to abort entire traversal,
907return DIRTREE_ABORT from parent callbacks too.)</p></li>
908<li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for
909non-directory entries. The remaining flags only take effect when
910recursing into the children of a directory.</p></li>
911<li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback a second time after
912examining all directory contents, allowing depth-first traversal.
913On the second call, dirtree->data = -1.</p></li>
914<li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's
915<b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of
916dirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to
917directories as directories. (Avoiding infinite recursion is the callback's
918problem: the non-NULL dirtree->symlink can still distinguish between
919them.)</p></li>
920</ul>
921
922<p>Each struct dirtree contains three pointers (next, parent, and child)
923to other struct dirtree.</p>
924
925<p>The <b>parent</b> pointer indicates the directory
926containing this entry; even when not assembling a persistent tree of
927nodes the parent entries remain live up to the root of the tree while
928child nodes are active. At the top of the tree the parent pointer is
929NULL, meaning the node's name[] is either an absolute path or relative
930to cwd. The function dirtree_parentfd() gets the directory file descriptor
931for use with openat() and friends, returning AT_FDCWD at the top of tree.</p>
932
933<p>The <b>child</b> pointer points to the first node of the list of contents of
934this directory. If the directory contains no files, or the entry isn't
935a directory, child is NULL.</p>
936
937<p>The <b>next</b> pointer indicates sibling nodes in the same directory as this
938node, and since it's the first entry in the struct the llist.c traversal
939mechanisms work to iterate over sibling nodes. Each dirtree node is a
940single malloc() (even char *symlink points to memory at the end of the node),
941so llist_free() works but its callback must descend into child nodes (freeing
942a tree, not just a linked list), plus whatever the user stored in extra.</p>
943
944<p>The <b>dirtree_read</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>()
945to create a root node relative to the current directory, then calling
946<b>handle_callback</b>() on that node (which recurses as instructed by the callback
947return flags). Some commands (such as chgrp) bypass this wrapper, for example
948to control whether or not to follow symlinks to the root node; symlinks
949listed on the command line are often treated differently than symlinks
950encountered during recursive directory traversal).
951
952<p>The ls command not only bypasses the wrapper, but never returns
953<b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually
954from elsewhere in the program. This gives ls -lR manual control
955of traversal order, which is neither depth first nor breadth first but
956instead a sort of FIFO order requried by the ls standard.</p>
957
Rob Landleyc0e56ed2012-10-08 00:02:30 -0500958<a name="#toys">
959<h2>Directory toys/</h2>
960
961<p>This directory contains command implementations. Each command is a single
962self-contained file. Adding a new command involves adding a single
963file, and removing a command involves removing that file. Commands use
964shared infrastructure from the lib/ and generated/ directories.</p>
965
966<p>Currently there are three subdirectories under "toys/" containing commands
967described in POSIX-2008, the Linux Standard Base 4.1, or "other". The only
968difference this makes is which menu the command shows up in during "make
969menuconfig", the directories are otherwise identical. Note that they commands
970exist within a single namespace at runtime, so you can't have the same
971command in multiple subdirectories.</p>
972
973<p>(There are actually four sub-menus in "make menuconfig", the fourth
974contains global configuration options for toybox, and lives in Config.in at
975the top level.)</p>
976
977<p>See <a href="#adding">adding a new command</a> for details on the
978layout of a command file.</p>
979
Rob Landley81b899d2007-12-18 02:02:47 -0600980<h2>Directory scripts/</h2>
Rob Landley4e68de12007-12-13 07:00:27 -0600981
Rob Landley1f4f41a2012-10-08 21:31:07 -0500982<p>Build infrastructure. The makefile calls scripts/make.sh for "make"
983and scripts/install.sh for "make install".</p>
984
985<p>There's also a test suite, "make test" calls make/test.sh, which runs all
986the tests in make/test/*. You can run individual tests via
987"scripts/test.sh command", or "TEST_HOST=1 scripts/test.sh command" to run
988that test against the host implementation instead of the toybox one.</p>
989
Rob Landley4e68de12007-12-13 07:00:27 -0600990<h3>scripts/cfg2files.sh</h3>
991
992<p>Run .config through this filter to get a list of enabled commands, which
993is turned into a list of files in toys via a sed invocation in the top level
994Makefile.
995</p>
996
Rob Landley81b899d2007-12-18 02:02:47 -0600997<h2>Directory kconfig/</h2>
Rob Landley4e68de12007-12-13 07:00:27 -0600998
999<p>Menuconfig infrastructure copied from the Linux kernel. See the
1000Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
1001
Rob Landley66a69d92012-01-16 01:44:17 -06001002<a name="generated">
1003<h2>Directory generated/</h2>
1004
1005<p>All the files in this directory except the README are generated by the
1006build. (See scripts/make.sh)</p>
1007
1008<ul>
1009<li><p><b>config.h</b> - CFG_COMMAND and USE_COMMAND() macros set by menuconfig via .config.</p></li>
1010
1011<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>
1012
1013<li><p><b>help.h</b> - Help text strings for use by "help" command. Building
1014this file requires python on the host system, so the prebuilt file is shipped
1015in the build tarball to avoid requiring python to build toybox.</p></li>
1016
1017<li><p><b>newtoys.h</b> - List of NEWTOY() or OLDTOY() macros for all available
1018commands. Associates command_main() functions with command names, provides
1019option string for command line parsing (<a href="#lib_args">see lib/args.c</a>),
1020specifies where to install each command and whether toysh should fork before
1021calling it.</p></li>
1022</ul>
1023
1024<p>Everything in this directory is a derivative file produced from something
1025else. The entire directory is deleted by "make distclean".</p>
Rob Landley4e68de12007-12-13 07:00:27 -06001026<!--#include file="footer.html" -->