1*cf5a6c84SAndroid Build Coastguard Worker<html><head><title>toybox source code walkthrough</title></head> 2*cf5a6c84SAndroid Build Coastguard Worker<!--#include file="header.html" --> 3*cf5a6c84SAndroid Build Coastguard Worker 4*cf5a6c84SAndroid Build Coastguard Worker<p><h1><a name="style" /><a href="#style">Code style</a></h1></p> 5*cf5a6c84SAndroid Build Coastguard Worker 6*cf5a6c84SAndroid Build Coastguard Worker<p>The primary goal of toybox is _simple_ code. Keeping the code small is 7*cf5a6c84SAndroid Build Coastguard Workersecond, with speed and lots of features coming in somewhere after that. 8*cf5a6c84SAndroid Build Coastguard Worker(For more on that, see the <a href=design.html>design</a> page.)</p> 9*cf5a6c84SAndroid Build Coastguard Worker 10*cf5a6c84SAndroid Build Coastguard Worker<p>A simple implementation usually takes up fewer lines of source code, 11*cf5a6c84SAndroid Build Coastguard Workermeaning more code can fit on the screen at once, meaning the programmer can 12*cf5a6c84SAndroid Build Coastguard Workersee more of it on the screen and thus keep more if in their head at once. 13*cf5a6c84SAndroid Build Coastguard WorkerThis helps code auditing and thus reduces bugs. That said, sometimes being 14*cf5a6c84SAndroid Build Coastguard Workermore explicit is preferable to being clever enough to outsmart yourself: 15*cf5a6c84SAndroid Build Coastguard Workerdon't be so terse your code is unreadable.</p> 16*cf5a6c84SAndroid Build Coastguard Worker 17*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox has an actual coding style guide over on 18*cf5a6c84SAndroid Build Coastguard Worker<a href=design.html#codestyle>the design page</a>, but in general we just 19*cf5a6c84SAndroid Build Coastguard Workerwant the code to be consistent.</p> 20*cf5a6c84SAndroid Build Coastguard Worker 21*cf5a6c84SAndroid Build Coastguard Worker<p><h1><a name="building" /><a href="#building">Building Toybox</a></h1></p> 22*cf5a6c84SAndroid Build Coastguard Worker 23*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox is configured using the 24*cf5a6c84SAndroid Build Coastguard Worker<a href=https://github.com/torvalds/linux/blob/v2.6.16/Documentation/kbuild/kconfig-language.txt>Kconfig language</a> pioneered by the Linux 25*cf5a6c84SAndroid Build Coastguard Workerkernel, and adopted by many other projects (buildroot, OpenEmbedded, etc). 26*cf5a6c84SAndroid Build Coastguard WorkerThis generates a ".config" file containing the selected options, which 27*cf5a6c84SAndroid Build Coastguard Workercontrols which features are included when compiling toybox.</p> 28*cf5a6c84SAndroid Build Coastguard Worker 29*cf5a6c84SAndroid Build Coastguard Worker<p>Each configuration option has a default value. The defaults indicate the 30*cf5a6c84SAndroid Build Coastguard Worker"maximum sane configuration", I.E. if the feature defaults to "n" then it 31*cf5a6c84SAndroid Build Coastguard Workereither isn't complete or is a special-purpose option (such as debugging 32*cf5a6c84SAndroid Build Coastguard Workercode) that isn't intended for general purpose use.</p> 33*cf5a6c84SAndroid Build Coastguard Worker 34*cf5a6c84SAndroid Build Coastguard Worker<p>For a more compact human-editable version .config files, you can use the 35*cf5a6c84SAndroid Build Coastguard Worker<a href=http://landley.net/aboriginal/FAQ.html#dev_miniconfig>miniconfig</a> 36*cf5a6c84SAndroid Build Coastguard Workerformat.</p> 37*cf5a6c84SAndroid Build Coastguard Worker 38*cf5a6c84SAndroid Build Coastguard Worker<p>The standard build invocation is:</p> 39*cf5a6c84SAndroid Build Coastguard Worker 40*cf5a6c84SAndroid Build Coastguard Worker<ul> 41*cf5a6c84SAndroid Build Coastguard Worker<li>make defconfig #(or menuconfig)</li> 42*cf5a6c84SAndroid Build Coastguard Worker<li>make</li> 43*cf5a6c84SAndroid Build Coastguard Worker<li>make install</li> 44*cf5a6c84SAndroid Build Coastguard Worker</ul> 45*cf5a6c84SAndroid Build Coastguard Worker 46*cf5a6c84SAndroid Build Coastguard Worker<p>Type "make help" to see all available build options.</p> 47*cf5a6c84SAndroid Build Coastguard Worker 48*cf5a6c84SAndroid Build Coastguard Worker<p>The file "configure" contains a number of environment variable definitions 49*cf5a6c84SAndroid Build Coastguard Workerwhich influence the build, such as specifying which compiler to use or where 50*cf5a6c84SAndroid Build Coastguard Workerto install the resulting binaries. This file is included by the build, but 51*cf5a6c84SAndroid Build Coastguard Workeraccepts existing definitions of the environment variables, so it may be sourced 52*cf5a6c84SAndroid Build Coastguard Workeror modified by the developer before building and the definitions exported 53*cf5a6c84SAndroid Build Coastguard Workerto the environment will take precedence.</p> 54*cf5a6c84SAndroid Build Coastguard Worker 55*cf5a6c84SAndroid Build Coastguard Worker<p>(To clarify: ".config" lists the features selected by defconfig/menuconfig, 56*cf5a6c84SAndroid Build Coastguard WorkerI.E. "what to build", and "configure" describes the build and installation 57*cf5a6c84SAndroid Build Coastguard Workerenvironment, I.E. "how to build it".)</p> 58*cf5a6c84SAndroid Build Coastguard Worker 59*cf5a6c84SAndroid Build Coastguard Worker<p>By default "make install" puts files in /usr/toybox. Adding this to the 60*cf5a6c84SAndroid Build Coastguard Worker$PATH is up to you. The environment variable $PREFIX can change the 61*cf5a6c84SAndroid Build Coastguard Workerinstall location, ala "PREFIX=/usr/local/bin make install".</p> 62*cf5a6c84SAndroid Build Coastguard Worker 63*cf5a6c84SAndroid Build Coastguard Worker<p>If you need an unstripped (debug) version of any of these binaries, 64*cf5a6c84SAndroid Build Coastguard Workerlook in generated/unstripped.</p> 65*cf5a6c84SAndroid Build Coastguard Worker 66*cf5a6c84SAndroid Build Coastguard Worker<p><h1><a name="running"><a href="#running">Running a command</a></h1></p> 67*cf5a6c84SAndroid Build Coastguard Worker 68*cf5a6c84SAndroid Build Coastguard Worker<h2>main</h2> 69*cf5a6c84SAndroid Build Coastguard Worker 70*cf5a6c84SAndroid Build Coastguard Worker<p>The toybox main() function is at the end of main.c at the top level. It has 71*cf5a6c84SAndroid Build Coastguard Workertwo possible codepaths, only one of which is configured into any given build 72*cf5a6c84SAndroid Build Coastguard Workerof toybox.</p> 73*cf5a6c84SAndroid Build Coastguard Worker 74*cf5a6c84SAndroid Build Coastguard Worker<p>If CONFIG_SINGLE is selected, toybox is configured to contain only a single 75*cf5a6c84SAndroid Build Coastguard Workercommand, so most of the normal setup can be skipped. In this case the 76*cf5a6c84SAndroid Build Coastguard Workermultiplexer isn't used, instead main() calls toy_singleinit() (also in main.c) 77*cf5a6c84SAndroid Build Coastguard Workerto set up global state and parse command line arguments, calls the command's 78*cf5a6c84SAndroid Build Coastguard Workermain function out of toy_list (in the CONFIG_SINGLE case the array has a single entry, no need to search), and if the function returns instead of exiting 79*cf5a6c84SAndroid Build Coastguard Workerit flushes stdout (detecting error) and returns toys.exitval.</p> 80*cf5a6c84SAndroid Build Coastguard Worker 81*cf5a6c84SAndroid Build Coastguard Worker<p>When CONFIG_SINGLE is not selected, main() uses basename() to find the 82*cf5a6c84SAndroid Build Coastguard Workername it was run as, shifts its argument list one to the right so it lines up 83*cf5a6c84SAndroid Build Coastguard Workerwith where the multiplexer function expects it, and calls toybox_main(). This 84*cf5a6c84SAndroid Build Coastguard Workerleverages the multiplexer command's infrastructure to find and run the 85*cf5a6c84SAndroid Build Coastguard Workerappropriate command. (A command name starting with "toybox" will 86*cf5a6c84SAndroid Build Coastguard Workerrecursively call toybox_main(); you can go "./toybox toybox toybox toybox ls" 87*cf5a6c84SAndroid Build Coastguard Workerif you want to...)</p> 88*cf5a6c84SAndroid Build Coastguard Worker 89*cf5a6c84SAndroid Build Coastguard Worker<h2>toybox_main</h2> 90*cf5a6c84SAndroid Build Coastguard Worker 91*cf5a6c84SAndroid Build Coastguard Worker<p>The toybox_main() function is also in main,c. It handles a possible 92*cf5a6c84SAndroid Build Coastguard Worker--help option ("toybox --help ls"), prints the list of available commands if no 93*cf5a6c84SAndroid Build Coastguard Workerarguments were provided to the multiplexer (or with full path names if any 94*cf5a6c84SAndroid Build Coastguard Workerother option is provided before a command name, ala "toybox --list"). 95*cf5a6c84SAndroid Build Coastguard WorkerOtherwise it calls toy_exec() on its argument list.</p> 96*cf5a6c84SAndroid Build Coastguard Worker 97*cf5a6c84SAndroid Build Coastguard Worker<p>Note that the multiplexer is the first entry in toy_list (the rest of the 98*cf5a6c84SAndroid Build Coastguard Workerlist is sorted alphabetically to allow binary search), so toybox_main can 99*cf5a6c84SAndroid Build Coastguard Workercheat and just grab the first entry to quickly set up its context without 100*cf5a6c84SAndroid Build Coastguard Workersearching. Since all command names go through the multiplexer at least once 101*cf5a6c84SAndroid Build Coastguard Workerin the non-TOYBOX_SINGLE case, this avoids a redundant search of 102*cf5a6c84SAndroid Build Coastguard Workerthe list.</p> 103*cf5a6c84SAndroid Build Coastguard Worker 104*cf5a6c84SAndroid Build Coastguard Worker<p>The toy_exec() function is also in main.c. It performs toy_find() to 105*cf5a6c84SAndroid Build Coastguard Workerperform a binary search on the toy_list array to look up the command's 106*cf5a6c84SAndroid Build Coastguard Workerentry by name and saves it in the global variable which, calls toy_init() 107*cf5a6c84SAndroid Build Coastguard Workerto parse command line arguments and set up global state (using which->options), 108*cf5a6c84SAndroid Build Coastguard Workerand calls the appropriate command's main() function (which->toy_main). On 109*cf5a6c84SAndroid Build Coastguard Workerreturn it flushes all pending ansi FILE * I/O, detects if stdout had an 110*cf5a6c84SAndroid Build Coastguard Workererror, and then calls xexit() (which uses toys.exitval).</p> 111*cf5a6c84SAndroid Build Coastguard Worker 112*cf5a6c84SAndroid Build Coastguard Worker<p><h1><a name="infrastructure" /><a href="#infrastructure">Infrastructure</a></h1></p> 113*cf5a6c84SAndroid Build Coastguard Worker 114*cf5a6c84SAndroid Build Coastguard Worker<p>The toybox source code is in following directories:</p> 115*cf5a6c84SAndroid Build Coastguard Worker<ul> 116*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#top">top level directory</a> contains the file main.c (were 117*cf5a6c84SAndroid Build Coastguard Workerexecution starts), the header file toys.h (included by every command), and 118*cf5a6c84SAndroid Build Coastguard Workerother global infrastructure.</li> 119*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#lib">lib directory</a> contains common functions shared by 120*cf5a6c84SAndroid Build Coastguard Workermultiple commands:</li> 121*cf5a6c84SAndroid Build Coastguard Worker<ul> 122*cf5a6c84SAndroid Build Coastguard Worker<li><a href="#lib_lib">lib/lib.c</a></li> 123*cf5a6c84SAndroid Build Coastguard Worker<li><a href="#lib_xwrap">lib/xwrap.c</a></li> 124*cf5a6c84SAndroid Build Coastguard Worker<li><a href="#lib_llist">lib/llist.c</a></li> 125*cf5a6c84SAndroid Build Coastguard Worker<li><a href="#lib_args">lib/args.c</a></li> 126*cf5a6c84SAndroid Build Coastguard Worker<li><a href="#lib_dirtree">lib/dirtree.c</a></li> 127*cf5a6c84SAndroid Build Coastguard Worker</ul> 128*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#toys">toys directory</a> contains the C files implementating 129*cf5a6c84SAndroid Build Coastguard Workereach command. Currently it contains five subdirectories categorizing the 130*cf5a6c84SAndroid Build Coastguard Workercommands: posix, lsb, other, example, and pending.</li> 131*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#scripts">scripts directory</a> contains the build and 132*cf5a6c84SAndroid Build Coastguard Workertest infrastructure.</li> 133*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#kconfig">kconfig directory</a> contains the configuration 134*cf5a6c84SAndroid Build Coastguard Workerinfrastructure implementing menuconfig (copied from the Linux kernel).</li> 135*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#generated">generated directory</a> contains intermediate 136*cf5a6c84SAndroid Build Coastguard Workerfiles generated from other parts of the source code.</li> 137*cf5a6c84SAndroid Build Coastguard Worker<li>The <a href="#tests">tests directory</a> contains the test suite. 138*cf5a6c84SAndroid Build Coastguard WorkerNOSPACE=1 to allow tests to pass with diff -b</li> 139*cf5a6c84SAndroid Build Coastguard Worker</ul> 140*cf5a6c84SAndroid Build Coastguard Worker 141*cf5a6c84SAndroid Build Coastguard Worker<a name="adding" /> 142*cf5a6c84SAndroid Build Coastguard Worker<p><h1><a href="#adding">Adding a new command</a></h1></p> 143*cf5a6c84SAndroid Build Coastguard Worker<p>To add a new command to toybox, add a C file implementing that command to 144*cf5a6c84SAndroid Build Coastguard Workerone of the subdirectories under the toys directory. No other files need to 145*cf5a6c84SAndroid Build Coastguard Workerbe modified; the build extracts all the information it needs (such as command 146*cf5a6c84SAndroid Build Coastguard Workerline arguments) from specially formatted comments and macros in the C file. 147*cf5a6c84SAndroid Build Coastguard Worker(See the description of the <a href="#generated">"generated" directory</a> 148*cf5a6c84SAndroid Build Coastguard Workerfor details.)</p> 149*cf5a6c84SAndroid Build Coastguard Worker 150*cf5a6c84SAndroid Build Coastguard Worker<p>Currently there are five subdirectories under "toys", one for commands 151*cf5a6c84SAndroid Build Coastguard Workerdefined by the POSIX standard, one for commands defined by the Linux Standard 152*cf5a6c84SAndroid Build Coastguard WorkerBase, an "other" directory for commands not covered by an obvious standard, 153*cf5a6c84SAndroid Build Coastguard Workera directory of example commands (templates to use when starting new commands), 154*cf5a6c84SAndroid Build Coastguard Workerand a "pending" directory of commands that need further review/cleanup 155*cf5a6c84SAndroid Build Coastguard Workerbefore moving to one of the other directories (run these at your own risk, 156*cf5a6c84SAndroid Build Coastguard Workercleanup patches welcome). 157*cf5a6c84SAndroid Build Coastguard WorkerThese directories are just for developer convenience sorting the commands, 158*cf5a6c84SAndroid Build Coastguard Workerthe directories are otherwise functionally identical. To add a new category, 159*cf5a6c84SAndroid Build Coastguard Workercreate the appropriate directory with a README file in it whose first line 160*cf5a6c84SAndroid Build Coastguard Workeris the description menuconfig should use for the directory.)</p> 161*cf5a6c84SAndroid Build Coastguard Worker 162*cf5a6c84SAndroid Build Coastguard Worker<p>An easy way to start a new command is copy the file "toys/example/hello.c" 163*cf5a6c84SAndroid Build Coastguard Workerto the name of the new command, and modify this copy to implement the new 164*cf5a6c84SAndroid Build Coastguard Workercommand (more or less by turning every instance of "hello" into the 165*cf5a6c84SAndroid Build Coastguard Workername of your command, updating the command line arguments, globals, and 166*cf5a6c84SAndroid Build Coastguard Workerhelp data, and then filling out its "main" function with code that does 167*cf5a6c84SAndroid Build Coastguard Workersomething interesting).</p> 168*cf5a6c84SAndroid Build Coastguard Worker 169*cf5a6c84SAndroid Build Coastguard Worker<p>You could also start with "toys/example/skeleton.c", which provides a lot 170*cf5a6c84SAndroid Build Coastguard Workermore example code (showing several variants of command line option 171*cf5a6c84SAndroid Build Coastguard Workerparsing, how to implement multiple commands in the same file, and so on). 172*cf5a6c84SAndroid Build Coastguard WorkerBut usually it's just more stuff to delete.</p> 173*cf5a6c84SAndroid Build Coastguard Worker 174*cf5a6c84SAndroid Build Coastguard Worker<p>Here's a checklist of steps to turn hello.c into another command:</p> 175*cf5a6c84SAndroid Build Coastguard Worker 176*cf5a6c84SAndroid Build Coastguard Worker<ul> 177*cf5a6c84SAndroid Build Coastguard Worker<li><p>First "cp toys/example/hello.c toys/other/yourcommand.c" and open 178*cf5a6c84SAndroid Build Coastguard Workerthe new file in your preferred text editor.</p> 179*cf5a6c84SAndroid Build Coastguard Worker<ul><li><p>Note that the 180*cf5a6c84SAndroid Build Coastguard Workername of the new file is significant: it's the name of the new command you're 181*cf5a6c84SAndroid Build Coastguard Workeradding to toybox. The build includes all *.c files under toys/*/ whose 182*cf5a6c84SAndroid Build Coastguard Workernames are a case insensitive match for an enabled config symbol. So 183*cf5a6c84SAndroid Build Coastguard Workertoys/posix/cat.c only gets included if you have "CAT=y" in ".config".</p></li> 184*cf5a6c84SAndroid Build Coastguard Worker</ul></p></li> 185*cf5a6c84SAndroid Build Coastguard Worker 186*cf5a6c84SAndroid Build Coastguard Worker<li><p>Change the one line comment at the top of the file (currently 187*cf5a6c84SAndroid Build Coastguard Worker"hello.c - A hello world program") to describe your new file.</p></li> 188*cf5a6c84SAndroid Build Coastguard Worker 189*cf5a6c84SAndroid Build Coastguard Worker<li><p>Change the copyright notice to your name, email, and the current 190*cf5a6c84SAndroid Build Coastguard Workeryear.</p></li> 191*cf5a6c84SAndroid Build Coastguard Worker 192*cf5a6c84SAndroid Build Coastguard Worker<li><p>Give a URL to the relevant standards document, where applicable. 193*cf5a6c84SAndroid Build Coastguard Worker(Sample links to SUSv4, LSB, IETF RFC, and man7.org are provided, feel free to 194*cf5a6c84SAndroid Build Coastguard Workerlink to other documentation or standards as appropriate.)</p></li> 195*cf5a6c84SAndroid Build Coastguard Worker 196*cf5a6c84SAndroid Build Coastguard Worker<li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. 197*cf5a6c84SAndroid Build Coastguard WorkerThe NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a> 198*cf5a6c84SAndroid Build Coastguard Workerstructure. The arguments to the NEWTOY macro are:</p> 199*cf5a6c84SAndroid Build Coastguard Worker 200*cf5a6c84SAndroid Build Coastguard Worker<ol> 201*cf5a6c84SAndroid Build Coastguard Worker<li><p>the name used to run your command</p></li> 202*cf5a6c84SAndroid Build Coastguard Worker<li><p>the command line argument <a href="#lib_args">option parsing string</a> (0 if none)</p></li> 203*cf5a6c84SAndroid Build Coastguard Worker<li><p>a bitfield of TOYFLAG values 204*cf5a6c84SAndroid Build Coastguard Worker(defined in toys.h) providing additional information such as where your 205*cf5a6c84SAndroid Build Coastguard Workercommand should be installed on a running system, whether to blank umask 206*cf5a6c84SAndroid Build Coastguard Workerbefore running, whether or not the command must run as root (and thus should 207*cf5a6c84SAndroid Build Coastguard Workerretain root access if installed SUID), and so on.</p></li> 208*cf5a6c84SAndroid Build Coastguard Worker</ol> 209*cf5a6c84SAndroid Build Coastguard Worker</li> 210*cf5a6c84SAndroid Build Coastguard Worker 211*cf5a6c84SAndroid Build Coastguard Worker<li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the 212*cf5a6c84SAndroid Build Coastguard Workercomment block) to supply your command's configuration and help 213*cf5a6c84SAndroid Build Coastguard Workerinformation. The uppper case config symbols are used by menuconfig, and are 214*cf5a6c84SAndroid Build Coastguard Workeralso what the CFG_ and USE_() macros are generated from (see [TODO]). The 215*cf5a6c84SAndroid Build Coastguard Workerhelp information here is used by menuconfig, and also by the "help" command to 216*cf5a6c84SAndroid Build Coastguard Workerdescribe your new command. (See [TODO] for details.) By convention, 217*cf5a6c84SAndroid Build Coastguard Workerunfinished commands default to "n" and finished commands default to "y", 218*cf5a6c84SAndroid Build Coastguard Workerso "make defconfig" selects all finished commands. (Note, "finished" means 219*cf5a6c84SAndroid Build Coastguard Worker"ready to be used", not that it'll never change again.)<p> 220*cf5a6c84SAndroid Build Coastguard Worker 221*cf5a6c84SAndroid Build Coastguard Worker<p>Each help block should start with a "usage: yourcommand" line explaining 222*cf5a6c84SAndroid Build Coastguard Workerany command line arguments added by this config option. The "help" command 223*cf5a6c84SAndroid Build Coastguard Workeroutputs this text, and scripts/config2help.c in the build infrastructure 224*cf5a6c84SAndroid Build Coastguard Workercollates these usage lines for commands with multiple configuration 225*cf5a6c84SAndroid Build Coastguard Workeroptions when producing generated/help.h.</p> 226*cf5a6c84SAndroid Build Coastguard Worker</li> 227*cf5a6c84SAndroid Build Coastguard Worker 228*cf5a6c84SAndroid Build Coastguard Worker<li><p>Change the "#define FOR_hello" line to "#define FOR_yourcommand" right 229*cf5a6c84SAndroid Build Coastguard Workerbefore the "#include <toys.h>". (This selects the appropriate FLAG_ macros and 230*cf5a6c84SAndroid Build Coastguard Workerdoes a "#define TT this.yourcommand" so you can access the global variables 231*cf5a6c84SAndroid Build Coastguard Workerout of the space-saving union of structures. If you aren't using any command 232*cf5a6c84SAndroid Build Coastguard Workerflag bits and aren't defining a GLOBAL block, you can delete this line.)</p></li> 233*cf5a6c84SAndroid Build Coastguard Worker 234*cf5a6c84SAndroid Build Coastguard Worker<li><p>Update the GLOBALS() macro to contain your command's global 235*cf5a6c84SAndroid Build Coastguard Workervariables. If your command has no global variables, delete this macro.</p> 236*cf5a6c84SAndroid Build Coastguard Worker 237*cf5a6c84SAndroid Build Coastguard Worker<p>Variables in the GLOBALS() block are are stored in a space saving 238*cf5a6c84SAndroid Build Coastguard Worker<a href="#toy_union">union of structures</a> format, which may be accessed 239*cf5a6c84SAndroid Build Coastguard Workerusing the TT macro as if TT were a global structure (so TT.membername). 240*cf5a6c84SAndroid Build Coastguard WorkerIf you specified two-character command line arguments in 241*cf5a6c84SAndroid Build Coastguard WorkerNEWTOY(), the first few global variables will be initialized by the automatic 242*cf5a6c84SAndroid Build Coastguard Workerargument parsing logic, and the type and order of these variables must 243*cf5a6c84SAndroid Build Coastguard Workercorrespond to the arguments specified in NEWTOY(). 244*cf5a6c84SAndroid Build Coastguard Worker(See <a href="#lib_args">lib/args.c</a> for details.)</p> 245*cf5a6c84SAndroid Build Coastguard Worker 246*cf5a6c84SAndroid Build Coastguard Worker<blockquote><p>NOTE: the GLOBALS() block creates a "this.filename" entry 247*cf5a6c84SAndroid Build Coastguard Workerin generated/globals.h. If your toys/*/filename.c does not match the first 248*cf5a6c84SAndroid Build Coastguard Workercommand name, you'll need to "#define TT this.filename" yourself before 249*cf5a6c84SAndroid Build Coastguard Worker#including toys.h if you want to use TT globals</p></blockquote> 250*cf5a6c84SAndroid Build Coastguard Worker</li> 251*cf5a6c84SAndroid Build Coastguard Worker 252*cf5a6c84SAndroid Build Coastguard Worker<li><p>Rename hello_main() to yourcommand_main(). This is the main() function 253*cf5a6c84SAndroid Build Coastguard Workerwhere execution of your command starts. Your command line options are 254*cf5a6c84SAndroid Build Coastguard Workeralready sorted into this.optflags, this.optargs, this.optc, and the GLOBALS() 255*cf5a6c84SAndroid Build Coastguard Workeras appropriate by the time this function is called. (See 256*cf5a6c84SAndroid Build Coastguard Worker<a href="#lib_args">get_optflags()</a> for details.)</p></li> 257*cf5a6c84SAndroid Build Coastguard Worker 258*cf5a6c84SAndroid Build Coastguard Worker<li><p>Switch on TOYBOX_DEBUG in menuconfig (toybox global settings menu) 259*cf5a6c84SAndroid Build Coastguard Workerthe first time you build and run your new command. If anything is wrong 260*cf5a6c84SAndroid Build Coastguard Workerwith your option string, that will give you error messages.</p> 261*cf5a6c84SAndroid Build Coastguard Worker 262*cf5a6c84SAndroid Build Coastguard Worker<p>Otherwise it'll just segfault without 263*cf5a6c84SAndroid Build Coastguard Workerexplanation when it falls off the end because it didn't find a matching 264*cf5a6c84SAndroid Build Coastguard Workerend parantheses for a longopt, or you put a nonexistent option in a square 265*cf5a6c84SAndroid Build Coastguard Workerbracket grouping... Since these kind of errors can only be caused by a 266*cf5a6c84SAndroid Build Coastguard Workerdeveloper, not by end users, we don't normally want runtime checks for 267*cf5a6c84SAndroid Build Coastguard Workerthem. Once you're happy with your option string, you can switch TOYBOX_DEBUG 268*cf5a6c84SAndroid Build Coastguard Workerback off.</p></li> 269*cf5a6c84SAndroid Build Coastguard Worker</ul> 270*cf5a6c84SAndroid Build Coastguard Worker 271*cf5a6c84SAndroid Build Coastguard Worker<a name="headers" /><h2><a href="#headers">Headers.</a></h2> 272*cf5a6c84SAndroid Build Coastguard Worker 273*cf5a6c84SAndroid Build Coastguard Worker<p>Commands are implemented as self-contained .c files, and generally don't 274*cf5a6c84SAndroid Build Coastguard Workerhave their own .h files. If it's common code put it in lib/, and if it's 275*cf5a6c84SAndroid Build Coastguard Workersomething like a local structure definition just put it in the command's .c 276*cf5a6c84SAndroid Build Coastguard Workerfile. If it would only ever be #included from one place, inline it. 277*cf5a6c84SAndroid Build Coastguard Worker(The line between implementing multiple commands in a C file via OLDTOY() 278*cf5a6c84SAndroid Build Coastguard Workerto share infrastructure and moving that shared infrastructure to lib/ is a 279*cf5a6c84SAndroid Build Coastguard Workerjudgement call. Try to figure out which is simplest.)</p> 280*cf5a6c84SAndroid Build Coastguard Worker 281*cf5a6c84SAndroid Build Coastguard Worker<p>The top level toys.h should #include all the standard (posix) headers 282*cf5a6c84SAndroid Build Coastguard Workerthat any command uses. (Partly this is friendly to ccache and partly this 283*cf5a6c84SAndroid Build Coastguard Workermakes the command implementations shorter.) Individual commands should only 284*cf5a6c84SAndroid Build Coastguard Workerneed to include nonstandard headers that might prevent that command from 285*cf5a6c84SAndroid Build Coastguard Workerbuilding in some context we'd care about (and thus requiring that command to 286*cf5a6c84SAndroid Build Coastguard Workerbe disabled to avoid a build break).</p> 287*cf5a6c84SAndroid Build Coastguard Worker 288*cf5a6c84SAndroid Build Coastguard Worker<p>Target-specific stuff (differences between compiler versions, libc versions, 289*cf5a6c84SAndroid Build Coastguard Workeror operating systems) should be confined to lib/portability.h and 290*cf5a6c84SAndroid Build Coastguard Workerlib/portability.c. (There's even some minimal compile-time environment probing 291*cf5a6c84SAndroid Build Coastguard Workerthat writes data to generated/portability.h, see scripts/genconfig.sh.)</p> 292*cf5a6c84SAndroid Build Coastguard Worker 293*cf5a6c84SAndroid Build Coastguard Worker<p>Only include <linux/*.h> headers from individual commands (not from other 294*cf5a6c84SAndroid Build Coastguard Workerheaders), and only if you really need to. Data that varies per architecture 295*cf5a6c84SAndroid Build Coastguard Workeris a good reason to include a header. If you just need a couple constants 296*cf5a6c84SAndroid Build Coastguard Workerthat haven't changed since the 1990's, it's ok to #define them yourself or 297*cf5a6c84SAndroid Build Coastguard Workerjust use the constant inline with a comment explaining what it is. (A 298*cf5a6c84SAndroid Build Coastguard Worker#define that's only used once isn't really helping.)</p> 299*cf5a6c84SAndroid Build Coastguard Worker 300*cf5a6c84SAndroid Build Coastguard Worker<p><a name="top" /><h1><a href="#top">Top level directory.</a></h1></p> 301*cf5a6c84SAndroid Build Coastguard Worker 302*cf5a6c84SAndroid Build Coastguard Worker<p>This directory contains global infrastructure.</p> 303*cf5a6c84SAndroid Build Coastguard Worker 304*cf5a6c84SAndroid Build Coastguard Worker<h3>toys.h</h3> 305*cf5a6c84SAndroid Build Coastguard Worker<p>Each command #includes "toys.h" as part of its standard prolog. It 306*cf5a6c84SAndroid Build Coastguard Workermay "#define FOR_commandname" before doing so to get some extra entries 307*cf5a6c84SAndroid Build Coastguard Workerspecific to this command.</p> 308*cf5a6c84SAndroid Build Coastguard Worker 309*cf5a6c84SAndroid Build Coastguard Worker<p>This file sucks in most of the commonly used standard #includes, so 310*cf5a6c84SAndroid Build Coastguard Workerindividual files can just #include "toys.h" and not have to worry about 311*cf5a6c84SAndroid Build Coastguard Workerstdargs.h and so on. Individual commands still need to #include 312*cf5a6c84SAndroid Build Coastguard Workerspecial-purpose headers that may not be present on all systems (and thus would 313*cf5a6c84SAndroid Build Coastguard Workerprevent toybox from building that command on such a system with that command 314*cf5a6c84SAndroid Build Coastguard Workerenabled). Examples include regex support, any "linux/" or "asm/" headers, mtab 315*cf5a6c84SAndroid Build Coastguard Workersupport (mntent.h and sys/mount.h), and so on.</p> 316*cf5a6c84SAndroid Build Coastguard Worker 317*cf5a6c84SAndroid Build Coastguard Worker<p>The toys.h header also defines structures for most of the global variables 318*cf5a6c84SAndroid Build Coastguard Workerprovided to each command by toybox_main(). These are described in 319*cf5a6c84SAndroid Build Coastguard Workerdetail in the description for main.c, where they are initialized.</p> 320*cf5a6c84SAndroid Build Coastguard Worker 321*cf5a6c84SAndroid Build Coastguard Worker<p>The global variables are grouped into structures (and a union) for space 322*cf5a6c84SAndroid Build Coastguard Workersavings, to more easily track the amount of memory consumed by them, 323*cf5a6c84SAndroid Build Coastguard Workerso that they may be automatically cleared/initialized as needed, and so 324*cf5a6c84SAndroid Build Coastguard Workerthat access to global variables is more easily distinguished from access to 325*cf5a6c84SAndroid Build Coastguard Workerlocal variables.</p> 326*cf5a6c84SAndroid Build Coastguard Worker 327*cf5a6c84SAndroid Build Coastguard Worker<h3>main.c</h3> 328*cf5a6c84SAndroid Build Coastguard Worker<p>Contains the main() function where execution starts, plus 329*cf5a6c84SAndroid Build Coastguard Workercommon infrastructure to initialize global variables and select which command 330*cf5a6c84SAndroid Build Coastguard Workerto run. The "toybox" multiplexer command also lives here. (This is the 331*cf5a6c84SAndroid Build Coastguard Workeronly command defined outside of the toys directory.)</p> 332*cf5a6c84SAndroid Build Coastguard Worker 333*cf5a6c84SAndroid Build Coastguard Worker<p>Execution starts in main() which trims any path off of the first command 334*cf5a6c84SAndroid Build Coastguard Workername and calls toybox_main(), which calls toy_exec(), which calls toy_find() 335*cf5a6c84SAndroid Build Coastguard Workerand toy_init() before calling the appropriate command's function from 336*cf5a6c84SAndroid Build Coastguard Workertoy_list[] (via toys.which->toy_main()). 337*cf5a6c84SAndroid Build Coastguard WorkerIf the command is "toybox", execution recurses into toybox_main(), otherwise 338*cf5a6c84SAndroid Build Coastguard Workerthe call goes to the appropriate commandname_main() from a C file in the toys 339*cf5a6c84SAndroid Build Coastguard Workerdirectory.</p> 340*cf5a6c84SAndroid Build Coastguard Worker 341*cf5a6c84SAndroid Build Coastguard Worker<p>The following global variables are defined in main.c:</p> 342*cf5a6c84SAndroid Build Coastguard Worker<ul> 343*cf5a6c84SAndroid Build Coastguard Worker<a name="toy_list" /> 344*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct toy_list toy_list[]</b> - array describing all the 345*cf5a6c84SAndroid Build Coastguard Workercommands currently configured into toybox. The first entry (toy_list[0]) is 346*cf5a6c84SAndroid Build Coastguard Workerfor the "toybox" multiplexer command, which runs all the other built-in commands 347*cf5a6c84SAndroid Build Coastguard Workerwithout symlinks by using its first argument as the name of the command to 348*cf5a6c84SAndroid Build Coastguard Workerrun and the rest as that command's argument list (ala "./toybox echo hello"). 349*cf5a6c84SAndroid Build Coastguard WorkerThe remaining entries are the commands in alphabetical order (for efficient 350*cf5a6c84SAndroid Build Coastguard Workerbinary search).</p> 351*cf5a6c84SAndroid Build Coastguard Worker 352*cf5a6c84SAndroid Build Coastguard Worker<p>This is a read-only array initialized at compile time by 353*cf5a6c84SAndroid Build Coastguard Workerdefining macros and #including generated/newtoys.h.</p> 354*cf5a6c84SAndroid Build Coastguard Worker 355*cf5a6c84SAndroid Build Coastguard Worker<p>Members of struct toy_list (defined in "toys.h") include:</p> 356*cf5a6c84SAndroid Build Coastguard Worker<ul> 357*cf5a6c84SAndroid Build Coastguard Worker<li><p>char *<b>name</b> - the name of this command.</p></li> 358*cf5a6c84SAndroid Build Coastguard Worker<li><p>void (*<b>toy_main</b>)(void) - function pointer to run this 359*cf5a6c84SAndroid Build Coastguard Workercommand.</p></li> 360*cf5a6c84SAndroid Build Coastguard Worker<li><p>char *<b>options</b> - command line option string (used by 361*cf5a6c84SAndroid Build Coastguard Workerget_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and 362*cf5a6c84SAndroid Build Coastguard Workerentries in the toy's GLOBALS struct). When this is NULL, no option 363*cf5a6c84SAndroid Build Coastguard Workerparsing is done before calling toy_main().</p></li> 364*cf5a6c84SAndroid Build Coastguard Worker<li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p> 365*cf5a6c84SAndroid Build Coastguard Worker 366*cf5a6c84SAndroid Build Coastguard Worker<ul> 367*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_USR</b> - Install this command under /usr</li> 368*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_BIN</b> - Install this command under /bin</li> 369*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li> 370*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li> 371*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li> 372*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li> 373*cf5a6c84SAndroid Build Coastguard Worker<li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li> 374*cf5a6c84SAndroid Build Coastguard Worker</ul> 375*cf5a6c84SAndroid Build Coastguard Worker<br> 376*cf5a6c84SAndroid Build Coastguard Worker 377*cf5a6c84SAndroid Build Coastguard Worker<p>These flags are combined with | (or). For example, to install a command 378*cf5a6c84SAndroid Build Coastguard Workerin /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p> 379*cf5a6c84SAndroid Build Coastguard Worker</ul> 380*cf5a6c84SAndroid Build Coastguard Worker</li> 381*cf5a6c84SAndroid Build Coastguard Worker 382*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct toy_context toys</b> - global structure containing information 383*cf5a6c84SAndroid Build Coastguard Workercommon to all commands, initializd by toy_init() and defined in "toys.h". 384*cf5a6c84SAndroid Build Coastguard WorkerMembers of this structure include:</p> 385*cf5a6c84SAndroid Build Coastguard Worker<ul> 386*cf5a6c84SAndroid Build Coastguard Worker<li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list 387*cf5a6c84SAndroid Build Coastguard Workerstructure. Mostly used to grab the name of the running command 388*cf5a6c84SAndroid Build Coastguard Worker(toys->which.name).</p> 389*cf5a6c84SAndroid Build Coastguard Worker</li> 390*cf5a6c84SAndroid Build Coastguard Worker<li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The 391*cf5a6c84SAndroid Build Coastguard Workererror_exit() functions will return 1 if this is zero, otherwise they'll 392*cf5a6c84SAndroid Build Coastguard Workerreturn this value.</p></li> 393*cf5a6c84SAndroid Build Coastguard Worker<li><p>char **<b>argv</b> - "raw" command line options, I.E. the original 394*cf5a6c84SAndroid Build Coastguard Workerunmodified string array passed in to main(). Note that modifying this changes 395*cf5a6c84SAndroid Build Coastguard Worker"ps" output, and is not recommended. This array is null terminated; a NULL 396*cf5a6c84SAndroid Build Coastguard Workerentry indicates the end of the array.</p> 397*cf5a6c84SAndroid Build Coastguard Worker<p>Most commands don't use this field, instead the use optargs, optflags, 398*cf5a6c84SAndroid Build Coastguard Workerand the fields in the GLOBALS struct initialized by get_optflags().</p> 399*cf5a6c84SAndroid Build Coastguard Worker</li> 400*cf5a6c84SAndroid Build Coastguard Worker<li><p>unsigned <b>optflags</b> - Command line option flags, set by 401*cf5a6c84SAndroid Build Coastguard Worker<a href="#lib_args">get_optflags()</a>. Indicates which of the command line options listed in 402*cf5a6c84SAndroid Build Coastguard Workertoys->which.options occurred this time.</p> 403*cf5a6c84SAndroid Build Coastguard Worker 404*cf5a6c84SAndroid Build Coastguard Worker<p>The rightmost command line argument listed in toys->which.options sets bit 405*cf5a6c84SAndroid Build Coastguard Worker1, the next one sets bit 2, and so on. This means the bits are set in the same 406*cf5a6c84SAndroid Build Coastguard Workerorder the binary digits would be listed if typed out as a string. For example, 407*cf5a6c84SAndroid Build Coastguard Workerthe option string "abcd" would parse the command line "-c" to set optflags to 2, 408*cf5a6c84SAndroid Build Coastguard Worker"-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p> 409*cf5a6c84SAndroid Build Coastguard Worker 410*cf5a6c84SAndroid Build Coastguard Worker<p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2, 411*cf5a6c84SAndroid Build Coastguard Workerb=4, a=8. Punctuation after a letter initializes global variables at the 412*cf5a6c84SAndroid Build Coastguard Workerstart of the GLOBALS() block (see <a href="#toy_union">union toy_union this</a> 413*cf5a6c84SAndroid Build Coastguard Workerfor details).</p> 414*cf5a6c84SAndroid Build Coastguard Worker 415*cf5a6c84SAndroid Build Coastguard Worker<p>The build infrastructure creates FLAG_ macros for each option letter, 416*cf5a6c84SAndroid Build Coastguard Workercorresponding to the bit position, so you can check (toys.optflags & FLAG_x) 417*cf5a6c84SAndroid Build Coastguard Workerto see if a flag was specified. (The correct set of FLAG_ macros is selected 418*cf5a6c84SAndroid Build Coastguard Workerby defining FOR_mycommand before #including toys.h. The macros live in 419*cf5a6c84SAndroid Build Coastguard Workertoys/globals.h which is generated by scripts/make.sh.)</p> 420*cf5a6c84SAndroid Build Coastguard Worker 421*cf5a6c84SAndroid Build Coastguard Worker<p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p> 422*cf5a6c84SAndroid Build Coastguard Worker 423*cf5a6c84SAndroid Build Coastguard Worker</li> 424*cf5a6c84SAndroid Build Coastguard Worker<li><p>char **<b>optargs</b> - Null terminated array of arguments left over 425*cf5a6c84SAndroid Build Coastguard Workerafter get_optflags() removed all the ones it understood. Note: optarg[0] is 426*cf5a6c84SAndroid Build Coastguard Workerthe first argument, not the command name. Use toys.which->name for the command 427*cf5a6c84SAndroid Build Coastguard Workername.</p></li> 428*cf5a6c84SAndroid Build Coastguard Worker<li><p>int <b>optc</b> - Optarg count, equivalent to argc but for 429*cf5a6c84SAndroid Build Coastguard Workeroptargs[].<p></li> 430*cf5a6c84SAndroid Build Coastguard Worker</ul> 431*cf5a6c84SAndroid Build Coastguard Worker 432*cf5a6c84SAndroid Build Coastguard Worker<a name="toy_union" /> 433*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>union toy_union this</b> - Union of structures containing each 434*cf5a6c84SAndroid Build Coastguard Workercommand's global variables.</p> 435*cf5a6c84SAndroid Build Coastguard Worker 436*cf5a6c84SAndroid Build Coastguard Worker<p>Global variables are useful: they reduce the overhead of passing extra 437*cf5a6c84SAndroid Build Coastguard Workercommand line arguments between functions, they conveniently start prezeroed to 438*cf5a6c84SAndroid Build Coastguard Workersave initialization costs, and the command line argument parsing infrastructure 439*cf5a6c84SAndroid Build Coastguard Workercan also initialize global variables with its results.</p> 440*cf5a6c84SAndroid Build Coastguard Worker 441*cf5a6c84SAndroid Build Coastguard Worker<p>But since each toybox process can only run one command at a time, allocating 442*cf5a6c84SAndroid Build Coastguard Workerspace for global variables belonging to other commands you aren't currently 443*cf5a6c84SAndroid Build Coastguard Workerrunning would be wasteful.</p> 444*cf5a6c84SAndroid Build Coastguard Worker 445*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox handles this by encapsulating each command's global variables in 446*cf5a6c84SAndroid Build Coastguard Workera structure, and declaring a union of those structures with a single global 447*cf5a6c84SAndroid Build Coastguard Workerinstance (called "this"). The GLOBALS() macro contains the global 448*cf5a6c84SAndroid Build Coastguard Workervariables that should go in the current command's global structure. Each 449*cf5a6c84SAndroid Build Coastguard Workervariable can then be accessed as "this.commandname.varname". 450*cf5a6c84SAndroid Build Coastguard WorkerIf you #defined FOR_commandname before including toys.h, the macro TT is 451*cf5a6c84SAndroid Build Coastguard Worker#defined to this.commandname so the variable can then be accessed as 452*cf5a6c84SAndroid Build Coastguard Worker"TT.variable". See toys/hello.c for an example.</p> 453*cf5a6c84SAndroid Build Coastguard Worker 454*cf5a6c84SAndroid Build Coastguard Worker<p>A command that needs global variables should declare a structure to 455*cf5a6c84SAndroid Build Coastguard Workercontain them all, and add that structure to this union. A command should never 456*cf5a6c84SAndroid Build Coastguard Workerdeclare global variables outside of this, because such global variables would 457*cf5a6c84SAndroid Build Coastguard Workerallocate memory when running other commands that don't use those global 458*cf5a6c84SAndroid Build Coastguard Workervariables.</p> 459*cf5a6c84SAndroid Build Coastguard Worker 460*cf5a6c84SAndroid Build Coastguard Worker<p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>, 461*cf5a6c84SAndroid Build Coastguard Workeras specified by the options field off this command's toy_list entry. See 462*cf5a6c84SAndroid Build Coastguard Workerthe get_optargs() description in lib/args.c for details.</p> 463*cf5a6c84SAndroid Build Coastguard Worker</li> 464*cf5a6c84SAndroid Build Coastguard Worker 465*cf5a6c84SAndroid Build Coastguard Worker<li><b>char toybuf[4096]</b> - a common scratch space buffer guaranteed 466*cf5a6c84SAndroid Build Coastguard Workerto start zeroed, so commands don't need to allocate/initialize their own. 467*cf5a6c84SAndroid Build Coastguard WorkerAny command is free to use this, and it should never be directly referenced 468*cf5a6c84SAndroid Build Coastguard Workerby functions in lib/ (although commands are free to pass toybuf in to a 469*cf5a6c84SAndroid Build Coastguard Workerlibrary function as an argument).</li> 470*cf5a6c84SAndroid Build Coastguard Worker 471*cf5a6c84SAndroid Build Coastguard Worker<li><b>char libbuf[4096]</b> - like toybuf, but for use by common code in 472*cf5a6c84SAndroid Build Coastguard Workerlib/*.c. Commands should never directly reference libbuf, and library 473*cf5a6c84SAndroid Build Coastguard Workercould should nnever directly reference toybuf.</li> 474*cf5a6c84SAndroid Build Coastguard Worker</ul> 475*cf5a6c84SAndroid Build Coastguard Worker 476*cf5a6c84SAndroid Build Coastguard Worker<p>The following functions are defined in main.c:</p> 477*cf5a6c84SAndroid Build Coastguard Worker<ul> 478*cf5a6c84SAndroid Build Coastguard Worker<li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list 479*cf5a6c84SAndroid Build Coastguard Workerstructure for this command name, or NULL if not found.</p></li> 480*cf5a6c84SAndroid Build Coastguard Worker<li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out 481*cf5a6c84SAndroid Build Coastguard Workerthe global toys structure, calling get_optargs() if necessary.</p></li> 482*cf5a6c84SAndroid Build Coastguard Worker<li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with 483*cf5a6c84SAndroid Build Coastguard Workerarguments.</p> 484*cf5a6c84SAndroid Build Coastguard Worker<p>Calls toy_find() on argv[0] (which must be just a command name 485*cf5a6c84SAndroid Build Coastguard Workerwithout path). Returns if it can't find this command, otherwise calls 486*cf5a6c84SAndroid Build Coastguard Workertoy_init(), toys->which.toy_main(), and exit() instead of returning.</p> 487*cf5a6c84SAndroid Build Coastguard Worker 488*cf5a6c84SAndroid Build Coastguard Worker<p>Use the library function xexec() to fall back to external executables 489*cf5a6c84SAndroid Build Coastguard Workerin $PATH if toy_exec() can't find a built-in command. Note that toy_exec() 490*cf5a6c84SAndroid Build Coastguard Workerdoes not strip paths before searching for a command, so "./command" will 491*cf5a6c84SAndroid Build Coastguard Workernever match an internal command.</li> 492*cf5a6c84SAndroid Build Coastguard Worker 493*cf5a6c84SAndroid Build Coastguard Worker<li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer 494*cf5a6c84SAndroid Build Coastguard Workercommand (I.E. "toybox"). Given a command name as its first argument, calls 495*cf5a6c84SAndroid Build Coastguard Workertoy_exec() on its arguments. With no arguments, it lists available commands. 496*cf5a6c84SAndroid Build Coastguard WorkerIf the first argument starts with "-" it lists each command with its default 497*cf5a6c84SAndroid Build Coastguard Workerinstall path prepended.</p></li> 498*cf5a6c84SAndroid Build Coastguard Worker 499*cf5a6c84SAndroid Build Coastguard Worker</ul> 500*cf5a6c84SAndroid Build Coastguard Worker 501*cf5a6c84SAndroid Build Coastguard Worker<h3>Config.in</h3> 502*cf5a6c84SAndroid Build Coastguard Worker 503*cf5a6c84SAndroid Build Coastguard Worker<p>Top level configuration file in a stylized variant of 504*cf5a6c84SAndroid Build Coastguard Worker<a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p> 505*cf5a6c84SAndroid Build Coastguard Worker 506*cf5a6c84SAndroid Build Coastguard Worker<p>These files are directly used by "make menuconfig" to select which commands 507*cf5a6c84SAndroid Build Coastguard Workerto build into toybox (thus generating a .config file), and by 508*cf5a6c84SAndroid Build Coastguard Workerscripts/config2help.py to create generated/help.h.</p> 509*cf5a6c84SAndroid Build Coastguard Worker 510*cf5a6c84SAndroid Build Coastguard Worker<a name="generated" /> 511*cf5a6c84SAndroid Build Coastguard Worker<h1><a href="#generated">Temporary files:</a></h1> 512*cf5a6c84SAndroid Build Coastguard Worker 513*cf5a6c84SAndroid Build Coastguard Worker<p>There is one temporary file in the top level source directory:</p> 514*cf5a6c84SAndroid Build Coastguard Worker<ul> 515*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>.config</b> - Configuration file generated by kconfig, indicating 516*cf5a6c84SAndroid Build Coastguard Workerwhich commands (and options to commands) are currently enabled. Used 517*cf5a6c84SAndroid Build Coastguard Workerto make generated/config.h and determine which toys/*/*.c files to build.</p> 518*cf5a6c84SAndroid Build Coastguard Worker 519*cf5a6c84SAndroid Build Coastguard Worker<p>You can create a human readable "miniconfig" version of this file using 520*cf5a6c84SAndroid Build Coastguard Worker<a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these 521*cf5a6c84SAndroid Build Coastguard Workerinstructions</a>.</p> 522*cf5a6c84SAndroid Build Coastguard Worker</li> 523*cf5a6c84SAndroid Build Coastguard Worker</ul> 524*cf5a6c84SAndroid Build Coastguard Worker 525*cf5a6c84SAndroid Build Coastguard Worker<p><h2>Directory generated/</h2></p> 526*cf5a6c84SAndroid Build Coastguard Worker 527*cf5a6c84SAndroid Build Coastguard Worker<p>The remaining temporary files live in the "generated/" directory, 528*cf5a6c84SAndroid Build Coastguard Workerwhich is for files generated at build time from other source files.</p> 529*cf5a6c84SAndroid Build Coastguard Worker 530*cf5a6c84SAndroid Build Coastguard Worker<ul> 531*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>generated/Config.in</b> - Kconfig entries for each command, included 532*cf5a6c84SAndroid Build Coastguard Workerfrom the top level Config.in. The help text here is used to generate 533*cf5a6c84SAndroid Build Coastguard Workerhelp.h.</p> 534*cf5a6c84SAndroid Build Coastguard Worker 535*cf5a6c84SAndroid Build Coastguard Worker<p>Each command has a configuration entry with an upper case version of 536*cf5a6c84SAndroid Build Coastguard Workerthe command name. Options to commands start with the command 537*cf5a6c84SAndroid Build Coastguard Workername followed by an underscore and the option name. Global options are attached 538*cf5a6c84SAndroid Build Coastguard Workerto the "toybox" command, and thus use the prefix "TOYBOX_". This organization 539*cf5a6c84SAndroid Build Coastguard Workeris used by scripts/cfg2files to select which toys/*/*.c files to compile for a 540*cf5a6c84SAndroid Build Coastguard Workergiven .config.</p> 541*cf5a6c84SAndroid Build Coastguard Worker</li> 542*cf5a6c84SAndroid Build Coastguard Worker 543*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros, 544*cf5a6c84SAndroid Build Coastguard Workergenerated from .config by a sed invocation in scripts/make.sh.</p> 545*cf5a6c84SAndroid Build Coastguard Worker 546*cf5a6c84SAndroid Build Coastguard Worker<p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for 547*cf5a6c84SAndroid Build Coastguard Workerdisabled symbols. This allows the use of normal if() statements to remove 548*cf5a6c84SAndroid Build Coastguard Workercode at compile time via the optimizer's dead code elimination (which removes 549*cf5a6c84SAndroid Build Coastguard Workerfrom the binary any code that cannot be reached). This saves space without 550*cf5a6c84SAndroid Build Coastguard Workercluttering the code with #ifdefs or leading to configuration dependent build 551*cf5a6c84SAndroid Build Coastguard Workerbreaks. (See the 1992 Usenix paper 552*cf5a6c84SAndroid Build Coastguard Worker<a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef 553*cf5a6c84SAndroid Build Coastguard WorkerConsidered Harmful</a> for more information.)</p> 554*cf5a6c84SAndroid Build Coastguard Worker 555*cf5a6c84SAndroid Build Coastguard Worker<p>When you can't entirely avoid an #ifdef, the USE_SYMBOL(code) macro 556*cf5a6c84SAndroid Build Coastguard Workerprovides a less intrusive alternative, evaluating to the code in parentheses 557*cf5a6c84SAndroid Build Coastguard Workerwhen the symbol is enabled, and nothing when the symbol is disabled. This 558*cf5a6c84SAndroid Build Coastguard Workeris most commonly used around NEWTOY() declarations (so only the enabled 559*cf5a6c84SAndroid Build Coastguard Workercommands show up in toy_list), and in option strings. This can also be used 560*cf5a6c84SAndroid Build Coastguard Workerfor things like varargs or structure members which can't always be 561*cf5a6c84SAndroid Build Coastguard Workereliminated by a simple test on CFG_SYMBOL. Remember, unlike CFG_SYMBOL 562*cf5a6c84SAndroid Build Coastguard Workerthis is really just a variant of #ifdef, and can still result in configuration 563*cf5a6c84SAndroid Build Coastguard Workerdependent build breaks. Use with caution.</p> 564*cf5a6c84SAndroid Build Coastguard Worker</li> 565*cf5a6c84SAndroid Build Coastguard Worker 566*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>generated/flags.h</b> - FLAG_? macros indicating which command 567*cf5a6c84SAndroid Build Coastguard Workerline options were seen. The option parsing in lib/args.c sets bits in 568*cf5a6c84SAndroid Build Coastguard Workertoys.optflags, which can be tested by anding with the appropriate FLAG_ 569*cf5a6c84SAndroid Build Coastguard Workermacro. (Bare longopts, which have no corresponding short option, will 570*cf5a6c84SAndroid Build Coastguard Workerhave the longopt name after FLAG_. All others use the single letter short 571*cf5a6c84SAndroid Build Coastguard Workeroption.)</p> 572*cf5a6c84SAndroid Build Coastguard Worker 573*cf5a6c84SAndroid Build Coastguard Worker<p>To get the appropriate macros for your command, #define FOR_commandname 574*cf5a6c84SAndroid Build Coastguard Workerbefore #including toys.h. To switch macro sets (because you have an OLDTOY() 575*cf5a6c84SAndroid Build Coastguard Workerwith different options in the same .c file), #define CLEANUP_oldcommand 576*cf5a6c84SAndroid Build Coastguard Workerand also #define FOR_newcommand, then #include "generated/flags.h" to switch. 577*cf5a6c84SAndroid Build Coastguard Worker</p> 578*cf5a6c84SAndroid Build Coastguard Worker</li> 579*cf5a6c84SAndroid Build Coastguard Worker 580*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>generated/globals.h</b> - 581*cf5a6c84SAndroid Build Coastguard WorkerDeclares structures to hold the contents of each command's GLOBALS(), 582*cf5a6c84SAndroid Build Coastguard Workerand combines them into "global_union this". (Yes, the name was 583*cf5a6c84SAndroid Build Coastguard Workerchosen to piss off C++ developers who think that C 584*cf5a6c84SAndroid Build Coastguard Workeris merely a subset of C++, not a language in its own right.)</p> 585*cf5a6c84SAndroid Build Coastguard Worker 586*cf5a6c84SAndroid Build Coastguard Worker<p>The union reuses the same memory for each command's global struct: 587*cf5a6c84SAndroid Build Coastguard Workersince only one command's globals are in use at any given time, collapsing 588*cf5a6c84SAndroid Build Coastguard Workerthem together saves space. The headers #define TT to the appropriate 589*cf5a6c84SAndroid Build Coastguard Worker"this.commandname", so you can refer to the current command's global 590*cf5a6c84SAndroid Build Coastguard Workervariables out of "this" as TT.variablename.</p> 591*cf5a6c84SAndroid Build Coastguard Worker 592*cf5a6c84SAndroid Build Coastguard Worker<p>The globals start zeroed, and the first few are filled out by the 593*cf5a6c84SAndroid Build Coastguard Workerlib/args.c argument parsing code called from main.c.</p> 594*cf5a6c84SAndroid Build Coastguard Worker</li> 595*cf5a6c84SAndroid Build Coastguard Worker 596*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>toys/help.h</b> - Help strings for use by the "help" command and 597*cf5a6c84SAndroid Build Coastguard Worker--help options. This file #defines a help_symbolname string for each 598*cf5a6c84SAndroid Build Coastguard Workersymbolname, but only the symbolnames matching command names get used 599*cf5a6c84SAndroid Build Coastguard Workerby show_help() in lib/help.c to display help for commands.</p> 600*cf5a6c84SAndroid Build Coastguard Worker 601*cf5a6c84SAndroid Build Coastguard Worker<p>This file is created by scripts/make.sh, which compiles scripts/config2help.c 602*cf5a6c84SAndroid Build Coastguard Workerinto the binary generated/config2help, and then runs it against the top 603*cf5a6c84SAndroid Build Coastguard Workerlevel .config and Config.in files to extract the help text from each config 604*cf5a6c84SAndroid Build Coastguard Workerentry and collate together dependent options.</p> 605*cf5a6c84SAndroid Build Coastguard Worker 606*cf5a6c84SAndroid Build Coastguard Worker<p>This file contains help text for all commands, regardless of current 607*cf5a6c84SAndroid Build Coastguard Workerconfiguration, but only the ones currently enabled in the .config file 608*cf5a6c84SAndroid Build Coastguard Workerwind up in the help_data[] array, and only the enabled dependent options 609*cf5a6c84SAndroid Build Coastguard Workerhave their help text added to the command they depend on.</p> 610*cf5a6c84SAndroid Build Coastguard Worker</li> 611*cf5a6c84SAndroid Build Coastguard Worker 612*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>generated/newtoys.h</b> - 613*cf5a6c84SAndroid Build Coastguard WorkerAll the NEWTOY() and OLDTOY() macros from toys/*/*.c. The "toybox" multiplexer 614*cf5a6c84SAndroid Build Coastguard Workeris the first entry, the rest are in alphabetical order. Each line should be 615*cf5a6c84SAndroid Build Coastguard Workerinside an appropriate USE_ macro, so code that #includes this file only sees 616*cf5a6c84SAndroid Build Coastguard Workerthe currently enabled commands.</p> 617*cf5a6c84SAndroid Build Coastguard Worker 618*cf5a6c84SAndroid Build Coastguard Worker<p>By #definining NEWTOY() to various things before #including this file, 619*cf5a6c84SAndroid Build Coastguard Workerit may be used to create function prototypes (in toys.h), initialize the 620*cf5a6c84SAndroid Build Coastguard Workerhelp_data array (in lib/help.c), initialize the toy_list array (in main.c, 621*cf5a6c84SAndroid Build Coastguard Workerthe alphabetical order lets toy_find() do a binary search, the exception to 622*cf5a6c84SAndroid Build Coastguard Workerthe alphabetical order lets it use the multiplexer without searching), and so 623*cf5a6c84SAndroid Build Coastguard Workeron. (It's even used to initialize the NEED_OPTIONS macro, which produces a 1 624*cf5a6c84SAndroid Build Coastguard Workeror 0 for each command using command line option parsing, which is ORed together 625*cf5a6c84SAndroid Build Coastguard Workerto allow compile-time dead code elimination to remove the whole of 626*cf5a6c84SAndroid Build Coastguard Workerlib/args.c if nothing currently enabled is using it.)<p> 627*cf5a6c84SAndroid Build Coastguard Worker 628*cf5a6c84SAndroid Build Coastguard Worker<p>Each NEWTOY and OLDTOY macro contains the command name, command line 629*cf5a6c84SAndroid Build Coastguard Workeroption string (telling lib/args.c how to parse command line options for 630*cf5a6c84SAndroid Build Coastguard Workerthis command), recommended install location, and miscelaneous data such 631*cf5a6c84SAndroid Build Coastguard Workeras whether this command should retain root permissions if installed suid.</p> 632*cf5a6c84SAndroid Build Coastguard Worker</li> 633*cf5a6c84SAndroid Build Coastguard Worker 634*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>toys/oldtoys.h</b> - Macros with the command line option parsing 635*cf5a6c84SAndroid Build Coastguard Workerstring for each NEWTOY. This allows an OLDTOY that's just an alias for an 636*cf5a6c84SAndroid Build Coastguard Workerexisting command to refer to the existing option string instead of 637*cf5a6c84SAndroid Build Coastguard Workerhaving to repeat it.</p> 638*cf5a6c84SAndroid Build Coastguard Worker</li> 639*cf5a6c84SAndroid Build Coastguard Worker</ul> 640*cf5a6c84SAndroid Build Coastguard Worker 641*cf5a6c84SAndroid Build Coastguard Worker<a name="lib"> 642*cf5a6c84SAndroid Build Coastguard Worker<h2>Directory lib/</h2> 643*cf5a6c84SAndroid Build Coastguard Worker 644*cf5a6c84SAndroid Build Coastguard Worker<p>TODO: document lots more here.</p> 645*cf5a6c84SAndroid Build Coastguard Worker 646*cf5a6c84SAndroid Build Coastguard Worker<p>lib: getmountlist(), error_msg/error_exit, xmalloc(), 647*cf5a6c84SAndroid Build Coastguard Workerstrlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(), 648*cf5a6c84SAndroid Build Coastguard Workeritoa().</p> 649*cf5a6c84SAndroid Build Coastguard Worker 650*cf5a6c84SAndroid Build Coastguard Worker 651*cf5a6c84SAndroid Build Coastguard Worker 652*cf5a6c84SAndroid Build Coastguard Worker<a name="lib_xwrap"><h3>lib/xwrap.c</h3> 653*cf5a6c84SAndroid Build Coastguard Worker 654*cf5a6c84SAndroid Build Coastguard Worker<p>Functions prefixed with the letter x call perror_exit() when they hit 655*cf5a6c84SAndroid Build Coastguard Workererrors, to eliminate common error checking. This prints an error message 656*cf5a6c84SAndroid Build Coastguard Workerand the strerror() string for the errno encountered.</p> 657*cf5a6c84SAndroid Build Coastguard Worker 658*cf5a6c84SAndroid Build Coastguard Worker<p>We replaced exit(), _exit(), and atexit() with xexit(), _xexit(), and 659*cf5a6c84SAndroid Build Coastguard Workersigatexit(). This gives _xexit() the option to siglongjmp(toys.rebound, 1) 660*cf5a6c84SAndroid Build Coastguard Workerinstead of exiting, lets xexit() report stdout flush failures to stderr 661*cf5a6c84SAndroid Build Coastguard Workerand change the exit code to indicate error, lets our toys.exit function 662*cf5a6c84SAndroid Build Coastguard Workerchange happen for signal exit paths and lets us remove the functions 663*cf5a6c84SAndroid Build Coastguard Workerafter we've called them.</p> 664*cf5a6c84SAndroid Build Coastguard Worker 665*cf5a6c84SAndroid Build Coastguard Worker<p>You can intercept our exit by assigning a sigsetjmp/siglongjmp buffer to 666*cf5a6c84SAndroid Build Coastguard Workertoys.rebound (set it back to zero to restore the default behavior). 667*cf5a6c84SAndroid Build Coastguard WorkerIf you do this, cleaning up resource leaks is your problem.</p> 668*cf5a6c84SAndroid Build Coastguard Worker 669*cf5a6c84SAndroid Build Coastguard Worker<ul> 670*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xstrncpy(char *dest, char *src, size_t size)</b></li> 671*cf5a6c84SAndroid Build Coastguard Worker<li><p><b><p>void _xexit(void)</b></p> 672*cf5a6c84SAndroid Build Coastguard Worker<p>Calls siglongjmp(toys.rebound, 1), or else _exit(toys.exitval). This 673*cf5a6c84SAndroid Build Coastguard Workerlets you ignore errors with the NO_EXIT() macro wrapper, or intercept 674*cf5a6c84SAndroid Build Coastguard Workerthem with WOULD_EXIT().</p> 675*cf5a6c84SAndroid Build Coastguard Worker<li><b><p>void xexit(void)</b></p> 676*cf5a6c84SAndroid Build Coastguard Worker<p>Calls toys.xexit functions (if any) and flushes stdout/stderr (reporting 677*cf5a6c84SAndroid Build Coastguard Workerfailure to write to stdout both to stderr and in the exit code), then 678*cf5a6c84SAndroid Build Coastguard Workercalls _xexit().</p> 679*cf5a6c84SAndroid Build Coastguard Worker</li> 680*cf5a6c84SAndroid Build Coastguard Worker<li><b>void *xmalloc(size_t size)</b></li> 681*cf5a6c84SAndroid Build Coastguard Worker<li><b>void *xzalloc(size_t size)</b></li> 682*cf5a6c84SAndroid Build Coastguard Worker<li><b>void *xrealloc(void *ptr, size_t size)</b></li> 683*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xstrndup(char *s, size_t n)</b></li> 684*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xstrdup(char *s)</b></li> 685*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xmprintf(char *format, ...)</b></li> 686*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xprintf(char *format, ...)</b></li> 687*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xputs(char *s)</b></li> 688*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xputc(char c)</b></li> 689*cf5a6c84SAndroid Build Coastguard Worker<li><b>pid_t xfork(void)</b></li> 690*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xexec_optargs(int skip)</b></li> 691*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xexec(char **argv)</b></li> 692*cf5a6c84SAndroid Build Coastguard Worker<li><b>pid_t xpopen(char **argv, int *pipes)</b></li> 693*cf5a6c84SAndroid Build Coastguard Worker<li><b>int xpclose(pid_t pid, int *pipes)</b></li> 694*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xaccess(char *path, int flags)</b></li> 695*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xunlink(char *path)</b></li> 696*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>int xcreate(char *path, int flags, int mode)<br /> 697*cf5a6c84SAndroid Build Coastguard Workerint xopen(char *path, int flags)</b></p> 698*cf5a6c84SAndroid Build Coastguard Worker 699*cf5a6c84SAndroid Build Coastguard Worker<p>The xopen() and xcreate() functions open an existing file (exiting if 700*cf5a6c84SAndroid Build Coastguard Workerit's not there) and create a new file (exiting if it can't).</p> 701*cf5a6c84SAndroid Build Coastguard Worker 702*cf5a6c84SAndroid Build Coastguard Worker<p>They default to O_CLOEXEC so the filehandles aren't passed on to child 703*cf5a6c84SAndroid Build Coastguard Workerprocesses. Feed in O_CLOEXEC to disable this.</p> 704*cf5a6c84SAndroid Build Coastguard Worker</li> 705*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>void xclose(int fd)</b></p> 706*cf5a6c84SAndroid Build Coastguard Worker 707*cf5a6c84SAndroid Build Coastguard Worker<p>Because NFS is broken, and won't necessarily perform the requested 708*cf5a6c84SAndroid Build Coastguard Workeroperation (and report the error) until you close the file. Of course, this 709*cf5a6c84SAndroid Build Coastguard Workerbeing NFS, it's not guaranteed to report the error there either, but it 710*cf5a6c84SAndroid Build Coastguard Worker_can_.</p> 711*cf5a6c84SAndroid Build Coastguard Worker 712*cf5a6c84SAndroid Build Coastguard Worker<p>Nothing else ever reports an error on close, everywhere else it's just a 713*cf5a6c84SAndroid Build Coastguard WorkerVFS operation freeing some resources. NFS is _special_, in a way that 714*cf5a6c84SAndroid Build Coastguard Workerother network filesystems like smbfs and v9fs aren't..</p> 715*cf5a6c84SAndroid Build Coastguard Worker</li> 716*cf5a6c84SAndroid Build Coastguard Worker<li><b>int xdup(int fd)</b></li> 717*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>size_t xread(int fd, void *buf, size_t len)</b></p> 718*cf5a6c84SAndroid Build Coastguard Worker 719*cf5a6c84SAndroid Build Coastguard Worker<p>Can return 0, but not -1.</p> 720*cf5a6c84SAndroid Build Coastguard Worker</li> 721*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>void xreadall(int fd, void *buf, size_t len)</b></p> 722*cf5a6c84SAndroid Build Coastguard Worker 723*cf5a6c84SAndroid Build Coastguard Worker<p>Reads the entire len-sized buffer, retrying to complete short 724*cf5a6c84SAndroid Build Coastguard Workerreads. Exits if it can't get enough data.</p></li> 725*cf5a6c84SAndroid Build Coastguard Worker 726*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>void xwrite(int fd, void *buf, size_t len)</b></p> 727*cf5a6c84SAndroid Build Coastguard Worker 728*cf5a6c84SAndroid Build Coastguard Worker<p>Retries short writes, exits if can't write the entire buffer.</p></li> 729*cf5a6c84SAndroid Build Coastguard Worker 730*cf5a6c84SAndroid Build Coastguard Worker<li><b>off_t xlseek(int fd, off_t offset, int whence)</b></li> 731*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xgetcwd(void)</b></li> 732*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xstat(char *path, struct stat *st)</b></li> 733*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>char *xabspath(char *path, int exact) </b></p> 734*cf5a6c84SAndroid Build Coastguard Worker 735*cf5a6c84SAndroid Build Coastguard Worker<p>After several years of 736*cf5a6c84SAndroid Build Coastguard Worker<a href=http://landley.net/notes-2007.html#18-06-2007>wrestling</a> 737*cf5a6c84SAndroid Build Coastguard Worker<a href=http://landley.net/notes-2008.html#19-01-2008>with</a> realpath(), 738*cf5a6c84SAndroid Build Coastguard WorkerI broke down and <a href=http://landley.net/notes-2012.html#20-11-2012>wrote 739*cf5a6c84SAndroid Build Coastguard Workermy own</a> implementation that doesn't use the one in libc. As I explained: 740*cf5a6c84SAndroid Build Coastguard Worker 741*cf5a6c84SAndroid Build Coastguard Worker<blockquote><p>If the path ends with a broken link, 742*cf5a6c84SAndroid Build Coastguard Workerreadlink -f should show where the link points to, not where the broken link 743*cf5a6c84SAndroid Build Coastguard Workerlives. (The point of readlink -f is "if I write here, where would it attempt 744*cf5a6c84SAndroid Build Coastguard Workerto create a file".) The problem is, realpath() returns NULL for a path ending 745*cf5a6c84SAndroid Build Coastguard Workerwith a broken link, and I can't beat different behavior out of code locked 746*cf5a6c84SAndroid Build Coastguard Workeraway in libc.</p></blockquote> 747*cf5a6c84SAndroid Build Coastguard Worker 748*cf5a6c84SAndroid Build Coastguard Worker<p> 749*cf5a6c84SAndroid Build Coastguard Worker</li> 750*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xchdir(char *path)</b></li> 751*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xchroot(char *path)</b></li> 752*cf5a6c84SAndroid Build Coastguard Worker 753*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct passwd *xgetpwuid(uid_t uid)<br /> 754*cf5a6c84SAndroid Build Coastguard Workerstruct group *xgetgrgid(gid_t gid)<br /> 755*cf5a6c84SAndroid Build Coastguard Workerstruct passwd *xgetpwnam(char *name)</b></p> 756*cf5a6c84SAndroid Build Coastguard Worker</li> 757*cf5a6c84SAndroid Build Coastguard Worker 758*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xsetuser(struct passwd *pwd)</b></li> 759*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xreadlink(char *name)</b></li> 760*cf5a6c84SAndroid Build Coastguard Worker<li><b>char *xreadfile(char *name, char *buf, off_t len)</b></li> 761*cf5a6c84SAndroid Build Coastguard Worker<li><b>int xioctl(int fd, int request, void *data)</b></li> 762*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xpidfile(char *name)</b></li> 763*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xsendfile(int in, int out)</b></li> 764*cf5a6c84SAndroid Build Coastguard Worker<li><b>long xparsetime(char *arg, long units, long *fraction)</b></li> 765*cf5a6c84SAndroid Build Coastguard Worker<li><b>void xregcomp(regex_t *preg, char *regex, int cflags)</b></li> 766*cf5a6c84SAndroid Build Coastguard Worker</ul> 767*cf5a6c84SAndroid Build Coastguard Worker 768*cf5a6c84SAndroid Build Coastguard Worker<a name="lib_lib"><h3>lib/lib.c</h3> 769*cf5a6c84SAndroid Build Coastguard Worker<p>Eight gazillion common functions, see lib/lib.h for the moment:</p> 770*cf5a6c84SAndroid Build Coastguard Worker 771*cf5a6c84SAndroid Build Coastguard Worker<h3>lib/portability.h</h3> 772*cf5a6c84SAndroid Build Coastguard Worker 773*cf5a6c84SAndroid Build Coastguard Worker<p>This file is automatically included from the top of toys.h, and smooths 774*cf5a6c84SAndroid Build Coastguard Workerover differences between platforms (hardware targets, compilers, C libraries, 775*cf5a6c84SAndroid Build Coastguard Workeroperating systems, etc).</p> 776*cf5a6c84SAndroid Build Coastguard Worker 777*cf5a6c84SAndroid Build Coastguard Worker<p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p> 778*cf5a6c84SAndroid Build Coastguard Worker 779*cf5a6c84SAndroid Build Coastguard Worker<p>A macro like SWAP_LE32(x) means "The value in x is stored as a little 780*cf5a6c84SAndroid Build Coastguard Workerendian 32 bit value, so perform the translation to/from whatever the native 781*cf5a6c84SAndroid Build Coastguard Worker32-bit format is". You do the swap once on the way in, and once on the way 782*cf5a6c84SAndroid Build Coastguard Workerout. If your target is already little endian, the macro is a NOP.</p> 783*cf5a6c84SAndroid Build Coastguard Worker 784*cf5a6c84SAndroid Build Coastguard Worker<p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions. 785*cf5a6c84SAndroid Build Coastguard WorkerIn each case, the name of the macro refers to the _external_ representation, 786*cf5a6c84SAndroid Build Coastguard Workerand converts to/from whatever your native representation happens to be (which 787*cf5a6c84SAndroid Build Coastguard Workercan vary depending on what you're currently compiling for).</p> 788*cf5a6c84SAndroid Build Coastguard Worker 789*cf5a6c84SAndroid Build Coastguard Worker<a name="lib_llist"><h3>lib/llist.c</h3> 790*cf5a6c84SAndroid Build Coastguard Worker 791*cf5a6c84SAndroid Build Coastguard Worker<p>Some generic single and doubly linked list functions, which take 792*cf5a6c84SAndroid Build Coastguard Workeradvantage of a couple properties of C:</p> 793*cf5a6c84SAndroid Build Coastguard Worker 794*cf5a6c84SAndroid Build Coastguard Worker<ul> 795*cf5a6c84SAndroid Build Coastguard Worker<li><p>Structure elements are laid out in memory in the order listed, and 796*cf5a6c84SAndroid Build Coastguard Workerthe first element has no padding. This means you can always treat (typecast) 797*cf5a6c84SAndroid Build Coastguard Workera pointer to a structure as a pointer to the first element of the structure, 798*cf5a6c84SAndroid Build Coastguard Workereven if you don't know anything about the data following it.</p></li> 799*cf5a6c84SAndroid Build Coastguard Worker 800*cf5a6c84SAndroid Build Coastguard Worker<li><p>An array of length zero at the end of a structure adds no space 801*cf5a6c84SAndroid Build Coastguard Workerto the sizeof() the structure, but if you calculate how much extra space 802*cf5a6c84SAndroid Build Coastguard Workeryou want when you malloc() the structure it will be available at the end. 803*cf5a6c84SAndroid Build Coastguard WorkerSince C has no bounds checking, this means each struct can have one variable 804*cf5a6c84SAndroid Build Coastguard Workerlength array.</p></li> 805*cf5a6c84SAndroid Build Coastguard Worker</ul> 806*cf5a6c84SAndroid Build Coastguard Worker 807*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox's list structures always have their <b>next</b> pointer as 808*cf5a6c84SAndroid Build Coastguard Workerthe first entry of each struct, and singly linked lists end with a NULL pointer. 809*cf5a6c84SAndroid Build Coastguard WorkerThis allows generic code to traverse such lists without knowing anything 810*cf5a6c84SAndroid Build Coastguard Workerelse about the specific structs composing them: if your pointer isn't NULL 811*cf5a6c84SAndroid Build Coastguard Workertypecast it to void ** and dereference once to get the next entry.</p> 812*cf5a6c84SAndroid Build Coastguard Worker 813*cf5a6c84SAndroid Build Coastguard Worker<p><b>lib/lib.h</b> defines three structure types:</p> 814*cf5a6c84SAndroid Build Coastguard Worker<ul> 815*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>), 816*cf5a6c84SAndroid Build Coastguard Workermemory for which is allocated as part of the node. (I.E. llist_traverse(list, 817*cf5a6c84SAndroid Build Coastguard Workerfree); can clean up after this type of list.)</p></li> 818*cf5a6c84SAndroid Build Coastguard Worker 819*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct arg_list</b> - stores a pointer to a single string 820*cf5a6c84SAndroid Build Coastguard Worker(<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li> 821*cf5a6c84SAndroid Build Coastguard Worker 822*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list 823*cf5a6c84SAndroid Build Coastguard Worker*prev</b> along with a <b>char *data</b> for payload.</p></li> 824*cf5a6c84SAndroid Build Coastguard Worker</ul> 825*cf5a6c84SAndroid Build Coastguard Worker 826*cf5a6c84SAndroid Build Coastguard Worker<b>List Functions</b> 827*cf5a6c84SAndroid Build Coastguard Worker 828*cf5a6c84SAndroid Build Coastguard Worker<ul> 829*cf5a6c84SAndroid Build Coastguard Worker<li><p>void *<b>llist_pop</b>(void **list) - advances through a list ala 830*cf5a6c84SAndroid Build Coastguard Worker<b>node = llist_pop(&list);</b> This doesn't modify the list contents, 831*cf5a6c84SAndroid Build Coastguard Workerbut does advance the pointer you feed it (which is why you pass the _address_ 832*cf5a6c84SAndroid Build Coastguard Workerof that pointer, not the pointer itself).</p></li> 833*cf5a6c84SAndroid Build Coastguard Worker 834*cf5a6c84SAndroid Build Coastguard Worker<li><p>void <b>llist_traverse</b>(void *list, void (*using)(void *data)) - 835*cf5a6c84SAndroid Build Coastguard Workeriterate through a list calling a function on each node.</p></li> 836*cf5a6c84SAndroid Build Coastguard Worker 837*cf5a6c84SAndroid Build Coastguard Worker<li><p>struct double_list *<b>dlist_add</b>(struct double_list **llist, char *data) 838*cf5a6c84SAndroid Build Coastguard Worker- append an entry to a circular linked list. 839*cf5a6c84SAndroid Build Coastguard WorkerThis function allocates a new struct double_list wrapper and returns the 840*cf5a6c84SAndroid Build Coastguard Workerpointer to the new entry (which you can usually ignore since it's llist->prev, 841*cf5a6c84SAndroid Build Coastguard Workerbut if llist was NULL you need it). The argument is the ->data field for the 842*cf5a6c84SAndroid Build Coastguard Workernew node.</p></li> 843*cf5a6c84SAndroid Build Coastguard Worker<ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist, 844*cf5a6c84SAndroid Build Coastguard Workerstruct double_list *new) - append existing struct double_list to 845*cf5a6c84SAndroid Build Coastguard Workerlist, does not allocate anything.</p></li></ul> 846*cf5a6c84SAndroid Build Coastguard Worker</ul> 847*cf5a6c84SAndroid Build Coastguard Worker 848*cf5a6c84SAndroid Build Coastguard Worker<b>List code trivia questions:</b> 849*cf5a6c84SAndroid Build Coastguard Worker 850*cf5a6c84SAndroid Build Coastguard Worker<ul> 851*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>Why do arg_list and double_list contain a char * payload instead of 852*cf5a6c84SAndroid Build Coastguard Workera void *?</b> - Because you always have to typecast a void * to use it, and 853*cf5a6c84SAndroid Build Coastguard Workertypecasting a char * does no harm. Since strings are the most common 854*cf5a6c84SAndroid Build Coastguard Workerpayload, and doing math on the pointer ala 855*cf5a6c84SAndroid Build Coastguard Worker"(type *)(ptr+sizeof(thing)+sizeof(otherthing))" requires ptr to be char * 856*cf5a6c84SAndroid Build Coastguard Workeranyway (at least according to the C standard), defaulting to char * saves 857*cf5a6c84SAndroid Build Coastguard Workera typecast.</p> 858*cf5a6c84SAndroid Build Coastguard Worker</li> 859*cf5a6c84SAndroid Build Coastguard Worker 860*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force 861*cf5a6c84SAndroid Build Coastguard Workeryou to keep track of which one you're using, calling free(node->str) would 862*cf5a6c84SAndroid Build Coastguard Workerbe bad, and _failing_ to free(node->arg) leaks memory.</p></li> 863*cf5a6c84SAndroid Build Coastguard Worker 864*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>Why does llist_pop() take a void * instead of void **?</b> - 865*cf5a6c84SAndroid Build Coastguard Workerbecause the stupid compiler complains about "type punned pointers" when 866*cf5a6c84SAndroid Build Coastguard Workeryou typecast and dereference on the same line, 867*cf5a6c84SAndroid Build Coastguard Workerdue to insane FSF developers hardwiring limitations of their optimizer 868*cf5a6c84SAndroid Build Coastguard Workerinto gcc's warning system. Since C automatically typecasts any other 869*cf5a6c84SAndroid Build Coastguard Workerpointer type to and from void *, the current code works fine. It's sad that it 870*cf5a6c84SAndroid Build Coastguard Workerwon't warn you if you forget the &, but the code crashes pretty quickly in 871*cf5a6c84SAndroid Build Coastguard Workerthat case.</p></li> 872*cf5a6c84SAndroid Build Coastguard Worker 873*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>How do I assemble a singly-linked-list in order?</b> - use 874*cf5a6c84SAndroid Build Coastguard Workera double_list, dlist_add() your entries, and then call dlist_terminate(list) 875*cf5a6c84SAndroid Build Coastguard Workerto break the circle when done (turning the last ->next and the first ->prev 876*cf5a6c84SAndroid Build Coastguard Workerinto NULLs).</p> 877*cf5a6c84SAndroid Build Coastguard Worker</ul> 878*cf5a6c84SAndroid Build Coastguard Worker 879*cf5a6c84SAndroid Build Coastguard Worker<a name="lib_args"><h3>lib/args.c</h3> 880*cf5a6c84SAndroid Build Coastguard Worker 881*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox's main.c automatically parses command line options before calling the 882*cf5a6c84SAndroid Build Coastguard Workercommand's main function. Option parsing starts in get_optflags(), which stores 883*cf5a6c84SAndroid Build Coastguard Workerresults in the global structures "toys" (optflags and optargs) and "this".</p> 884*cf5a6c84SAndroid Build Coastguard Worker 885*cf5a6c84SAndroid Build Coastguard Worker<p>The option parsing infrastructure stores a bitfield in toys.optflags to 886*cf5a6c84SAndroid Build Coastguard Workerindicate which options the current command line contained, and defines FLAG 887*cf5a6c84SAndroid Build Coastguard Workermacros code can use to check whether each argument's bit is set. Arguments 888*cf5a6c84SAndroid Build Coastguard Workerattached to those options are saved into the command's global structure 889*cf5a6c84SAndroid Build Coastguard Worker("this"). Any remaining command line arguments are collected together into 890*cf5a6c84SAndroid Build Coastguard Workerthe null-terminated array toys.optargs, with the length in toys.optc. (Note 891*cf5a6c84SAndroid Build Coastguard Workerthat toys.optargs does not contain the current command name at position zero, 892*cf5a6c84SAndroid Build Coastguard Workeruse "toys.which->name" for that.) The raw command line arguments get_optflags() 893*cf5a6c84SAndroid Build Coastguard Workerparsed are retained unmodified in toys.argv[].</p> 894*cf5a6c84SAndroid Build Coastguard Worker 895*cf5a6c84SAndroid Build Coastguard Worker<p>Toybox's option parsing logic is controlled by an "optflags" string, using 896*cf5a6c84SAndroid Build Coastguard Workera format reminiscent of getopt's optargs but with several important differences. 897*cf5a6c84SAndroid Build Coastguard WorkerToybox does not use the getopt() 898*cf5a6c84SAndroid Build Coastguard Workerfunction out of the C library, get_optflags() is an independent implementation 899*cf5a6c84SAndroid Build Coastguard Workerwhich doesn't permute the original arguments (and thus doesn't change how the 900*cf5a6c84SAndroid Build Coastguard Workercommand is displayed in ps and top), and has many features not present in 901*cf5a6c84SAndroid Build Coastguard Workerlibc optargs() (such as the ability to describe long options in the same string 902*cf5a6c84SAndroid Build Coastguard Workeras normal options).</p> 903*cf5a6c84SAndroid Build Coastguard Worker 904*cf5a6c84SAndroid Build Coastguard Worker<p>Each command's NEWTOY() macro has an optflags string as its middle argument, 905*cf5a6c84SAndroid Build Coastguard Workerwhich sets toy_list.options for that command to tell get_optflags() what 906*cf5a6c84SAndroid Build Coastguard Workercommand line arguments to look for, and what to do with them. 907*cf5a6c84SAndroid Build Coastguard WorkerIf a command has no option 908*cf5a6c84SAndroid Build Coastguard Workerdefinition string (I.E. the argument is NULL), option parsing is skipped 909*cf5a6c84SAndroid Build Coastguard Workerfor that command, which must look at the raw data in toys.argv to parse its 910*cf5a6c84SAndroid Build Coastguard Workerown arguments. (If no currently enabled command uses option parsing, 911*cf5a6c84SAndroid Build Coastguard Workerget_optflags() is optimized out of the resulting binary by the compiler's 912*cf5a6c84SAndroid Build Coastguard Worker--gc-sections option.)</p> 913*cf5a6c84SAndroid Build Coastguard Worker 914*cf5a6c84SAndroid Build Coastguard Worker<p>You don't have to free the option strings, which point into the environment 915*cf5a6c84SAndroid Build Coastguard Workerspace (I.E. the string data is not copied). A TOYFLAG_NOFORK command 916*cf5a6c84SAndroid Build Coastguard Workerthat uses the linked list type "*" should free the list objects but not 917*cf5a6c84SAndroid Build Coastguard Workerthe data they point to, via "llist_free(TT.mylist, NULL);". (If it's not 918*cf5a6c84SAndroid Build Coastguard WorkerNOFORK, exit() will free all the malloced data anyway unless you want 919*cf5a6c84SAndroid Build Coastguard Workerto implement a CONFIG_TOYBOX_FREE cleanup for it.)</p> 920*cf5a6c84SAndroid Build Coastguard Worker 921*cf5a6c84SAndroid Build Coastguard Worker<h4>Optflags format string</h4> 922*cf5a6c84SAndroid Build Coastguard Worker 923*cf5a6c84SAndroid Build Coastguard Worker<p>Note: the optflags option description string format is much more 924*cf5a6c84SAndroid Build Coastguard Workerconcisely described by a large comment at the top of lib/args.c.</p> 925*cf5a6c84SAndroid Build Coastguard Worker 926*cf5a6c84SAndroid Build Coastguard Worker<p>The general theory is that letters set optflags, and punctuation describes 927*cf5a6c84SAndroid Build Coastguard Workerother actions the option parsing logic should take.</p> 928*cf5a6c84SAndroid Build Coastguard Worker 929*cf5a6c84SAndroid Build Coastguard Worker<p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b> 930*cf5a6c84SAndroid Build Coastguard Workeris parsed using the optflags string "<b>a#b:c:d</b>". (I.E. 931*cf5a6c84SAndroid Build Coastguard Workertoys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d", 932*cf5a6c84SAndroid Build Coastguard Worker"walrus", "-a", "42"]). When get_optflags() returns, the following data is 933*cf5a6c84SAndroid Build Coastguard Workeravailable to command_main(): 934*cf5a6c84SAndroid Build Coastguard Worker 935*cf5a6c84SAndroid Build Coastguard Worker<ul> 936*cf5a6c84SAndroid Build Coastguard Worker<li><p>In <b>struct toys</b>: 937*cf5a6c84SAndroid Build Coastguard Worker<ul> 938*cf5a6c84SAndroid Build Coastguard Worker<li>toys.optflags = 13; // FLAG_a = 8 | FLAG_b = 4 | FLAG_d = 1</li> 939*cf5a6c84SAndroid Build Coastguard Worker<li>toys.optargs[0] = "walrus"; // leftover argument</li> 940*cf5a6c84SAndroid Build Coastguard Worker<li>toys.optargs[1] = NULL; // end of list</li> 941*cf5a6c84SAndroid Build Coastguard Worker<li>toys.optc = 1; // there was 1 leftover argument</li> 942*cf5a6c84SAndroid Build Coastguard Worker<li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments 943*cf5a6c84SAndroid Build Coastguard Worker</ul> 944*cf5a6c84SAndroid Build Coastguard Worker<p></li> 945*cf5a6c84SAndroid Build Coastguard Worker 946*cf5a6c84SAndroid Build Coastguard Worker<li><p>In <b>union this</b> (treated as <b>long this[]</b>): 947*cf5a6c84SAndroid Build Coastguard Worker<ul> 948*cf5a6c84SAndroid Build Coastguard Worker<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> 949*cf5a6c84SAndroid Build Coastguard Worker<li>this[1] = (long)"fruit"; // argument to -b</li> 950*cf5a6c84SAndroid Build Coastguard Worker<li>this[2] = 42; // argument to -a</li> 951*cf5a6c84SAndroid Build Coastguard Worker</ul> 952*cf5a6c84SAndroid Build Coastguard Worker</p></li> 953*cf5a6c84SAndroid Build Coastguard Worker</ul> 954*cf5a6c84SAndroid Build Coastguard Worker 955*cf5a6c84SAndroid Build Coastguard Worker<p>If the command's globals are:</p> 956*cf5a6c84SAndroid Build Coastguard Worker 957*cf5a6c84SAndroid Build Coastguard Worker<blockquote><pre> 958*cf5a6c84SAndroid Build Coastguard WorkerGLOBALS( 959*cf5a6c84SAndroid Build Coastguard Worker char *c; 960*cf5a6c84SAndroid Build Coastguard Worker char *b; 961*cf5a6c84SAndroid Build Coastguard Worker long a; 962*cf5a6c84SAndroid Build Coastguard Worker) 963*cf5a6c84SAndroid Build Coastguard Worker</pre></blockquote> 964*cf5a6c84SAndroid Build Coastguard Worker 965*cf5a6c84SAndroid Build Coastguard Worker<p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember, 966*cf5a6c84SAndroid Build Coastguard Workereach entry that receives an argument must be a long or pointer, to line up 967*cf5a6c84SAndroid Build Coastguard Workerwith the array position. Right to left in the optflags string corresponds to 968*cf5a6c84SAndroid Build Coastguard Workertop to bottom in GLOBALS().</p> 969*cf5a6c84SAndroid Build Coastguard Worker 970*cf5a6c84SAndroid Build Coastguard Worker<p>Put globals not filled out by the option parsing logic at the end of the 971*cf5a6c84SAndroid Build Coastguard WorkerGLOBALS block. Common practice is to list the options one per line (to 972*cf5a6c84SAndroid Build Coastguard Workermake the ordering explicit, first to last in globals corresponds to right 973*cf5a6c84SAndroid Build Coastguard Workerto left in the option string), then leave a blank line before any non-option 974*cf5a6c84SAndroid Build Coastguard Workerglobals.</p> 975*cf5a6c84SAndroid Build Coastguard Worker 976*cf5a6c84SAndroid Build Coastguard Worker<p><b>long toys.optflags</b></p> 977*cf5a6c84SAndroid Build Coastguard Worker 978*cf5a6c84SAndroid Build Coastguard Worker<p>Each option in the optflags string corresponds to a bit position in 979*cf5a6c84SAndroid Build Coastguard Workertoys.optflags, with the same value as a corresponding binary digit. The 980*cf5a6c84SAndroid Build Coastguard Workerrightmost argument is (1<<0), the next to last is (1<<1) and so on. If 981*cf5a6c84SAndroid Build Coastguard Workerthe option isn't encountered while parsing argv[], its bit remains 0.</p> 982*cf5a6c84SAndroid Build Coastguard Worker 983*cf5a6c84SAndroid Build Coastguard Worker<p>Each option -x has a FLAG_x macro for the command letter. Bare --longopts 984*cf5a6c84SAndroid Build Coastguard Workerwith no corresponding short option have a FLAG_longopt macro for the long 985*cf5a6c84SAndroid Build Coastguard Workeroptionname. Commands enable these macros by #defining FOR_commandname before 986*cf5a6c84SAndroid Build Coastguard Worker#including <toys.h>. When multiple commands are implemented in the same 987*cf5a6c84SAndroid Build Coastguard Workersource file, you can switch flag contexts later in the file by 988*cf5a6c84SAndroid Build Coastguard Worker#defining CLEANUP_oldcommand and #defining FOR_newcommand, then 989*cf5a6c84SAndroid Build Coastguard Worker#including <generated/flags.h>.</p> 990*cf5a6c84SAndroid Build Coastguard Worker 991*cf5a6c84SAndroid Build Coastguard Worker<p>Options disabled in the current configuration (wrapped in 992*cf5a6c84SAndroid Build Coastguard Workera USE_BLAH() macro for a CONFIG_BLAH that's switched off) have their 993*cf5a6c84SAndroid Build Coastguard Workercorresponding FLAG macro set to zero, so code checking them ala 994*cf5a6c84SAndroid Build Coastguard Workerif (toys.optargs & FLAG_x) gets optimized out via dead code elimination. 995*cf5a6c84SAndroid Build Coastguard Worker#defining FORCE_FLAGS when switching flag context disables this 996*cf5a6c84SAndroid Build Coastguard Workerbehavior: the flag is never zero even if the config is disabled. This 997*cf5a6c84SAndroid Build Coastguard Workerallows code shared between multiple commands to use the same flag 998*cf5a6c84SAndroid Build Coastguard Workervalues, as long as the common flags match up right to left in both option 999*cf5a6c84SAndroid Build Coastguard Workerstrings.</p> 1000*cf5a6c84SAndroid Build Coastguard Worker 1001*cf5a6c84SAndroid Build Coastguard Worker<p>For example, 1002*cf5a6c84SAndroid Build Coastguard Workerthe optflags string "abcd" would parse the command line argument "-c" to set 1003*cf5a6c84SAndroid Build Coastguard Workeroptflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to 1004*cf5a6c84SAndroid Build Coastguard Worker6 (I.E. 4|2), and "-a -c" would set optflags to 10 (2|8). To check if -c 1005*cf5a6c84SAndroid Build Coastguard Workerwas encountered, code could test: if (toys.optflags & FLAG_c) printf("yup"); 1006*cf5a6c84SAndroid Build Coastguard Worker(See the toys/examples directory for more.)</p> 1007*cf5a6c84SAndroid Build Coastguard Worker 1008*cf5a6c84SAndroid Build Coastguard Worker<p>Only letters are relevant to optflags, punctuation is skipped: in the 1009*cf5a6c84SAndroid Build Coastguard Workerstring "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter 1010*cf5a6c84SAndroid Build Coastguard Workerusually indicate that the option takes an argument.</p> 1011*cf5a6c84SAndroid Build Coastguard Worker 1012*cf5a6c84SAndroid Build Coastguard Worker<p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is 1013*cf5a6c84SAndroid Build Coastguard Workerthe amount a long would have on 32-bit platforms anyway; 64 bit code on 1014*cf5a6c84SAndroid Build Coastguard Worker32 bit platforms is too expensive to require in common code used by almost 1015*cf5a6c84SAndroid Build Coastguard Workerall commands.) Bit positions beyond the 1<<31 aren't recorded, but 1016*cf5a6c84SAndroid Build Coastguard Workerparsing higher options can still set global variables.</p> 1017*cf5a6c84SAndroid Build Coastguard Worker 1018*cf5a6c84SAndroid Build Coastguard Worker<p><b>Automatically setting global variables from arguments (union this)</b></p> 1019*cf5a6c84SAndroid Build Coastguard Worker 1020*cf5a6c84SAndroid Build Coastguard Worker<p>The following punctuation characters may be appended to an optflags 1021*cf5a6c84SAndroid Build Coastguard Workerargument letter, indicating the option takes an additional argument:</p> 1022*cf5a6c84SAndroid Build Coastguard Worker 1023*cf5a6c84SAndroid Build Coastguard Worker<ul> 1024*cf5a6c84SAndroid Build Coastguard Worker<li><b>:</b> - plus a string argument, keep most recent if more than one.</li> 1025*cf5a6c84SAndroid Build Coastguard Worker<li><b>*</b> - plus a string argument, appended to a linked list.</li> 1026*cf5a6c84SAndroid Build Coastguard Worker<li><b>@</b> - plus an occurrence counter (stored in a long)</li> 1027*cf5a6c84SAndroid Build Coastguard Worker<li><b>#</b> - plus a signed long argument. 1028*cf5a6c84SAndroid Build Coastguard Worker<li><b>-</b> - plus a signed long argument defaulting to negative (start argument with + to force a positive value).</li> 1029*cf5a6c84SAndroid Build Coastguard Worker<li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li> 1030*cf5a6c84SAndroid Build Coastguard Worker<ul>The following can be appended to a float or double: 1031*cf5a6c84SAndroid Build Coastguard Worker<li><b><123</b> - error if argument is less than this</li> 1032*cf5a6c84SAndroid Build Coastguard Worker<li><b>>123</b> - error if argument is greater than this</li> 1033*cf5a6c84SAndroid Build Coastguard Worker<li><b>=123</b> - default value if argument not supplied</li> 1034*cf5a6c84SAndroid Build Coastguard Worker</ul> 1035*cf5a6c84SAndroid Build Coastguard Worker</ul> 1036*cf5a6c84SAndroid Build Coastguard Worker 1037*cf5a6c84SAndroid Build Coastguard Worker<p><b>GLOBALS</b></p> 1038*cf5a6c84SAndroid Build Coastguard Worker 1039*cf5a6c84SAndroid Build Coastguard Worker<p>Options which have an argument fill in the corresponding slot in the global 1040*cf5a6c84SAndroid Build Coastguard Workerunion "this" (see generated/globals.h), treating it as an array of longs 1041*cf5a6c84SAndroid Build Coastguard Workerwith the rightmost saved in this[0]. As described above, using "a*b:c#d", 1042*cf5a6c84SAndroid Build Coastguard Worker"-c 42" would set this[0] = 42; and "-b 42" would set this[1] = "42"; each 1043*cf5a6c84SAndroid Build Coastguard Workerslot is left NULL if the corresponding argument is not encountered.</p> 1044*cf5a6c84SAndroid Build Coastguard Worker 1045*cf5a6c84SAndroid Build Coastguard Worker<p>This behavior is useful because the LP64 standard ensures long and pointer 1046*cf5a6c84SAndroid Build Coastguard Workerare the same size. C99 guarantees structure members will occur in memory 1047*cf5a6c84SAndroid Build Coastguard Workerin the same order they're declared, and that padding won't be inserted between 1048*cf5a6c84SAndroid Build Coastguard Workerconsecutive variables of register size. Thus the first few entries can 1049*cf5a6c84SAndroid Build Coastguard Workerbe longs or pointers corresponding to the saved arguments.</p> 1050*cf5a6c84SAndroid Build Coastguard Worker 1051*cf5a6c84SAndroid Build Coastguard Worker<p>The main downside is that numeric arguments ("#" and "-" format) 1052*cf5a6c84SAndroid Build Coastguard Workerare limited to +- 2 billion on 32 bit platforms (the "truncate -s 8G" 1053*cf5a6c84SAndroid Build Coastguard Workerproblem), because long is only 64 bits on 64 bit hosts, so the capabilities 1054*cf5a6c84SAndroid Build Coastguard Workerof some tools differ when built in 32 bit vs 64 bit mode. Fixing this 1055*cf5a6c84SAndroid Build Coastguard Workerkind of ugly and even embedded designs are slowly moving to 64 bits, 1056*cf5a6c84SAndroid Build Coastguard Workerso our current plan is to document the problem and wait it out. (If 1057*cf5a6c84SAndroid Build Coastguard Worker"x32 mode" and similar becomes popular enough, we may revisit this 1058*cf5a6c84SAndroid Build Coastguard Workerdecision.)</p> 1059*cf5a6c84SAndroid Build Coastguard Worker 1060*cf5a6c84SAndroid Build Coastguard Worker<p>See toys/example/*.c for longer examples of parsing options into the 1061*cf5a6c84SAndroid Build Coastguard WorkerGLOBALS block.</p> 1062*cf5a6c84SAndroid Build Coastguard Worker 1063*cf5a6c84SAndroid Build Coastguard Worker<p><b>char *toys.optargs[]</b></p> 1064*cf5a6c84SAndroid Build Coastguard Worker 1065*cf5a6c84SAndroid Build Coastguard Worker<p>Command line arguments in argv[] which are not consumed by option parsing 1066*cf5a6c84SAndroid Build Coastguard Worker(I.E. not recognized either as -flags or arguments to -flags) will be copied 1067*cf5a6c84SAndroid Build Coastguard Workerto toys.optargs[], with the length of that array in toys.optc. 1068*cf5a6c84SAndroid Build Coastguard Worker(When toys.optc is 0, no unrecognized command line arguments remain.) 1069*cf5a6c84SAndroid Build Coastguard WorkerThe order of entries is preserved, and as with argv[] this new array is also 1070*cf5a6c84SAndroid Build Coastguard Workerterminated by a NULL entry.</p> 1071*cf5a6c84SAndroid Build Coastguard Worker 1072*cf5a6c84SAndroid Build Coastguard Worker<p>Option parsing can require a minimum or maximum number of optargs left 1073*cf5a6c84SAndroid Build Coastguard Workerover, by adding "<1" (read "at least one") or ">9" ("at most nine") to the 1074*cf5a6c84SAndroid Build Coastguard Workerstart of the optflags string.</p> 1075*cf5a6c84SAndroid Build Coastguard Worker 1076*cf5a6c84SAndroid Build Coastguard Worker<p>The special argument "--" terminates option parsing, storing all remaining 1077*cf5a6c84SAndroid Build Coastguard Workerarguments in optargs. The "--" itself is consumed.</p> 1078*cf5a6c84SAndroid Build Coastguard Worker 1079*cf5a6c84SAndroid Build Coastguard Worker<p><b>Other optflags control characters</b></p> 1080*cf5a6c84SAndroid Build Coastguard Worker 1081*cf5a6c84SAndroid Build Coastguard Worker<p>The following characters may occur at the start of each command's 1082*cf5a6c84SAndroid Build Coastguard Workeroptflags string, before any options that would set a bit in toys.optflags:</p> 1083*cf5a6c84SAndroid Build Coastguard Worker 1084*cf5a6c84SAndroid Build Coastguard Worker<ul> 1085*cf5a6c84SAndroid Build Coastguard Worker<li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li> 1086*cf5a6c84SAndroid Build Coastguard Worker<li><b>?</b> - allow unknown arguments (pass non-option arguments starting 1087*cf5a6c84SAndroid Build Coastguard Workerwith - through to optargs instead of erroring out).</li> 1088*cf5a6c84SAndroid Build Coastguard Worker<li><b>&</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li> 1089*cf5a6c84SAndroid Build Coastguard Worker<li><b><</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li> 1090*cf5a6c84SAndroid Build Coastguard Worker<li><b>></b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li> 1091*cf5a6c84SAndroid Build Coastguard Worker</ul> 1092*cf5a6c84SAndroid Build Coastguard Worker 1093*cf5a6c84SAndroid Build Coastguard Worker<p>The following characters may be appended to an option character, but do 1094*cf5a6c84SAndroid Build Coastguard Workernot by themselves indicate an extra argument should be saved in this[]. 1095*cf5a6c84SAndroid Build Coastguard Worker(Technically any character not recognized as a control character sets an 1096*cf5a6c84SAndroid Build Coastguard Workeroptflag, but letters are never control characters.)</p> 1097*cf5a6c84SAndroid Build Coastguard Worker 1098*cf5a6c84SAndroid Build Coastguard Worker<ul> 1099*cf5a6c84SAndroid Build Coastguard Worker<li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li> 1100*cf5a6c84SAndroid Build Coastguard Worker<li><b>|</b> - this option is required. If more than one marked, only one is required.</li> 1101*cf5a6c84SAndroid Build Coastguard Worker</ul> 1102*cf5a6c84SAndroid Build Coastguard Worker 1103*cf5a6c84SAndroid Build Coastguard Worker<p>The following may be appended to a float or double:</p> 1104*cf5a6c84SAndroid Build Coastguard Worker 1105*cf5a6c84SAndroid Build Coastguard Worker<ul> 1106*cf5a6c84SAndroid Build Coastguard Worker<li><b><123</b> - error if argument is less than this</li> 1107*cf5a6c84SAndroid Build Coastguard Worker<li><b>>123</b> - error if argument is greater than this</li> 1108*cf5a6c84SAndroid Build Coastguard Worker<li><b>=123</b> - default value if argument not supplied</li> 1109*cf5a6c84SAndroid Build Coastguard Worker</ul> 1110*cf5a6c84SAndroid Build Coastguard Worker 1111*cf5a6c84SAndroid Build Coastguard Worker<p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT 1112*cf5a6c84SAndroid Build Coastguard Workeris enabled. (Otherwise the code to determine where floating point constants 1113*cf5a6c84SAndroid Build Coastguard Workerend drops out. When disabled, it can reserve a global data slot for the 1114*cf5a6c84SAndroid Build Coastguard Workerargument so offsets won't change, but will never fill it out.) You can handle 1115*cf5a6c84SAndroid Build Coastguard Workerthis by using the USE_BLAH() macros with C string concatenation, ala:</p> 1116*cf5a6c84SAndroid Build Coastguard Worker 1117*cf5a6c84SAndroid Build Coastguard Worker<blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote> 1118*cf5a6c84SAndroid Build Coastguard Worker 1119*cf5a6c84SAndroid Build Coastguard Worker<p><b>--longopts</b></p> 1120*cf5a6c84SAndroid Build Coastguard Worker 1121*cf5a6c84SAndroid Build Coastguard Worker<p>The optflags string can contain long options, which are enclosed in 1122*cf5a6c84SAndroid Build Coastguard Workerparentheses. They may be appended to an existing option character, in 1123*cf5a6c84SAndroid Build Coastguard Workerwhich case the --longopt is a synonym for that option, ala "a:(--fred)" 1124*cf5a6c84SAndroid Build Coastguard Workerwhich understands "-a blah" or "--fred blah" as synonyms.</p> 1125*cf5a6c84SAndroid Build Coastguard Worker 1126*cf5a6c84SAndroid Build Coastguard Worker<p>Longopts may also appear before any other options in the optflags string, 1127*cf5a6c84SAndroid Build Coastguard Workerin which case they have no corresponding short argument, but instead set 1128*cf5a6c84SAndroid Build Coastguard Workertheir own bit based on position. So for "(walrus)#(blah)xy:z", "command 1129*cf5a6c84SAndroid Build Coastguard Worker--walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8) 1130*cf5a6c84SAndroid Build Coastguard Workerand would assign this[1] = 42;</p> 1131*cf5a6c84SAndroid Build Coastguard Worker 1132*cf5a6c84SAndroid Build Coastguard Worker<p>A short option may have multiple longopt synonyms, "a(one)(two)", but 1133*cf5a6c84SAndroid Build Coastguard Workereach "bare longopt" (ala "(one)(two)abc" before any option characters) 1134*cf5a6c84SAndroid Build Coastguard Workeralways sets its own bit (although you can group them with +X).</p> 1135*cf5a6c84SAndroid Build Coastguard Worker 1136*cf5a6c84SAndroid Build Coastguard Worker<p>Only bare longopts have a FLAG_ macro with the longopt name 1137*cf5a6c84SAndroid Build Coastguard Worker(ala --fred would #define FLAG_fred). Other longopts use the short 1138*cf5a6c84SAndroid Build Coastguard Workeroption's FLAG macro to test the toys.optflags bit.</p> 1139*cf5a6c84SAndroid Build Coastguard Worker 1140*cf5a6c84SAndroid Build Coastguard Worker<p>Options with a semicolon ";" after their data type can only set their 1141*cf5a6c84SAndroid Build Coastguard Workercorresponding GLOBALS() entry via "--longopt=value". For example, option 1142*cf5a6c84SAndroid Build Coastguard Workerstring "x(boing): y" would set TT.x if it saw "--boing=value", but would 1143*cf5a6c84SAndroid Build Coastguard Workertreat "--boing value" as setting FLAG_x in toys.optargs, leaving TT.x NULL, 1144*cf5a6c84SAndroid Build Coastguard Workerand keeping "value" in toys.optargs[]. (This lets "ls --color" and 1145*cf5a6c84SAndroid Build Coastguard Worker"ls --color=auto" both work.)</p> 1146*cf5a6c84SAndroid Build Coastguard Worker 1147*cf5a6c84SAndroid Build Coastguard Worker<p><b>[groups]</b></p> 1148*cf5a6c84SAndroid Build Coastguard Worker 1149*cf5a6c84SAndroid Build Coastguard Worker<p>At the end of the option string, square bracket groups can define 1150*cf5a6c84SAndroid Build Coastguard Workerrelationships between existing options. (This only applies to short 1151*cf5a6c84SAndroid Build Coastguard Workeroptions, bare --longopts can't participate.)</p> 1152*cf5a6c84SAndroid Build Coastguard Worker 1153*cf5a6c84SAndroid Build Coastguard Worker<p>The first character of the group defines the type, the remaining 1154*cf5a6c84SAndroid Build Coastguard Workercharacters are options it applies to:</p> 1155*cf5a6c84SAndroid Build Coastguard Worker 1156*cf5a6c84SAndroid Build Coastguard Worker<ul> 1157*cf5a6c84SAndroid Build Coastguard Worker<li><b>-</b> - Exclusive, switch off all others in this group.</li> 1158*cf5a6c84SAndroid Build Coastguard Worker<li><b>+</b> - Inclusive, switch on all others in this group.</li> 1159*cf5a6c84SAndroid Build Coastguard Worker<li><b>!</b> - Error, fail if more than one defined.</li> 1160*cf5a6c84SAndroid Build Coastguard Worker</ul> 1161*cf5a6c84SAndroid Build Coastguard Worker 1162*cf5a6c84SAndroid Build Coastguard Worker<p>So "abc[-abc]" means -ab = -b, -ba = -a, -abc = -c. "abc[+abc]" 1163*cf5a6c84SAndroid Build Coastguard Workermeans -ab=-abc, -c=-abc, and "abc[!abc] means -ab calls error_exit("no -b 1164*cf5a6c84SAndroid Build Coastguard Workerwith -a"). Note that [-] groups clear the GLOBALS option slot of 1165*cf5a6c84SAndroid Build Coastguard Workeroptions they're switching back off, but [+] won't set options it didn't see 1166*cf5a6c84SAndroid Build Coastguard Worker(just the optflags).</p> 1167*cf5a6c84SAndroid Build Coastguard Worker 1168*cf5a6c84SAndroid Build Coastguard Worker<p><b>whitespace</b></p> 1169*cf5a6c84SAndroid Build Coastguard Worker 1170*cf5a6c84SAndroid Build Coastguard Worker<p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42"). 1171*cf5a6c84SAndroid Build Coastguard WorkerThe command line argument "-abc" may be interepreted many different ways: 1172*cf5a6c84SAndroid Build Coastguard Workerthe optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4 1173*cf5a6c84SAndroid Build Coastguard Workerand saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves 1174*cf5a6c84SAndroid Build Coastguard Worker"c" as the argument to -b.</p> 1175*cf5a6c84SAndroid Build Coastguard Worker 1176*cf5a6c84SAndroid Build Coastguard Worker<p>Note that & changes whitespace handling, so that the command line 1177*cf5a6c84SAndroid Build Coastguard Worker"tar cvfCj outfile.tar.bz2 topdir filename" is parsed the same as 1178*cf5a6c84SAndroid Build Coastguard Worker"tar filename -c -v -j -f outfile.tar.bz2 -C topdir". Note that "tar -cvfCj 1179*cf5a6c84SAndroid Build Coastguard Workerone two three" would equal "tar -c -v -f Cj one two three". (This matches 1180*cf5a6c84SAndroid Build Coastguard Workerhistorical usage.)</p> 1181*cf5a6c84SAndroid Build Coastguard Worker 1182*cf5a6c84SAndroid Build Coastguard Worker<p>Appending a space to the option in the option string ("a: b") makes it 1183*cf5a6c84SAndroid Build Coastguard Workerrequire a space, I.E. "-ab" is interpreted as "-a" "-b". That way "kill -stop" 1184*cf5a6c84SAndroid Build Coastguard Workerdiffers from "kill -s top".</p> 1185*cf5a6c84SAndroid Build Coastguard Worker 1186*cf5a6c84SAndroid Build Coastguard Worker<p>Appending ; to a longopt in the option string makes its argument optional, 1187*cf5a6c84SAndroid Build Coastguard Workerand only settable with =, so in ls "(color):;" can accept "ls --color" and 1188*cf5a6c84SAndroid Build Coastguard Worker"ls --color=auto" without complaining that the first has no argument.</p> 1189*cf5a6c84SAndroid Build Coastguard Worker 1190*cf5a6c84SAndroid Build Coastguard Worker<a name="lib_dirtree"><h3>lib/dirtree.c</h3> 1191*cf5a6c84SAndroid Build Coastguard Worker 1192*cf5a6c84SAndroid Build Coastguard Worker<p>The directory tree traversal code should be sufficiently generic 1193*cf5a6c84SAndroid Build Coastguard Workerthat commands never need to use readdir(), scandir(), or the fts.h family 1194*cf5a6c84SAndroid Build Coastguard Workerof functions.</p> 1195*cf5a6c84SAndroid Build Coastguard Worker 1196*cf5a6c84SAndroid Build Coastguard Worker<p>These functions do not call chdir() or rely on PATH_MAX. Instead they 1197*cf5a6c84SAndroid Build Coastguard Workeruse openat() and friends, using one filehandle per directory level to 1198*cf5a6c84SAndroid Build Coastguard Workerrecurse into subdirectories. (I.E. they can descend 1000 directories deep 1199*cf5a6c84SAndroid Build Coastguard Workerif setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default 1200*cf5a6c84SAndroid Build Coastguard Workerin /proc/self/limits is generally 1024.)</p> 1201*cf5a6c84SAndroid Build Coastguard Worker 1202*cf5a6c84SAndroid Build Coastguard Worker<p>There are two main ways to use dirtree: 1) assemble a tree of nodes 1203*cf5a6c84SAndroid Build Coastguard Workerrepresenting a snapshot of directory state and traverse them using the 1204*cf5a6c84SAndroid Build Coastguard Worker->next and ->child pointers, or 2) traverse the tree calling a callback 1205*cf5a6c84SAndroid Build Coastguard Workerfunction on each entry, and freeing its node afterwards. (You can also 1206*cf5a6c84SAndroid Build Coastguard Workercombine the two, using the callback as a filter to determine which nodes 1207*cf5a6c84SAndroid Build Coastguard Workerto keep.)</p> 1208*cf5a6c84SAndroid Build Coastguard Worker 1209*cf5a6c84SAndroid Build Coastguard Worker<p>The basic dirtree functions are:</p> 1210*cf5a6c84SAndroid Build Coastguard Worker 1211*cf5a6c84SAndroid Build Coastguard Worker<ul> 1212*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>struct dirtree *dirtree_read(char *path, int (*callback)(struct 1213*cf5a6c84SAndroid Build Coastguard Workerdirtree node))</b> - recursively read files and directories, calling 1214*cf5a6c84SAndroid Build Coastguard Workercallback() on each, and returning a tree of saved nodes (if any). 1215*cf5a6c84SAndroid Build Coastguard WorkerIf path doesn't exist, returns DIRTREE_ABORTVAL. If callback is NULL, 1216*cf5a6c84SAndroid Build Coastguard Workerreturns a single node at that path.</p> 1217*cf5a6c84SAndroid Build Coastguard Worker 1218*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>dirtree_notdotdot(struct dirtree *new)</b> - standard callback 1219*cf5a6c84SAndroid Build Coastguard Workerwhich discards "." and ".." entries and returns DIRTREE_SAVE|DIRTREE_RECURSE 1220*cf5a6c84SAndroid Build Coastguard Workerfor everything else. Used directly, this assembles a snapshot tree of 1221*cf5a6c84SAndroid Build Coastguard Workerthe contents of this directory and its subdirectories 1222*cf5a6c84SAndroid Build Coastguard Workerto be processed after dirtree_read() returns (by traversing the 1223*cf5a6c84SAndroid Build Coastguard Workerstruct dirtree's ->next and ->child pointers from the returned root node).</p> 1224*cf5a6c84SAndroid Build Coastguard Worker 1225*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>dirtree_path(struct dirtree *node, int *plen)</b> - malloc() a 1226*cf5a6c84SAndroid Build Coastguard Workerstring containing the path from the root of this tree to this node. If 1227*cf5a6c84SAndroid Build Coastguard Workerplen isn't NULL then *plen is how many extra bytes to malloc at the end 1228*cf5a6c84SAndroid Build Coastguard Workerof string.</p></li> 1229*cf5a6c84SAndroid Build Coastguard Worker 1230*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of 1231*cf5a6c84SAndroid Build Coastguard Workerdirectory containing this node, for use with openat() and such.</p></li> 1232*cf5a6c84SAndroid Build Coastguard Worker</ul> 1233*cf5a6c84SAndroid Build Coastguard Worker 1234*cf5a6c84SAndroid Build Coastguard Worker<p>The <b>dirtree_read()</b> function is the standard way to start 1235*cf5a6c84SAndroid Build Coastguard Workerdirectory traversal. It takes two arguments: a starting path for 1236*cf5a6c84SAndroid Build Coastguard Workerthe root of the tree, and a callback function. The callback() is called 1237*cf5a6c84SAndroid Build Coastguard Workeron each directory entry, its argument is a fully populated 1238*cf5a6c84SAndroid Build Coastguard Worker<b>struct dirtree *</b> (from lib/lib.h) describing the node, and its 1239*cf5a6c84SAndroid Build Coastguard Workerreturn value tells the dirtree infrastructure what to do next.</p> 1240*cf5a6c84SAndroid Build Coastguard Worker 1241*cf5a6c84SAndroid Build Coastguard Worker<p>(There's also a three argument version, 1242*cf5a6c84SAndroid Build Coastguard Worker<b>dirtree_flagread(char *path, int flags, int (*callback)(struct 1243*cf5a6c84SAndroid Build Coastguard Workerdirtree node))</b>, which lets you apply flags like DIRTREE_SYMFOLLOW and 1244*cf5a6c84SAndroid Build Coastguard WorkerDIRTREE_SHUTUP to reading the top node, but this only affects the top node. 1245*cf5a6c84SAndroid Build Coastguard WorkerChild nodes use the flags returned by callback().</p> 1246*cf5a6c84SAndroid Build Coastguard Worker 1247*cf5a6c84SAndroid Build Coastguard Worker<p><b>struct dirtree</b></p> 1248*cf5a6c84SAndroid Build Coastguard Worker 1249*cf5a6c84SAndroid Build Coastguard Worker<p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat 1250*cf5a6c84SAndroid Build Coastguard Workerst</b> entries describing a file, plus a <b>char *symlink</b> 1251*cf5a6c84SAndroid Build Coastguard Workerwhich is NULL for non-symlinks.</p> 1252*cf5a6c84SAndroid Build Coastguard Worker 1253*cf5a6c84SAndroid Build Coastguard Worker<p>During a callback function, the <b>int dirfd</b> field of directory nodes 1254*cf5a6c84SAndroid Build Coastguard Workercontains a directory file descriptor (for use with the openat() family of 1255*cf5a6c84SAndroid Build Coastguard Workerfunctions). This isn't usually used directly, intstead call dirtree_parentfd() 1256*cf5a6c84SAndroid Build Coastguard Workeron the callback's node argument. The <b>char again</b> field is 0 for the 1257*cf5a6c84SAndroid Build Coastguard Workerfirst callback on a node, and 1 on the second callback (triggered by returning 1258*cf5a6c84SAndroid Build Coastguard WorkerDIRTREE_COMEAGAIN on a directory, made after all children have been processed). 1259*cf5a6c84SAndroid Build Coastguard Worker</p> 1260*cf5a6c84SAndroid Build Coastguard Worker 1261*cf5a6c84SAndroid Build Coastguard Worker<p>Users of this code may put anything they like into the <b>long extra</b> 1262*cf5a6c84SAndroid Build Coastguard Workerfield. For example, "cp" and "mv" use this to store a dirfd for the destination 1263*cf5a6c84SAndroid Build Coastguard Workerdirectory (and use DIRTREE_COMEAGAIN to get the second callback so they can 1264*cf5a6c84SAndroid Build Coastguard Workerclose(node->extra) to avoid running out of filehandles). 1265*cf5a6c84SAndroid Build Coastguard WorkerThis field is not directly used by the dirtree code, and 1266*cf5a6c84SAndroid Build Coastguard Workerthanks to LP64 it's large enough to store a typecast pointer to an 1267*cf5a6c84SAndroid Build Coastguard Workerarbitrary struct.</p> 1268*cf5a6c84SAndroid Build Coastguard Worker 1269*cf5a6c84SAndroid Build Coastguard Worker<p>The return value of the callback combines flags (with boolean or) to tell 1270*cf5a6c84SAndroid Build Coastguard Workerthe traversal infrastructure how to behave:</p> 1271*cf5a6c84SAndroid Build Coastguard Worker 1272*cf5a6c84SAndroid Build Coastguard Worker<ul> 1273*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without 1274*cf5a6c84SAndroid Build Coastguard Workerthis the struct dirtree is freed after the callback returns. Filtering out 1275*cf5a6c84SAndroid Build Coastguard Workersiblings is fine, but discarding a parent while keeping its child leaks 1276*cf5a6c84SAndroid Build Coastguard Workermemory.)</p></li> 1277*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this 1278*cf5a6c84SAndroid Build Coastguard Workerdirectory. (Does not propagate up tree: to abort entire traversal, 1279*cf5a6c84SAndroid Build Coastguard Workerreturn DIRTREE_ABORT from parent callbacks too.)</p></li> 1280*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for 1281*cf5a6c84SAndroid Build Coastguard Workernon-directory entries. The remaining flags only take effect when 1282*cf5a6c84SAndroid Build Coastguard Workerrecursing into the children of a directory.</p></li> 1283*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback on this node a second time 1284*cf5a6c84SAndroid Build Coastguard Workerafter examining all directory contents, allowing depth-first traversal. 1285*cf5a6c84SAndroid Build Coastguard WorkerOn the second call, dirtree->again is nonzero.</p></li> 1286*cf5a6c84SAndroid Build Coastguard Worker<li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's 1287*cf5a6c84SAndroid Build Coastguard Worker<b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of 1288*cf5a6c84SAndroid Build Coastguard Workerdirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to 1289*cf5a6c84SAndroid Build Coastguard Workerdirectories as directories. (Avoiding infinite recursion is the callback's 1290*cf5a6c84SAndroid Build Coastguard Workerproblem: the non-NULL dirtree->symlink can still distinguish between 1291*cf5a6c84SAndroid Build Coastguard Workerthem. The "find" command follows ->parent up the tree to the root node 1292*cf5a6c84SAndroid Build Coastguard Workereach time, checking to make sure that stat's dev and inode pair don't 1293*cf5a6c84SAndroid Build Coastguard Workermatch any ancestors.)</p></li> 1294*cf5a6c84SAndroid Build Coastguard Worker</ul> 1295*cf5a6c84SAndroid Build Coastguard Worker 1296*cf5a6c84SAndroid Build Coastguard Worker<p>Each struct dirtree contains three pointers (next, parent, and child) 1297*cf5a6c84SAndroid Build Coastguard Workerto other struct dirtree.</p> 1298*cf5a6c84SAndroid Build Coastguard Worker 1299*cf5a6c84SAndroid Build Coastguard Worker<p>The <b>parent</b> pointer indicates the directory 1300*cf5a6c84SAndroid Build Coastguard Workercontaining this entry; even when not assembling a persistent tree of 1301*cf5a6c84SAndroid Build Coastguard Workernodes the parent entries remain live up to the root of the tree while 1302*cf5a6c84SAndroid Build Coastguard Workerchild nodes are active. At the top of the tree the parent pointer is 1303*cf5a6c84SAndroid Build Coastguard WorkerNULL, meaning the node's name[] is either an absolute path or relative 1304*cf5a6c84SAndroid Build Coastguard Workerto cwd. The function dirtree_parentfd() gets the directory file descriptor 1305*cf5a6c84SAndroid Build Coastguard Workerfor use with openat() and friends, returning AT_FDCWD at the top of tree.</p> 1306*cf5a6c84SAndroid Build Coastguard Worker 1307*cf5a6c84SAndroid Build Coastguard Worker<p>The <b>child</b> pointer points to the first node of the list of contents of 1308*cf5a6c84SAndroid Build Coastguard Workerthis directory. If the directory contains no files, or the entry isn't 1309*cf5a6c84SAndroid Build Coastguard Workera directory, child is NULL.</p> 1310*cf5a6c84SAndroid Build Coastguard Worker 1311*cf5a6c84SAndroid Build Coastguard Worker<p>The <b>next</b> pointer indicates sibling nodes in the same directory as this 1312*cf5a6c84SAndroid Build Coastguard Workernode, and since it's the first entry in the struct the llist.c traversal 1313*cf5a6c84SAndroid Build Coastguard Workermechanisms work to iterate over sibling nodes. Each dirtree node is a 1314*cf5a6c84SAndroid Build Coastguard Workersingle malloc() (even char *symlink points to memory at the end of the node), 1315*cf5a6c84SAndroid Build Coastguard Workerso llist_free() works but its callback must descend into child nodes (freeing 1316*cf5a6c84SAndroid Build Coastguard Workera tree, not just a linked list), plus whatever the user stored in extra.</p> 1317*cf5a6c84SAndroid Build Coastguard Worker 1318*cf5a6c84SAndroid Build Coastguard Worker<p>The <b>dirtree_flagread</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>() 1319*cf5a6c84SAndroid Build Coastguard Workerto create a root node relative to the current directory, then calling 1320*cf5a6c84SAndroid Build Coastguard Worker<b>dirtree_handle_callback</b>() on that node (which recurses as instructed by the callback 1321*cf5a6c84SAndroid Build Coastguard Workerreturn flags). The flags argument primarily lets you 1322*cf5a6c84SAndroid Build Coastguard Workercontrol whether or not to follow symlinks to the root node; symlinks 1323*cf5a6c84SAndroid Build Coastguard Workerlisted on the command line are often treated differently than symlinks 1324*cf5a6c84SAndroid Build Coastguard Workerencountered during recursive directory traversal. 1325*cf5a6c84SAndroid Build Coastguard Worker 1326*cf5a6c84SAndroid Build Coastguard Worker<p>The ls command not only bypasses this wrapper, but never returns 1327*cf5a6c84SAndroid Build Coastguard Worker<b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually 1328*cf5a6c84SAndroid Build Coastguard Workerfrom elsewhere in the program. This gives ls -lR manual control 1329*cf5a6c84SAndroid Build Coastguard Workerof traversal order, which is neither depth first nor breadth first but 1330*cf5a6c84SAndroid Build Coastguard Workerinstead a sort of FIFO order requried by the ls standard.</p> 1331*cf5a6c84SAndroid Build Coastguard Worker 1332*cf5a6c84SAndroid Build Coastguard Worker<a name="toys"> 1333*cf5a6c84SAndroid Build Coastguard Worker<h1><a href="#toys">Directory toys/</a></h1> 1334*cf5a6c84SAndroid Build Coastguard Worker 1335*cf5a6c84SAndroid Build Coastguard Worker<p>This directory contains command implementations. Each command is a single 1336*cf5a6c84SAndroid Build Coastguard Workerself-contained file. Adding a new command involves adding a single 1337*cf5a6c84SAndroid Build Coastguard Workerfile, and removing a command involves removing that file. Commands use 1338*cf5a6c84SAndroid Build Coastguard Workershared infrastructure from the lib/ and generated/ directories.</p> 1339*cf5a6c84SAndroid Build Coastguard Worker 1340*cf5a6c84SAndroid Build Coastguard Worker<p>Currently there are five subdirectories under "toys/" containing "posix" 1341*cf5a6c84SAndroid Build Coastguard Workercommands described in POSIX-2008, "lsb" commands described in the Linux 1342*cf5a6c84SAndroid Build Coastguard WorkerStandard Base 4.1, "other" commands not described by either standard, 1343*cf5a6c84SAndroid Build Coastguard Worker"pending" commands awaiting cleanup (which default to "n" in menuconfig 1344*cf5a6c84SAndroid Build Coastguard Workerbecause they don't necessarily work right yet), and "example" code showing 1345*cf5a6c84SAndroid Build Coastguard Workerhow toybox infrastructure works and providing template/skeleton files to 1346*cf5a6c84SAndroid Build Coastguard Workerstart new commands.</p> 1347*cf5a6c84SAndroid Build Coastguard Worker 1348*cf5a6c84SAndroid Build Coastguard Worker<p>The only difference directory location makes is which menu the command 1349*cf5a6c84SAndroid Build Coastguard Workershows up in during "make menuconfig", the directories are otherwise identical. 1350*cf5a6c84SAndroid Build Coastguard WorkerNote that the commands exist within a single namespace at runtime, so you can't 1351*cf5a6c84SAndroid Build Coastguard Workerhave the same command in multiple subdirectories. (The build tries to fail 1352*cf5a6c84SAndroid Build Coastguard Workerinformatively when you do that.)</p> 1353*cf5a6c84SAndroid Build Coastguard Worker 1354*cf5a6c84SAndroid Build Coastguard Worker<p>There is one more sub-menus in "make menuconfig" containing global 1355*cf5a6c84SAndroid Build Coastguard Workerconfiguration options for toybox. This menu is defined in the top level 1356*cf5a6c84SAndroid Build Coastguard WorkerConfig.in.</p> 1357*cf5a6c84SAndroid Build Coastguard Worker 1358*cf5a6c84SAndroid Build Coastguard Worker<p>See <a href="#adding">adding a new command</a> for details on the 1359*cf5a6c84SAndroid Build Coastguard Workerlayout of a command file.</p> 1360*cf5a6c84SAndroid Build Coastguard Worker 1361*cf5a6c84SAndroid Build Coastguard Worker<a name="scripts"> 1362*cf5a6c84SAndroid Build Coastguard Worker<h2>Directory scripts/</h2> 1363*cf5a6c84SAndroid Build Coastguard Worker 1364*cf5a6c84SAndroid Build Coastguard Worker<p>Build infrastructure. The makefile calls scripts/make.sh for "make" 1365*cf5a6c84SAndroid Build Coastguard Workerand scripts/install.sh for "make install".</p> 1366*cf5a6c84SAndroid Build Coastguard Worker 1367*cf5a6c84SAndroid Build Coastguard Worker<p>There's also a test suite, "make test" calls make/test.sh, which runs all 1368*cf5a6c84SAndroid Build Coastguard Workerthe tests in make/test/*. You can run individual tests via 1369*cf5a6c84SAndroid Build Coastguard Worker"scripts/test.sh command", or "TEST_HOST=1 scripts/test.sh command" to run 1370*cf5a6c84SAndroid Build Coastguard Workerthat test against the host implementation instead of the toybox one.</p> 1371*cf5a6c84SAndroid Build Coastguard Worker 1372*cf5a6c84SAndroid Build Coastguard Worker<h3>scripts/cfg2files.sh</h3> 1373*cf5a6c84SAndroid Build Coastguard Worker 1374*cf5a6c84SAndroid Build Coastguard Worker<p>Run .config through this filter to get a list of enabled commands, which 1375*cf5a6c84SAndroid Build Coastguard Workeris turned into a list of files in toys via a sed invocation in the top level 1376*cf5a6c84SAndroid Build Coastguard WorkerMakefile. 1377*cf5a6c84SAndroid Build Coastguard Worker</p> 1378*cf5a6c84SAndroid Build Coastguard Worker 1379*cf5a6c84SAndroid Build Coastguard Worker<h2>Directory kconfig/</h2> 1380*cf5a6c84SAndroid Build Coastguard Worker 1381*cf5a6c84SAndroid Build Coastguard Worker<p>Menuconfig infrastructure copied from the Linux kernel a long time ago 1382*cf5a6c84SAndroid Build Coastguard Worker(version 2.6.16). See the 1383*cf5a6c84SAndroid Build Coastguard WorkerLinux kernel's Documentation/kbuild/kconfig-language.txt</p> 1384*cf5a6c84SAndroid Build Coastguard Worker 1385*cf5a6c84SAndroid Build Coastguard Worker<!-- todo 1386*cf5a6c84SAndroid Build Coastguard Worker 1387*cf5a6c84SAndroid Build Coastguard WorkerBetter OLDTOY and multiple command explanation. From Config.in: 1388*cf5a6c84SAndroid Build Coastguard Worker 1389*cf5a6c84SAndroid Build Coastguard Worker<p>A command with multiple names (or multiple similar commands implemented in 1390*cf5a6c84SAndroid Build Coastguard Workerthe same .c file) should have config symbols prefixed with the name of their 1391*cf5a6c84SAndroid Build Coastguard WorkerC file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names 1392*cf5a6c84SAndroid Build Coastguard Workerhave config symbols they must be options (symbols with an underscore and 1393*cf5a6c84SAndroid Build Coastguard Workersuffix) to the NEWTOY() name. (See generated/toylist.h)</p> 1394*cf5a6c84SAndroid Build Coastguard Worker--> 1395*cf5a6c84SAndroid Build Coastguard Worker 1396*cf5a6c84SAndroid Build Coastguard Worker<!--#include file="footer.html" --> 1397