10f66f451Sopenharmony_ci<html><head><title>toybox source code walkthrough</title></head> 20f66f451Sopenharmony_ci<!--#include file="header.html" --> 30f66f451Sopenharmony_ci 40f66f451Sopenharmony_ci<p><h1><a name="style" /><a href="#style">Code style</a></h1></p> 50f66f451Sopenharmony_ci 60f66f451Sopenharmony_ci<p>The primary goal of toybox is _simple_ code. Keeping the code small is 70f66f451Sopenharmony_cisecond, with speed and lots of features coming in somewhere after that. 80f66f451Sopenharmony_ci(For more on that, see the <a href=design.html>design</a> page.)</p> 90f66f451Sopenharmony_ci 100f66f451Sopenharmony_ci<p>A simple implementation usually takes up fewer lines of source code, 110f66f451Sopenharmony_cimeaning more code can fit on the screen at once, meaning the programmer can 120f66f451Sopenharmony_cisee more of it on the screen and thus keep more if in their head at once. 130f66f451Sopenharmony_ciThis helps code auditing and thus reduces bugs. That said, sometimes being 140f66f451Sopenharmony_cimore explicit is preferable to being clever enough to outsmart yourself: 150f66f451Sopenharmony_cidon't be so terse your code is unreadable.</p> 160f66f451Sopenharmony_ci 170f66f451Sopenharmony_ci<p>Toybox has an actual coding style guide over on 180f66f451Sopenharmony_ci<a href=design.html#codestyle>the design page</a>, but in general we just 190f66f451Sopenharmony_ciwant the code to be consistent.</p> 200f66f451Sopenharmony_ci 210f66f451Sopenharmony_ci<p><h1><a name="building" /><a href="#building">Building Toybox</a></h1></p> 220f66f451Sopenharmony_ci 230f66f451Sopenharmony_ci<p>Toybox is configured using the 240f66f451Sopenharmony_ci<a href=https://github.com/torvalds/linux/blob/v2.6.16/Documentation/kbuild/kconfig-language.txt>Kconfig language</a> pioneered by the Linux 250f66f451Sopenharmony_cikernel, and adopted by many other projects (buildroot, OpenEmbedded, etc). 260f66f451Sopenharmony_ciThis generates a ".config" file containing the selected options, which 270f66f451Sopenharmony_cicontrols which features are included when compiling toybox.</p> 280f66f451Sopenharmony_ci 290f66f451Sopenharmony_ci<p>Each configuration option has a default value. The defaults indicate the 300f66f451Sopenharmony_ci"maximum sane configuration", I.E. if the feature defaults to "n" then it 310f66f451Sopenharmony_cieither isn't complete or is a special-purpose option (such as debugging 320f66f451Sopenharmony_cicode) that isn't intended for general purpose use.</p> 330f66f451Sopenharmony_ci 340f66f451Sopenharmony_ci<p>For a more compact human-editable version .config files, you can use the 350f66f451Sopenharmony_ci<a href=http://landley.net/aboriginal/FAQ.html#dev_miniconfig>miniconfig</a> 360f66f451Sopenharmony_ciformat.</p> 370f66f451Sopenharmony_ci 380f66f451Sopenharmony_ci<p>The standard build invocation is:</p> 390f66f451Sopenharmony_ci 400f66f451Sopenharmony_ci<ul> 410f66f451Sopenharmony_ci<li>make defconfig #(or menuconfig)</li> 420f66f451Sopenharmony_ci<li>make</li> 430f66f451Sopenharmony_ci<li>make install</li> 440f66f451Sopenharmony_ci</ul> 450f66f451Sopenharmony_ci 460f66f451Sopenharmony_ci<p>Type "make help" to see all available build options.</p> 470f66f451Sopenharmony_ci 480f66f451Sopenharmony_ci<p>The file "configure" contains a number of environment variable definitions 490f66f451Sopenharmony_ciwhich influence the build, such as specifying which compiler to use or where 500f66f451Sopenharmony_cito install the resulting binaries. This file is included by the build, but 510f66f451Sopenharmony_ciaccepts existing definitions of the environment variables, so it may be sourced 520f66f451Sopenharmony_cior modified by the developer before building and the definitions exported 530f66f451Sopenharmony_cito the environment will take precedence.</p> 540f66f451Sopenharmony_ci 550f66f451Sopenharmony_ci<p>(To clarify: ".config" lists the features selected by defconfig/menuconfig, 560f66f451Sopenharmony_ciI.E. "what to build", and "configure" describes the build and installation 570f66f451Sopenharmony_cienvironment, I.E. "how to build it".)</p> 580f66f451Sopenharmony_ci 590f66f451Sopenharmony_ci<p>By default "make install" puts files in /usr/toybox. Adding this to the 600f66f451Sopenharmony_ci$PATH is up to you. The environment variable $PREFIX can change the 610f66f451Sopenharmony_ciinstall location, ala "PREFIX=/usr/local/bin make install".</p> 620f66f451Sopenharmony_ci 630f66f451Sopenharmony_ci<p>If you need an unstripped (debug) version of any of these binaries, 640f66f451Sopenharmony_cilook in generated/unstripped.</p> 650f66f451Sopenharmony_ci 660f66f451Sopenharmony_ci<p><h1><a name="running"><a href="#running">Running a command</a></h1></p> 670f66f451Sopenharmony_ci 680f66f451Sopenharmony_ci<h2>main</h2> 690f66f451Sopenharmony_ci 700f66f451Sopenharmony_ci<p>The toybox main() function is at the end of main.c at the top level. It has 710f66f451Sopenharmony_citwo possible codepaths, only one of which is configured into any given build 720f66f451Sopenharmony_ciof toybox.</p> 730f66f451Sopenharmony_ci 740f66f451Sopenharmony_ci<p>If CONFIG_SINGLE is selected, toybox is configured to contain only a single 750f66f451Sopenharmony_cicommand, so most of the normal setup can be skipped. In this case the 760f66f451Sopenharmony_cimultiplexer isn't used, instead main() calls toy_singleinit() (also in main.c) 770f66f451Sopenharmony_cito set up global state and parse command line arguments, calls the command's 780f66f451Sopenharmony_cimain 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 790f66f451Sopenharmony_ciit flushes stdout (detecting error) and returns toys.exitval.</p> 800f66f451Sopenharmony_ci 810f66f451Sopenharmony_ci<p>When CONFIG_SINGLE is not selected, main() uses basename() to find the 820f66f451Sopenharmony_ciname it was run as, shifts its argument list one to the right so it lines up 830f66f451Sopenharmony_ciwith where the multiplexer function expects it, and calls toybox_main(). This 840f66f451Sopenharmony_cileverages the multiplexer command's infrastructure to find and run the 850f66f451Sopenharmony_ciappropriate command. (A command name starting with "toybox" will 860f66f451Sopenharmony_cirecursively call toybox_main(); you can go "./toybox toybox toybox toybox ls" 870f66f451Sopenharmony_ciif you want to...)</p> 880f66f451Sopenharmony_ci 890f66f451Sopenharmony_ci<h2>toybox_main</h2> 900f66f451Sopenharmony_ci 910f66f451Sopenharmony_ci<p>The toybox_main() function is also in main,c. It handles a possible 920f66f451Sopenharmony_ci--help option ("toybox --help ls"), prints the list of available commands if no 930f66f451Sopenharmony_ciarguments were provided to the multiplexer (or with full path names if any 940f66f451Sopenharmony_ciother option is provided before a command name, ala "toybox --list"). 950f66f451Sopenharmony_ciOtherwise it calls toy_exec() on its argument list.</p> 960f66f451Sopenharmony_ci 970f66f451Sopenharmony_ci<p>Note that the multiplexer is the first entry in toy_list (the rest of the 980f66f451Sopenharmony_cilist is sorted alphabetically to allow binary search), so toybox_main can 990f66f451Sopenharmony_cicheat and just grab the first entry to quickly set up its context without 1000f66f451Sopenharmony_cisearching. Since all command names go through the multiplexer at least once 1010f66f451Sopenharmony_ciin the non-TOYBOX_SINGLE case, this avoids a redundant search of 1020f66f451Sopenharmony_cithe list.</p> 1030f66f451Sopenharmony_ci 1040f66f451Sopenharmony_ci<p>The toy_exec() function is also in main.c. It performs toy_find() to 1050f66f451Sopenharmony_ciperform a binary search on the toy_list array to look up the command's 1060f66f451Sopenharmony_cientry by name and saves it in the global variable which, calls toy_init() 1070f66f451Sopenharmony_cito parse command line arguments and set up global state (using which->options), 1080f66f451Sopenharmony_ciand calls the appropriate command's main() function (which->toy_main). On 1090f66f451Sopenharmony_cireturn it flushes all pending ansi FILE * I/O, detects if stdout had an 1100f66f451Sopenharmony_cierror, and then calls xexit() (which uses toys.exitval).</p> 1110f66f451Sopenharmony_ci 1120f66f451Sopenharmony_ci<p><h1><a name="infrastructure" /><a href="#infrastructure">Infrastructure</a></h1></p> 1130f66f451Sopenharmony_ci 1140f66f451Sopenharmony_ci<p>The toybox source code is in following directories:</p> 1150f66f451Sopenharmony_ci<ul> 1160f66f451Sopenharmony_ci<li>The <a href="#top">top level directory</a> contains the file main.c (were 1170f66f451Sopenharmony_ciexecution starts), the header file toys.h (included by every command), and 1180f66f451Sopenharmony_ciother global infrastructure.</li> 1190f66f451Sopenharmony_ci<li>The <a href="#lib">lib directory</a> contains common functions shared by 1200f66f451Sopenharmony_cimultiple commands:</li> 1210f66f451Sopenharmony_ci<ul> 1220f66f451Sopenharmony_ci<li><a href="#lib_lib">lib/lib.c</a></li> 1230f66f451Sopenharmony_ci<li><a href="#lib_xwrap">lib/xwrap.c</a></li> 1240f66f451Sopenharmony_ci<li><a href="#lib_llist">lib/llist.c</a></li> 1250f66f451Sopenharmony_ci<li><a href="#lib_args">lib/args.c</a></li> 1260f66f451Sopenharmony_ci<li><a href="#lib_dirtree">lib/dirtree.c</a></li> 1270f66f451Sopenharmony_ci</ul> 1280f66f451Sopenharmony_ci<li>The <a href="#toys">toys directory</a> contains the C files implementating 1290f66f451Sopenharmony_cieach command. Currently it contains five subdirectories categorizing the 1300f66f451Sopenharmony_cicommands: posix, lsb, other, example, and pending.</li> 1310f66f451Sopenharmony_ci<li>The <a href="#scripts">scripts directory</a> contains the build and 1320f66f451Sopenharmony_citest infrastructure.</li> 1330f66f451Sopenharmony_ci<li>The <a href="#kconfig">kconfig directory</a> contains the configuration 1340f66f451Sopenharmony_ciinfrastructure implementing menuconfig (copied from the Linux kernel).</li> 1350f66f451Sopenharmony_ci<li>The <a href="#generated">generated directory</a> contains intermediate 1360f66f451Sopenharmony_cifiles generated from other parts of the source code.</li> 1370f66f451Sopenharmony_ci<li>The <a href="#tests">tests directory</a> contains the test suite. 1380f66f451Sopenharmony_ciNOSPACE=1 to allow tests to pass with diff -b</li> 1390f66f451Sopenharmony_ci</ul> 1400f66f451Sopenharmony_ci 1410f66f451Sopenharmony_ci<a name="adding" /> 1420f66f451Sopenharmony_ci<p><h1><a href="#adding">Adding a new command</a></h1></p> 1430f66f451Sopenharmony_ci<p>To add a new command to toybox, add a C file implementing that command to 1440f66f451Sopenharmony_cione of the subdirectories under the toys directory. No other files need to 1450f66f451Sopenharmony_cibe modified; the build extracts all the information it needs (such as command 1460f66f451Sopenharmony_ciline arguments) from specially formatted comments and macros in the C file. 1470f66f451Sopenharmony_ci(See the description of the <a href="#generated">"generated" directory</a> 1480f66f451Sopenharmony_cifor details.)</p> 1490f66f451Sopenharmony_ci 1500f66f451Sopenharmony_ci<p>Currently there are five subdirectories under "toys", one for commands 1510f66f451Sopenharmony_cidefined by the POSIX standard, one for commands defined by the Linux Standard 1520f66f451Sopenharmony_ciBase, an "other" directory for commands not covered by an obvious standard, 1530f66f451Sopenharmony_cia directory of example commands (templates to use when starting new commands), 1540f66f451Sopenharmony_ciand a "pending" directory of commands that need further review/cleanup 1550f66f451Sopenharmony_cibefore moving to one of the other directories (run these at your own risk, 1560f66f451Sopenharmony_cicleanup patches welcome). 1570f66f451Sopenharmony_ciThese directories are just for developer convenience sorting the commands, 1580f66f451Sopenharmony_cithe directories are otherwise functionally identical. To add a new category, 1590f66f451Sopenharmony_cicreate the appropriate directory with a README file in it whose first line 1600f66f451Sopenharmony_ciis the description menuconfig should use for the directory.)</p> 1610f66f451Sopenharmony_ci 1620f66f451Sopenharmony_ci<p>An easy way to start a new command is copy the file "toys/example/hello.c" 1630f66f451Sopenharmony_cito the name of the new command, and modify this copy to implement the new 1640f66f451Sopenharmony_cicommand (more or less by turning every instance of "hello" into the 1650f66f451Sopenharmony_ciname of your command, updating the command line arguments, globals, and 1660f66f451Sopenharmony_cihelp data, and then filling out its "main" function with code that does 1670f66f451Sopenharmony_cisomething interesting).</p> 1680f66f451Sopenharmony_ci 1690f66f451Sopenharmony_ci<p>You could also start with "toys/example/skeleton.c", which provides a lot 1700f66f451Sopenharmony_cimore example code (showing several variants of command line option 1710f66f451Sopenharmony_ciparsing, how to implement multiple commands in the same file, and so on). 1720f66f451Sopenharmony_ciBut usually it's just more stuff to delete.</p> 1730f66f451Sopenharmony_ci 1740f66f451Sopenharmony_ci<p>Here's a checklist of steps to turn hello.c into another command:</p> 1750f66f451Sopenharmony_ci 1760f66f451Sopenharmony_ci<ul> 1770f66f451Sopenharmony_ci<li><p>First "cp toys/example/hello.c toys/other/yourcommand.c" and open 1780f66f451Sopenharmony_cithe new file in your preferred text editor.</p> 1790f66f451Sopenharmony_ci<ul><li><p>Note that the 1800f66f451Sopenharmony_ciname of the new file is significant: it's the name of the new command you're 1810f66f451Sopenharmony_ciadding to toybox. The build includes all *.c files under toys/*/ whose 1820f66f451Sopenharmony_cinames are a case insensitive match for an enabled config symbol. So 1830f66f451Sopenharmony_citoys/posix/cat.c only gets included if you have "CAT=y" in ".config".</p></li> 1840f66f451Sopenharmony_ci</ul></p></li> 1850f66f451Sopenharmony_ci 1860f66f451Sopenharmony_ci<li><p>Change the one line comment at the top of the file (currently 1870f66f451Sopenharmony_ci"hello.c - A hello world program") to describe your new file.</p></li> 1880f66f451Sopenharmony_ci 1890f66f451Sopenharmony_ci<li><p>Change the copyright notice to your name, email, and the current 1900f66f451Sopenharmony_ciyear.</p></li> 1910f66f451Sopenharmony_ci 1920f66f451Sopenharmony_ci<li><p>Give a URL to the relevant standards document, where applicable. 1930f66f451Sopenharmony_ci(Sample links to SUSv4, LSB, IETF RFC, and man7.org are provided, feel free to 1940f66f451Sopenharmony_cilink to other documentation or standards as appropriate.)</p></li> 1950f66f451Sopenharmony_ci 1960f66f451Sopenharmony_ci<li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. 1970f66f451Sopenharmony_ciThe NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a> 1980f66f451Sopenharmony_cistructure. The arguments to the NEWTOY macro are:</p> 1990f66f451Sopenharmony_ci 2000f66f451Sopenharmony_ci<ol> 2010f66f451Sopenharmony_ci<li><p>the name used to run your command</p></li> 2020f66f451Sopenharmony_ci<li><p>the command line argument <a href="#lib_args">option parsing string</a> (0 if none)</p></li> 2030f66f451Sopenharmony_ci<li><p>a bitfield of TOYFLAG values 2040f66f451Sopenharmony_ci(defined in toys.h) providing additional information such as where your 2050f66f451Sopenharmony_cicommand should be installed on a running system, whether to blank umask 2060f66f451Sopenharmony_cibefore running, whether or not the command must run as root (and thus should 2070f66f451Sopenharmony_ciretain root access if installed SUID), and so on.</p></li> 2080f66f451Sopenharmony_ci</ol> 2090f66f451Sopenharmony_ci</li> 2100f66f451Sopenharmony_ci 2110f66f451Sopenharmony_ci<li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the 2120f66f451Sopenharmony_cicomment block) to supply your command's configuration and help 2130f66f451Sopenharmony_ciinformation. The uppper case config symbols are used by menuconfig, and are 2140f66f451Sopenharmony_cialso what the CFG_ and USE_() macros are generated from (see [TODO]). The 2150f66f451Sopenharmony_cihelp information here is used by menuconfig, and also by the "help" command to 2160f66f451Sopenharmony_cidescribe your new command. (See [TODO] for details.) By convention, 2170f66f451Sopenharmony_ciunfinished commands default to "n" and finished commands default to "y", 2180f66f451Sopenharmony_ciso "make defconfig" selects all finished commands. (Note, "finished" means 2190f66f451Sopenharmony_ci"ready to be used", not that it'll never change again.)<p> 2200f66f451Sopenharmony_ci 2210f66f451Sopenharmony_ci<p>Each help block should start with a "usage: yourcommand" line explaining 2220f66f451Sopenharmony_ciany command line arguments added by this config option. The "help" command 2230f66f451Sopenharmony_cioutputs this text, and scripts/config2help.c in the build infrastructure 2240f66f451Sopenharmony_cicollates these usage lines for commands with multiple configuration 2250f66f451Sopenharmony_cioptions when producing generated/help.h.</p> 2260f66f451Sopenharmony_ci</li> 2270f66f451Sopenharmony_ci 2280f66f451Sopenharmony_ci<li><p>Change the "#define FOR_hello" line to "#define FOR_yourcommand" right 2290f66f451Sopenharmony_cibefore the "#include <toys.h>". (This selects the appropriate FLAG_ macros and 2300f66f451Sopenharmony_cidoes a "#define TT this.yourcommand" so you can access the global variables 2310f66f451Sopenharmony_ciout of the space-saving union of structures. If you aren't using any command 2320f66f451Sopenharmony_ciflag bits and aren't defining a GLOBAL block, you can delete this line.)</p></li> 2330f66f451Sopenharmony_ci 2340f66f451Sopenharmony_ci<li><p>Update the GLOBALS() macro to contain your command's global 2350f66f451Sopenharmony_civariables. If your command has no global variables, delete this macro.</p> 2360f66f451Sopenharmony_ci 2370f66f451Sopenharmony_ci<p>Variables in the GLOBALS() block are are stored in a space saving 2380f66f451Sopenharmony_ci<a href="#toy_union">union of structures</a> format, which may be accessed 2390f66f451Sopenharmony_ciusing the TT macro as if TT were a global structure (so TT.membername). 2400f66f451Sopenharmony_ciIf you specified two-character command line arguments in 2410f66f451Sopenharmony_ciNEWTOY(), the first few global variables will be initialized by the automatic 2420f66f451Sopenharmony_ciargument parsing logic, and the type and order of these variables must 2430f66f451Sopenharmony_cicorrespond to the arguments specified in NEWTOY(). 2440f66f451Sopenharmony_ci(See <a href="#lib_args">lib/args.c</a> for details.)</p> 2450f66f451Sopenharmony_ci 2460f66f451Sopenharmony_ci<blockquote><p>NOTE: the GLOBALS() block creates a "this.filename" entry 2470f66f451Sopenharmony_ciin generated/globals.h. If your toys/*/filename.c does not match the first 2480f66f451Sopenharmony_cicommand name, you'll need to "#define TT this.filename" yourself before 2490f66f451Sopenharmony_ci#including toys.h if you want to use TT globals</p></blockquote> 2500f66f451Sopenharmony_ci</li> 2510f66f451Sopenharmony_ci 2520f66f451Sopenharmony_ci<li><p>Rename hello_main() to yourcommand_main(). This is the main() function 2530f66f451Sopenharmony_ciwhere execution of your command starts. Your command line options are 2540f66f451Sopenharmony_cialready sorted into this.optflags, this.optargs, this.optc, and the GLOBALS() 2550f66f451Sopenharmony_cias appropriate by the time this function is called. (See 2560f66f451Sopenharmony_ci<a href="#lib_args">get_optflags()</a> for details.)</p></li> 2570f66f451Sopenharmony_ci 2580f66f451Sopenharmony_ci<li><p>Switch on TOYBOX_DEBUG in menuconfig (toybox global settings menu) 2590f66f451Sopenharmony_cithe first time you build and run your new command. If anything is wrong 2600f66f451Sopenharmony_ciwith your option string, that will give you error messages.</p> 2610f66f451Sopenharmony_ci 2620f66f451Sopenharmony_ci<p>Otherwise it'll just segfault without 2630f66f451Sopenharmony_ciexplanation when it falls off the end because it didn't find a matching 2640f66f451Sopenharmony_ciend parantheses for a longopt, or you put a nonexistent option in a square 2650f66f451Sopenharmony_cibracket grouping... Since these kind of errors can only be caused by a 2660f66f451Sopenharmony_cideveloper, not by end users, we don't normally want runtime checks for 2670f66f451Sopenharmony_cithem. Once you're happy with your option string, you can switch TOYBOX_DEBUG 2680f66f451Sopenharmony_ciback off.</p></li> 2690f66f451Sopenharmony_ci</ul> 2700f66f451Sopenharmony_ci 2710f66f451Sopenharmony_ci<a name="headers" /><h2><a href="#headers">Headers.</a></h2> 2720f66f451Sopenharmony_ci 2730f66f451Sopenharmony_ci<p>Commands are implemented as self-contained .c files, and generally don't 2740f66f451Sopenharmony_cihave their own .h files. If it's common code put it in lib/, and if it's 2750f66f451Sopenharmony_cisomething like a local structure definition just put it in the command's .c 2760f66f451Sopenharmony_cifile. If it would only ever be #included from one place, inline it. 2770f66f451Sopenharmony_ci(The line between implementing multiple commands in a C file via OLDTOY() 2780f66f451Sopenharmony_cito share infrastructure and moving that shared infrastructure to lib/ is a 2790f66f451Sopenharmony_cijudgement call. Try to figure out which is simplest.)</p> 2800f66f451Sopenharmony_ci 2810f66f451Sopenharmony_ci<p>The top level toys.h should #include all the standard (posix) headers 2820f66f451Sopenharmony_cithat any command uses. (Partly this is friendly to ccache and partly this 2830f66f451Sopenharmony_cimakes the command implementations shorter.) Individual commands should only 2840f66f451Sopenharmony_cineed to include nonstandard headers that might prevent that command from 2850f66f451Sopenharmony_cibuilding in some context we'd care about (and thus requiring that command to 2860f66f451Sopenharmony_cibe disabled to avoid a build break).</p> 2870f66f451Sopenharmony_ci 2880f66f451Sopenharmony_ci<p>Target-specific stuff (differences between compiler versions, libc versions, 2890f66f451Sopenharmony_cior operating systems) should be confined to lib/portability.h and 2900f66f451Sopenharmony_cilib/portability.c. (There's even some minimal compile-time environment probing 2910f66f451Sopenharmony_cithat writes data to generated/portability.h, see scripts/genconfig.sh.)</p> 2920f66f451Sopenharmony_ci 2930f66f451Sopenharmony_ci<p>Only include <linux/*.h> headers from individual commands (not from other 2940f66f451Sopenharmony_ciheaders), and only if you really need to. Data that varies per architecture 2950f66f451Sopenharmony_ciis a good reason to include a header. If you just need a couple constants 2960f66f451Sopenharmony_cithat haven't changed since the 1990's, it's ok to #define them yourself or 2970f66f451Sopenharmony_cijust use the constant inline with a comment explaining what it is. (A 2980f66f451Sopenharmony_ci#define that's only used once isn't really helping.)</p> 2990f66f451Sopenharmony_ci 3000f66f451Sopenharmony_ci<p><a name="top" /><h1><a href="#top">Top level directory.</a></h1></p> 3010f66f451Sopenharmony_ci 3020f66f451Sopenharmony_ci<p>This directory contains global infrastructure.</p> 3030f66f451Sopenharmony_ci 3040f66f451Sopenharmony_ci<h3>toys.h</h3> 3050f66f451Sopenharmony_ci<p>Each command #includes "toys.h" as part of its standard prolog. It 3060f66f451Sopenharmony_cimay "#define FOR_commandname" before doing so to get some extra entries 3070f66f451Sopenharmony_cispecific to this command.</p> 3080f66f451Sopenharmony_ci 3090f66f451Sopenharmony_ci<p>This file sucks in most of the commonly used standard #includes, so 3100f66f451Sopenharmony_ciindividual files can just #include "toys.h" and not have to worry about 3110f66f451Sopenharmony_cistdargs.h and so on. Individual commands still need to #include 3120f66f451Sopenharmony_cispecial-purpose headers that may not be present on all systems (and thus would 3130f66f451Sopenharmony_ciprevent toybox from building that command on such a system with that command 3140f66f451Sopenharmony_cienabled). Examples include regex support, any "linux/" or "asm/" headers, mtab 3150f66f451Sopenharmony_cisupport (mntent.h and sys/mount.h), and so on.</p> 3160f66f451Sopenharmony_ci 3170f66f451Sopenharmony_ci<p>The toys.h header also defines structures for most of the global variables 3180f66f451Sopenharmony_ciprovided to each command by toybox_main(). These are described in 3190f66f451Sopenharmony_cidetail in the description for main.c, where they are initialized.</p> 3200f66f451Sopenharmony_ci 3210f66f451Sopenharmony_ci<p>The global variables are grouped into structures (and a union) for space 3220f66f451Sopenharmony_cisavings, to more easily track the amount of memory consumed by them, 3230f66f451Sopenharmony_ciso that they may be automatically cleared/initialized as needed, and so 3240f66f451Sopenharmony_cithat access to global variables is more easily distinguished from access to 3250f66f451Sopenharmony_cilocal variables.</p> 3260f66f451Sopenharmony_ci 3270f66f451Sopenharmony_ci<h3>main.c</h3> 3280f66f451Sopenharmony_ci<p>Contains the main() function where execution starts, plus 3290f66f451Sopenharmony_cicommon infrastructure to initialize global variables and select which command 3300f66f451Sopenharmony_cito run. The "toybox" multiplexer command also lives here. (This is the 3310f66f451Sopenharmony_cionly command defined outside of the toys directory.)</p> 3320f66f451Sopenharmony_ci 3330f66f451Sopenharmony_ci<p>Execution starts in main() which trims any path off of the first command 3340f66f451Sopenharmony_ciname and calls toybox_main(), which calls toy_exec(), which calls toy_find() 3350f66f451Sopenharmony_ciand toy_init() before calling the appropriate command's function from 3360f66f451Sopenharmony_citoy_list[] (via toys.which->toy_main()). 3370f66f451Sopenharmony_ciIf the command is "toybox", execution recurses into toybox_main(), otherwise 3380f66f451Sopenharmony_cithe call goes to the appropriate commandname_main() from a C file in the toys 3390f66f451Sopenharmony_cidirectory.</p> 3400f66f451Sopenharmony_ci 3410f66f451Sopenharmony_ci<p>The following global variables are defined in main.c:</p> 3420f66f451Sopenharmony_ci<ul> 3430f66f451Sopenharmony_ci<a name="toy_list" /> 3440f66f451Sopenharmony_ci<li><p><b>struct toy_list toy_list[]</b> - array describing all the 3450f66f451Sopenharmony_cicommands currently configured into toybox. The first entry (toy_list[0]) is 3460f66f451Sopenharmony_cifor the "toybox" multiplexer command, which runs all the other built-in commands 3470f66f451Sopenharmony_ciwithout symlinks by using its first argument as the name of the command to 3480f66f451Sopenharmony_cirun and the rest as that command's argument list (ala "./toybox echo hello"). 3490f66f451Sopenharmony_ciThe remaining entries are the commands in alphabetical order (for efficient 3500f66f451Sopenharmony_cibinary search).</p> 3510f66f451Sopenharmony_ci 3520f66f451Sopenharmony_ci<p>This is a read-only array initialized at compile time by 3530f66f451Sopenharmony_cidefining macros and #including generated/newtoys.h.</p> 3540f66f451Sopenharmony_ci 3550f66f451Sopenharmony_ci<p>Members of struct toy_list (defined in "toys.h") include:</p> 3560f66f451Sopenharmony_ci<ul> 3570f66f451Sopenharmony_ci<li><p>char *<b>name</b> - the name of this command.</p></li> 3580f66f451Sopenharmony_ci<li><p>void (*<b>toy_main</b>)(void) - function pointer to run this 3590f66f451Sopenharmony_cicommand.</p></li> 3600f66f451Sopenharmony_ci<li><p>char *<b>options</b> - command line option string (used by 3610f66f451Sopenharmony_ciget_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and 3620f66f451Sopenharmony_cientries in the toy's GLOBALS struct). When this is NULL, no option 3630f66f451Sopenharmony_ciparsing is done before calling toy_main().</p></li> 3640f66f451Sopenharmony_ci<li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p> 3650f66f451Sopenharmony_ci 3660f66f451Sopenharmony_ci<ul> 3670f66f451Sopenharmony_ci<li><b>TOYFLAG_USR</b> - Install this command under /usr</li> 3680f66f451Sopenharmony_ci<li><b>TOYFLAG_BIN</b> - Install this command under /bin</li> 3690f66f451Sopenharmony_ci<li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li> 3700f66f451Sopenharmony_ci<li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li> 3710f66f451Sopenharmony_ci<li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li> 3720f66f451Sopenharmony_ci<li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li> 3730f66f451Sopenharmony_ci<li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li> 3740f66f451Sopenharmony_ci</ul> 3750f66f451Sopenharmony_ci<br> 3760f66f451Sopenharmony_ci 3770f66f451Sopenharmony_ci<p>These flags are combined with | (or). For example, to install a command 3780f66f451Sopenharmony_ciin /usr/bin, or together TOYFLAG_USR|TOYFLAG_BIN.</p> 3790f66f451Sopenharmony_ci</ul> 3800f66f451Sopenharmony_ci</li> 3810f66f451Sopenharmony_ci 3820f66f451Sopenharmony_ci<li><p><b>struct toy_context toys</b> - global structure containing information 3830f66f451Sopenharmony_cicommon to all commands, initializd by toy_init() and defined in "toys.h". 3840f66f451Sopenharmony_ciMembers of this structure include:</p> 3850f66f451Sopenharmony_ci<ul> 3860f66f451Sopenharmony_ci<li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list 3870f66f451Sopenharmony_cistructure. Mostly used to grab the name of the running command 3880f66f451Sopenharmony_ci(toys->which.name).</p> 3890f66f451Sopenharmony_ci</li> 3900f66f451Sopenharmony_ci<li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The 3910f66f451Sopenharmony_cierror_exit() functions will return 1 if this is zero, otherwise they'll 3920f66f451Sopenharmony_cireturn this value.</p></li> 3930f66f451Sopenharmony_ci<li><p>char **<b>argv</b> - "raw" command line options, I.E. the original 3940f66f451Sopenharmony_ciunmodified string array passed in to main(). Note that modifying this changes 3950f66f451Sopenharmony_ci"ps" output, and is not recommended. This array is null terminated; a NULL 3960f66f451Sopenharmony_cientry indicates the end of the array.</p> 3970f66f451Sopenharmony_ci<p>Most commands don't use this field, instead the use optargs, optflags, 3980f66f451Sopenharmony_ciand the fields in the GLOBALS struct initialized by get_optflags().</p> 3990f66f451Sopenharmony_ci</li> 4000f66f451Sopenharmony_ci<li><p>unsigned <b>optflags</b> - Command line option flags, set by 4010f66f451Sopenharmony_ci<a href="#lib_args">get_optflags()</a>. Indicates which of the command line options listed in 4020f66f451Sopenharmony_citoys->which.options occurred this time.</p> 4030f66f451Sopenharmony_ci 4040f66f451Sopenharmony_ci<p>The rightmost command line argument listed in toys->which.options sets bit 4050f66f451Sopenharmony_ci1, the next one sets bit 2, and so on. This means the bits are set in the same 4060f66f451Sopenharmony_ciorder the binary digits would be listed if typed out as a string. For example, 4070f66f451Sopenharmony_cithe option string "abcd" would parse the command line "-c" to set optflags to 2, 4080f66f451Sopenharmony_ci"-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).</p> 4090f66f451Sopenharmony_ci 4100f66f451Sopenharmony_ci<p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2, 4110f66f451Sopenharmony_cib=4, a=8. Punctuation after a letter initializes global variables at the 4120f66f451Sopenharmony_cistart of the GLOBALS() block (see <a href="#toy_union">union toy_union this</a> 4130f66f451Sopenharmony_cifor details).</p> 4140f66f451Sopenharmony_ci 4150f66f451Sopenharmony_ci<p>The build infrastructure creates FLAG_ macros for each option letter, 4160f66f451Sopenharmony_cicorresponding to the bit position, so you can check (toys.optflags & FLAG_x) 4170f66f451Sopenharmony_cito see if a flag was specified. (The correct set of FLAG_ macros is selected 4180f66f451Sopenharmony_ciby defining FOR_mycommand before #including toys.h. The macros live in 4190f66f451Sopenharmony_citoys/globals.h which is generated by scripts/make.sh.)</p> 4200f66f451Sopenharmony_ci 4210f66f451Sopenharmony_ci<p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p> 4220f66f451Sopenharmony_ci 4230f66f451Sopenharmony_ci</li> 4240f66f451Sopenharmony_ci<li><p>char **<b>optargs</b> - Null terminated array of arguments left over 4250f66f451Sopenharmony_ciafter get_optflags() removed all the ones it understood. Note: optarg[0] is 4260f66f451Sopenharmony_cithe first argument, not the command name. Use toys.which->name for the command 4270f66f451Sopenharmony_ciname.</p></li> 4280f66f451Sopenharmony_ci<li><p>int <b>optc</b> - Optarg count, equivalent to argc but for 4290f66f451Sopenharmony_cioptargs[].<p></li> 4300f66f451Sopenharmony_ci</ul> 4310f66f451Sopenharmony_ci 4320f66f451Sopenharmony_ci<a name="toy_union" /> 4330f66f451Sopenharmony_ci<li><p><b>union toy_union this</b> - Union of structures containing each 4340f66f451Sopenharmony_cicommand's global variables.</p> 4350f66f451Sopenharmony_ci 4360f66f451Sopenharmony_ci<p>Global variables are useful: they reduce the overhead of passing extra 4370f66f451Sopenharmony_cicommand line arguments between functions, they conveniently start prezeroed to 4380f66f451Sopenharmony_cisave initialization costs, and the command line argument parsing infrastructure 4390f66f451Sopenharmony_cican also initialize global variables with its results.</p> 4400f66f451Sopenharmony_ci 4410f66f451Sopenharmony_ci<p>But since each toybox process can only run one command at a time, allocating 4420f66f451Sopenharmony_cispace for global variables belonging to other commands you aren't currently 4430f66f451Sopenharmony_cirunning would be wasteful.</p> 4440f66f451Sopenharmony_ci 4450f66f451Sopenharmony_ci<p>Toybox handles this by encapsulating each command's global variables in 4460f66f451Sopenharmony_cia structure, and declaring a union of those structures with a single global 4470f66f451Sopenharmony_ciinstance (called "this"). The GLOBALS() macro contains the global 4480f66f451Sopenharmony_civariables that should go in the current command's global structure. Each 4490f66f451Sopenharmony_civariable can then be accessed as "this.commandname.varname". 4500f66f451Sopenharmony_ciIf you #defined FOR_commandname before including toys.h, the macro TT is 4510f66f451Sopenharmony_ci#defined to this.commandname so the variable can then be accessed as 4520f66f451Sopenharmony_ci"TT.variable". See toys/hello.c for an example.</p> 4530f66f451Sopenharmony_ci 4540f66f451Sopenharmony_ci<p>A command that needs global variables should declare a structure to 4550f66f451Sopenharmony_cicontain them all, and add that structure to this union. A command should never 4560f66f451Sopenharmony_cideclare global variables outside of this, because such global variables would 4570f66f451Sopenharmony_ciallocate memory when running other commands that don't use those global 4580f66f451Sopenharmony_civariables.</p> 4590f66f451Sopenharmony_ci 4600f66f451Sopenharmony_ci<p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>, 4610f66f451Sopenharmony_cias specified by the options field off this command's toy_list entry. See 4620f66f451Sopenharmony_cithe get_optargs() description in lib/args.c for details.</p> 4630f66f451Sopenharmony_ci</li> 4640f66f451Sopenharmony_ci 4650f66f451Sopenharmony_ci<li><b>char toybuf[4096]</b> - a common scratch space buffer guaranteed 4660f66f451Sopenharmony_cito start zeroed, so commands don't need to allocate/initialize their own. 4670f66f451Sopenharmony_ciAny command is free to use this, and it should never be directly referenced 4680f66f451Sopenharmony_ciby functions in lib/ (although commands are free to pass toybuf in to a 4690f66f451Sopenharmony_cilibrary function as an argument).</li> 4700f66f451Sopenharmony_ci 4710f66f451Sopenharmony_ci<li><b>char libbuf[4096]</b> - like toybuf, but for use by common code in 4720f66f451Sopenharmony_cilib/*.c. Commands should never directly reference libbuf, and library 4730f66f451Sopenharmony_cicould should nnever directly reference toybuf.</li> 4740f66f451Sopenharmony_ci</ul> 4750f66f451Sopenharmony_ci 4760f66f451Sopenharmony_ci<p>The following functions are defined in main.c:</p> 4770f66f451Sopenharmony_ci<ul> 4780f66f451Sopenharmony_ci<li><p>struct toy_list *<b>toy_find</b>(char *name) - Return the toy_list 4790f66f451Sopenharmony_cistructure for this command name, or NULL if not found.</p></li> 4800f66f451Sopenharmony_ci<li><p>void <b>toy_init</b>(struct toy_list *which, char *argv[]) - fill out 4810f66f451Sopenharmony_cithe global toys structure, calling get_optargs() if necessary.</p></li> 4820f66f451Sopenharmony_ci<li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with 4830f66f451Sopenharmony_ciarguments.</p> 4840f66f451Sopenharmony_ci<p>Calls toy_find() on argv[0] (which must be just a command name 4850f66f451Sopenharmony_ciwithout path). Returns if it can't find this command, otherwise calls 4860f66f451Sopenharmony_citoy_init(), toys->which.toy_main(), and exit() instead of returning.</p> 4870f66f451Sopenharmony_ci 4880f66f451Sopenharmony_ci<p>Use the library function xexec() to fall back to external executables 4890f66f451Sopenharmony_ciin $PATH if toy_exec() can't find a built-in command. Note that toy_exec() 4900f66f451Sopenharmony_cidoes not strip paths before searching for a command, so "./command" will 4910f66f451Sopenharmony_cinever match an internal command.</li> 4920f66f451Sopenharmony_ci 4930f66f451Sopenharmony_ci<li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer 4940f66f451Sopenharmony_cicommand (I.E. "toybox"). Given a command name as its first argument, calls 4950f66f451Sopenharmony_citoy_exec() on its arguments. With no arguments, it lists available commands. 4960f66f451Sopenharmony_ciIf the first argument starts with "-" it lists each command with its default 4970f66f451Sopenharmony_ciinstall path prepended.</p></li> 4980f66f451Sopenharmony_ci 4990f66f451Sopenharmony_ci</ul> 5000f66f451Sopenharmony_ci 5010f66f451Sopenharmony_ci<h3>Config.in</h3> 5020f66f451Sopenharmony_ci 5030f66f451Sopenharmony_ci<p>Top level configuration file in a stylized variant of 5040f66f451Sopenharmony_ci<a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p> 5050f66f451Sopenharmony_ci 5060f66f451Sopenharmony_ci<p>These files are directly used by "make menuconfig" to select which commands 5070f66f451Sopenharmony_cito build into toybox (thus generating a .config file), and by 5080f66f451Sopenharmony_ciscripts/config2help.py to create generated/help.h.</p> 5090f66f451Sopenharmony_ci 5100f66f451Sopenharmony_ci<a name="generated" /> 5110f66f451Sopenharmony_ci<h1><a href="#generated">Temporary files:</a></h1> 5120f66f451Sopenharmony_ci 5130f66f451Sopenharmony_ci<p>There is one temporary file in the top level source directory:</p> 5140f66f451Sopenharmony_ci<ul> 5150f66f451Sopenharmony_ci<li><p><b>.config</b> - Configuration file generated by kconfig, indicating 5160f66f451Sopenharmony_ciwhich commands (and options to commands) are currently enabled. Used 5170f66f451Sopenharmony_cito make generated/config.h and determine which toys/*/*.c files to build.</p> 5180f66f451Sopenharmony_ci 5190f66f451Sopenharmony_ci<p>You can create a human readable "miniconfig" version of this file using 5200f66f451Sopenharmony_ci<a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these 5210f66f451Sopenharmony_ciinstructions</a>.</p> 5220f66f451Sopenharmony_ci</li> 5230f66f451Sopenharmony_ci</ul> 5240f66f451Sopenharmony_ci 5250f66f451Sopenharmony_ci<p><h2>Directory generated/</h2></p> 5260f66f451Sopenharmony_ci 5270f66f451Sopenharmony_ci<p>The remaining temporary files live in the "generated/" directory, 5280f66f451Sopenharmony_ciwhich is for files generated at build time from other source files.</p> 5290f66f451Sopenharmony_ci 5300f66f451Sopenharmony_ci<ul> 5310f66f451Sopenharmony_ci<li><p><b>generated/Config.in</b> - Kconfig entries for each command, included 5320f66f451Sopenharmony_cifrom the top level Config.in. The help text here is used to generate 5330f66f451Sopenharmony_cihelp.h.</p> 5340f66f451Sopenharmony_ci 5350f66f451Sopenharmony_ci<p>Each command has a configuration entry with an upper case version of 5360f66f451Sopenharmony_cithe command name. Options to commands start with the command 5370f66f451Sopenharmony_ciname followed by an underscore and the option name. Global options are attached 5380f66f451Sopenharmony_cito the "toybox" command, and thus use the prefix "TOYBOX_". This organization 5390f66f451Sopenharmony_ciis used by scripts/cfg2files to select which toys/*/*.c files to compile for a 5400f66f451Sopenharmony_cigiven .config.</p> 5410f66f451Sopenharmony_ci</li> 5420f66f451Sopenharmony_ci 5430f66f451Sopenharmony_ci<li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros, 5440f66f451Sopenharmony_cigenerated from .config by a sed invocation in scripts/make.sh.</p> 5450f66f451Sopenharmony_ci 5460f66f451Sopenharmony_ci<p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for 5470f66f451Sopenharmony_cidisabled symbols. This allows the use of normal if() statements to remove 5480f66f451Sopenharmony_cicode at compile time via the optimizer's dead code elimination (which removes 5490f66f451Sopenharmony_cifrom the binary any code that cannot be reached). This saves space without 5500f66f451Sopenharmony_cicluttering the code with #ifdefs or leading to configuration dependent build 5510f66f451Sopenharmony_cibreaks. (See the 1992 Usenix paper 5520f66f451Sopenharmony_ci<a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef 5530f66f451Sopenharmony_ciConsidered Harmful</a> for more information.)</p> 5540f66f451Sopenharmony_ci 5550f66f451Sopenharmony_ci<p>When you can't entirely avoid an #ifdef, the USE_SYMBOL(code) macro 5560f66f451Sopenharmony_ciprovides a less intrusive alternative, evaluating to the code in parentheses 5570f66f451Sopenharmony_ciwhen the symbol is enabled, and nothing when the symbol is disabled. This 5580f66f451Sopenharmony_ciis most commonly used around NEWTOY() declarations (so only the enabled 5590f66f451Sopenharmony_cicommands show up in toy_list), and in option strings. This can also be used 5600f66f451Sopenharmony_cifor things like varargs or structure members which can't always be 5610f66f451Sopenharmony_cieliminated by a simple test on CFG_SYMBOL. Remember, unlike CFG_SYMBOL 5620f66f451Sopenharmony_cithis is really just a variant of #ifdef, and can still result in configuration 5630f66f451Sopenharmony_cidependent build breaks. Use with caution.</p> 5640f66f451Sopenharmony_ci</li> 5650f66f451Sopenharmony_ci 5660f66f451Sopenharmony_ci<li><p><b>generated/flags.h</b> - FLAG_? macros indicating which command 5670f66f451Sopenharmony_ciline options were seen. The option parsing in lib/args.c sets bits in 5680f66f451Sopenharmony_citoys.optflags, which can be tested by anding with the appropriate FLAG_ 5690f66f451Sopenharmony_cimacro. (Bare longopts, which have no corresponding short option, will 5700f66f451Sopenharmony_cihave the longopt name after FLAG_. All others use the single letter short 5710f66f451Sopenharmony_cioption.)</p> 5720f66f451Sopenharmony_ci 5730f66f451Sopenharmony_ci<p>To get the appropriate macros for your command, #define FOR_commandname 5740f66f451Sopenharmony_cibefore #including toys.h. To switch macro sets (because you have an OLDTOY() 5750f66f451Sopenharmony_ciwith different options in the same .c file), #define CLEANUP_oldcommand 5760f66f451Sopenharmony_ciand also #define FOR_newcommand, then #include "generated/flags.h" to switch. 5770f66f451Sopenharmony_ci</p> 5780f66f451Sopenharmony_ci</li> 5790f66f451Sopenharmony_ci 5800f66f451Sopenharmony_ci<li><p><b>generated/globals.h</b> - 5810f66f451Sopenharmony_ciDeclares structures to hold the contents of each command's GLOBALS(), 5820f66f451Sopenharmony_ciand combines them into "global_union this". (Yes, the name was 5830f66f451Sopenharmony_cichosen to piss off C++ developers who think that C 5840f66f451Sopenharmony_ciis merely a subset of C++, not a language in its own right.)</p> 5850f66f451Sopenharmony_ci 5860f66f451Sopenharmony_ci<p>The union reuses the same memory for each command's global struct: 5870f66f451Sopenharmony_cisince only one command's globals are in use at any given time, collapsing 5880f66f451Sopenharmony_cithem together saves space. The headers #define TT to the appropriate 5890f66f451Sopenharmony_ci"this.commandname", so you can refer to the current command's global 5900f66f451Sopenharmony_civariables out of "this" as TT.variablename.</p> 5910f66f451Sopenharmony_ci 5920f66f451Sopenharmony_ci<p>The globals start zeroed, and the first few are filled out by the 5930f66f451Sopenharmony_cilib/args.c argument parsing code called from main.c.</p> 5940f66f451Sopenharmony_ci</li> 5950f66f451Sopenharmony_ci 5960f66f451Sopenharmony_ci<li><p><b>toys/help.h</b> - Help strings for use by the "help" command and 5970f66f451Sopenharmony_ci--help options. This file #defines a help_symbolname string for each 5980f66f451Sopenharmony_cisymbolname, but only the symbolnames matching command names get used 5990f66f451Sopenharmony_ciby show_help() in lib/help.c to display help for commands.</p> 6000f66f451Sopenharmony_ci 6010f66f451Sopenharmony_ci<p>This file is created by scripts/make.sh, which compiles scripts/config2help.c 6020f66f451Sopenharmony_ciinto the binary generated/config2help, and then runs it against the top 6030f66f451Sopenharmony_cilevel .config and Config.in files to extract the help text from each config 6040f66f451Sopenharmony_cientry and collate together dependent options.</p> 6050f66f451Sopenharmony_ci 6060f66f451Sopenharmony_ci<p>This file contains help text for all commands, regardless of current 6070f66f451Sopenharmony_ciconfiguration, but only the ones currently enabled in the .config file 6080f66f451Sopenharmony_ciwind up in the help_data[] array, and only the enabled dependent options 6090f66f451Sopenharmony_cihave their help text added to the command they depend on.</p> 6100f66f451Sopenharmony_ci</li> 6110f66f451Sopenharmony_ci 6120f66f451Sopenharmony_ci<li><p><b>generated/newtoys.h</b> - 6130f66f451Sopenharmony_ciAll the NEWTOY() and OLDTOY() macros from toys/*/*.c. The "toybox" multiplexer 6140f66f451Sopenharmony_ciis the first entry, the rest are in alphabetical order. Each line should be 6150f66f451Sopenharmony_ciinside an appropriate USE_ macro, so code that #includes this file only sees 6160f66f451Sopenharmony_cithe currently enabled commands.</p> 6170f66f451Sopenharmony_ci 6180f66f451Sopenharmony_ci<p>By #definining NEWTOY() to various things before #including this file, 6190f66f451Sopenharmony_ciit may be used to create function prototypes (in toys.h), initialize the 6200f66f451Sopenharmony_cihelp_data array (in lib/help.c), initialize the toy_list array (in main.c, 6210f66f451Sopenharmony_cithe alphabetical order lets toy_find() do a binary search, the exception to 6220f66f451Sopenharmony_cithe alphabetical order lets it use the multiplexer without searching), and so 6230f66f451Sopenharmony_cion. (It's even used to initialize the NEED_OPTIONS macro, which produces a 1 6240f66f451Sopenharmony_cior 0 for each command using command line option parsing, which is ORed together 6250f66f451Sopenharmony_cito allow compile-time dead code elimination to remove the whole of 6260f66f451Sopenharmony_cilib/args.c if nothing currently enabled is using it.)<p> 6270f66f451Sopenharmony_ci 6280f66f451Sopenharmony_ci<p>Each NEWTOY and OLDTOY macro contains the command name, command line 6290f66f451Sopenharmony_cioption string (telling lib/args.c how to parse command line options for 6300f66f451Sopenharmony_cithis command), recommended install location, and miscelaneous data such 6310f66f451Sopenharmony_cias whether this command should retain root permissions if installed suid.</p> 6320f66f451Sopenharmony_ci</li> 6330f66f451Sopenharmony_ci 6340f66f451Sopenharmony_ci<li><p><b>toys/oldtoys.h</b> - Macros with the command line option parsing 6350f66f451Sopenharmony_cistring for each NEWTOY. This allows an OLDTOY that's just an alias for an 6360f66f451Sopenharmony_ciexisting command to refer to the existing option string instead of 6370f66f451Sopenharmony_cihaving to repeat it.</p> 6380f66f451Sopenharmony_ci</li> 6390f66f451Sopenharmony_ci</ul> 6400f66f451Sopenharmony_ci 6410f66f451Sopenharmony_ci<a name="lib"> 6420f66f451Sopenharmony_ci<h2>Directory lib/</h2> 6430f66f451Sopenharmony_ci 6440f66f451Sopenharmony_ci<p>TODO: document lots more here.</p> 6450f66f451Sopenharmony_ci 6460f66f451Sopenharmony_ci<p>lib: getmountlist(), error_msg/error_exit, xmalloc(), 6470f66f451Sopenharmony_cistrlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(), 6480f66f451Sopenharmony_ciitoa().</p> 6490f66f451Sopenharmony_ci 6500f66f451Sopenharmony_ci 6510f66f451Sopenharmony_ci 6520f66f451Sopenharmony_ci<a name="lib_xwrap"><h3>lib/xwrap.c</h3> 6530f66f451Sopenharmony_ci 6540f66f451Sopenharmony_ci<p>Functions prefixed with the letter x call perror_exit() when they hit 6550f66f451Sopenharmony_cierrors, to eliminate common error checking. This prints an error message 6560f66f451Sopenharmony_ciand the strerror() string for the errno encountered.</p> 6570f66f451Sopenharmony_ci 6580f66f451Sopenharmony_ci<p>We replaced exit(), _exit(), and atexit() with xexit(), _xexit(), and 6590f66f451Sopenharmony_cisigatexit(). This gives _xexit() the option to siglongjmp(toys.rebound, 1) 6600f66f451Sopenharmony_ciinstead of exiting, lets xexit() report stdout flush failures to stderr 6610f66f451Sopenharmony_ciand change the exit code to indicate error, lets our toys.exit function 6620f66f451Sopenharmony_cichange happen for signal exit paths and lets us remove the functions 6630f66f451Sopenharmony_ciafter we've called them.</p> 6640f66f451Sopenharmony_ci 6650f66f451Sopenharmony_ci<p>You can intercept our exit by assigning a sigsetjmp/siglongjmp buffer to 6660f66f451Sopenharmony_citoys.rebound (set it back to zero to restore the default behavior). 6670f66f451Sopenharmony_ciIf you do this, cleaning up resource leaks is your problem.</p> 6680f66f451Sopenharmony_ci 6690f66f451Sopenharmony_ci<ul> 6700f66f451Sopenharmony_ci<li><b>void xstrncpy(char *dest, char *src, size_t size)</b></li> 6710f66f451Sopenharmony_ci<li><p><b><p>void _xexit(void)</b></p> 6720f66f451Sopenharmony_ci<p>Calls siglongjmp(toys.rebound, 1), or else _exit(toys.exitval). This 6730f66f451Sopenharmony_cilets you ignore errors with the NO_EXIT() macro wrapper, or intercept 6740f66f451Sopenharmony_cithem with WOULD_EXIT().</p> 6750f66f451Sopenharmony_ci<li><b><p>void xexit(void)</b></p> 6760f66f451Sopenharmony_ci<p>Calls toys.xexit functions (if any) and flushes stdout/stderr (reporting 6770f66f451Sopenharmony_cifailure to write to stdout both to stderr and in the exit code), then 6780f66f451Sopenharmony_cicalls _xexit().</p> 6790f66f451Sopenharmony_ci</li> 6800f66f451Sopenharmony_ci<li><b>void *xmalloc(size_t size)</b></li> 6810f66f451Sopenharmony_ci<li><b>void *xzalloc(size_t size)</b></li> 6820f66f451Sopenharmony_ci<li><b>void *xrealloc(void *ptr, size_t size)</b></li> 6830f66f451Sopenharmony_ci<li><b>char *xstrndup(char *s, size_t n)</b></li> 6840f66f451Sopenharmony_ci<li><b>char *xstrdup(char *s)</b></li> 6850f66f451Sopenharmony_ci<li><b>char *xmprintf(char *format, ...)</b></li> 6860f66f451Sopenharmony_ci<li><b>void xprintf(char *format, ...)</b></li> 6870f66f451Sopenharmony_ci<li><b>void xputs(char *s)</b></li> 6880f66f451Sopenharmony_ci<li><b>void xputc(char c)</b></li> 6890f66f451Sopenharmony_ci<li><b>void xflush(void)</b></li> 6900f66f451Sopenharmony_ci<li><b>pid_t xfork(void)</b></li> 6910f66f451Sopenharmony_ci<li><b>void xexec_optargs(int skip)</b></li> 6920f66f451Sopenharmony_ci<li><b>void xexec(char **argv)</b></li> 6930f66f451Sopenharmony_ci<li><b>pid_t xpopen(char **argv, int *pipes)</b></li> 6940f66f451Sopenharmony_ci<li><b>int xpclose(pid_t pid, int *pipes)</b></li> 6950f66f451Sopenharmony_ci<li><b>void xaccess(char *path, int flags)</b></li> 6960f66f451Sopenharmony_ci<li><b>void xunlink(char *path)</b></li> 6970f66f451Sopenharmony_ci<li><p><b>int xcreate(char *path, int flags, int mode)<br /> 6980f66f451Sopenharmony_ciint xopen(char *path, int flags)</b></p> 6990f66f451Sopenharmony_ci 7000f66f451Sopenharmony_ci<p>The xopen() and xcreate() functions open an existing file (exiting if 7010f66f451Sopenharmony_ciit's not there) and create a new file (exiting if it can't).</p> 7020f66f451Sopenharmony_ci 7030f66f451Sopenharmony_ci<p>They default to O_CLOEXEC so the filehandles aren't passed on to child 7040f66f451Sopenharmony_ciprocesses. Feed in O_CLOEXEC to disable this.</p> 7050f66f451Sopenharmony_ci</li> 7060f66f451Sopenharmony_ci<li><p><b>void xclose(int fd)</b></p> 7070f66f451Sopenharmony_ci 7080f66f451Sopenharmony_ci<p>Because NFS is broken, and won't necessarily perform the requested 7090f66f451Sopenharmony_cioperation (and report the error) until you close the file. Of course, this 7100f66f451Sopenharmony_cibeing NFS, it's not guaranteed to report the error there either, but it 7110f66f451Sopenharmony_ci_can_.</p> 7120f66f451Sopenharmony_ci 7130f66f451Sopenharmony_ci<p>Nothing else ever reports an error on close, everywhere else it's just a 7140f66f451Sopenharmony_ciVFS operation freeing some resources. NFS is _special_, in a way that 7150f66f451Sopenharmony_ciother network filesystems like smbfs and v9fs aren't..</p> 7160f66f451Sopenharmony_ci</li> 7170f66f451Sopenharmony_ci<li><b>int xdup(int fd)</b></li> 7180f66f451Sopenharmony_ci<li><p><b>size_t xread(int fd, void *buf, size_t len)</b></p> 7190f66f451Sopenharmony_ci 7200f66f451Sopenharmony_ci<p>Can return 0, but not -1.</p> 7210f66f451Sopenharmony_ci</li> 7220f66f451Sopenharmony_ci<li><p><b>void xreadall(int fd, void *buf, size_t len)</b></p> 7230f66f451Sopenharmony_ci 7240f66f451Sopenharmony_ci<p>Reads the entire len-sized buffer, retrying to complete short 7250f66f451Sopenharmony_cireads. Exits if it can't get enough data.</p></li> 7260f66f451Sopenharmony_ci 7270f66f451Sopenharmony_ci<li><p><b>void xwrite(int fd, void *buf, size_t len)</b></p> 7280f66f451Sopenharmony_ci 7290f66f451Sopenharmony_ci<p>Retries short writes, exits if can't write the entire buffer.</p></li> 7300f66f451Sopenharmony_ci 7310f66f451Sopenharmony_ci<li><b>off_t xlseek(int fd, off_t offset, int whence)</b></li> 7320f66f451Sopenharmony_ci<li><b>char *xgetcwd(void)</b></li> 7330f66f451Sopenharmony_ci<li><b>void xstat(char *path, struct stat *st)</b></li> 7340f66f451Sopenharmony_ci<li><p><b>char *xabspath(char *path, int exact) </b></p> 7350f66f451Sopenharmony_ci 7360f66f451Sopenharmony_ci<p>After several years of 7370f66f451Sopenharmony_ci<a href=http://landley.net/notes-2007.html#18-06-2007>wrestling</a> 7380f66f451Sopenharmony_ci<a href=http://landley.net/notes-2008.html#19-01-2008>with</a> realpath(), 7390f66f451Sopenharmony_ciI broke down and <a href=http://landley.net/notes-2012.html#20-11-2012>wrote 7400f66f451Sopenharmony_cimy own</a> implementation that doesn't use the one in libc. As I explained: 7410f66f451Sopenharmony_ci 7420f66f451Sopenharmony_ci<blockquote><p>If the path ends with a broken link, 7430f66f451Sopenharmony_cireadlink -f should show where the link points to, not where the broken link 7440f66f451Sopenharmony_cilives. (The point of readlink -f is "if I write here, where would it attempt 7450f66f451Sopenharmony_cito create a file".) The problem is, realpath() returns NULL for a path ending 7460f66f451Sopenharmony_ciwith a broken link, and I can't beat different behavior out of code locked 7470f66f451Sopenharmony_ciaway in libc.</p></blockquote> 7480f66f451Sopenharmony_ci 7490f66f451Sopenharmony_ci<p> 7500f66f451Sopenharmony_ci</li> 7510f66f451Sopenharmony_ci<li><b>void xchdir(char *path)</b></li> 7520f66f451Sopenharmony_ci<li><b>void xchroot(char *path)</b></li> 7530f66f451Sopenharmony_ci 7540f66f451Sopenharmony_ci<li><p><b>struct passwd *xgetpwuid(uid_t uid)<br /> 7550f66f451Sopenharmony_cistruct group *xgetgrgid(gid_t gid)<br /> 7560f66f451Sopenharmony_cistruct passwd *xgetpwnam(char *name)</b></p> 7570f66f451Sopenharmony_ci</li> 7580f66f451Sopenharmony_ci 7590f66f451Sopenharmony_ci<li><b>void xsetuser(struct passwd *pwd)</b></li> 7600f66f451Sopenharmony_ci<li><b>char *xreadlink(char *name)</b></li> 7610f66f451Sopenharmony_ci<li><b>char *xreadfile(char *name, char *buf, off_t len)</b></li> 7620f66f451Sopenharmony_ci<li><b>int xioctl(int fd, int request, void *data)</b></li> 7630f66f451Sopenharmony_ci<li><b>void xpidfile(char *name)</b></li> 7640f66f451Sopenharmony_ci<li><b>void xsendfile(int in, int out)</b></li> 7650f66f451Sopenharmony_ci<li><b>long xparsetime(char *arg, long units, long *fraction)</b></li> 7660f66f451Sopenharmony_ci<li><b>void xregcomp(regex_t *preg, char *regex, int cflags)</b></li> 7670f66f451Sopenharmony_ci</ul> 7680f66f451Sopenharmony_ci 7690f66f451Sopenharmony_ci<a name="lib_lib"><h3>lib/lib.c</h3> 7700f66f451Sopenharmony_ci<p>Eight gazillion common functions, see lib/lib.h for the moment:</p> 7710f66f451Sopenharmony_ci 7720f66f451Sopenharmony_ci<h3>lib/portability.h</h3> 7730f66f451Sopenharmony_ci 7740f66f451Sopenharmony_ci<p>This file is automatically included from the top of toys.h, and smooths 7750f66f451Sopenharmony_ciover differences between platforms (hardware targets, compilers, C libraries, 7760f66f451Sopenharmony_cioperating systems, etc).</p> 7770f66f451Sopenharmony_ci 7780f66f451Sopenharmony_ci<p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p> 7790f66f451Sopenharmony_ci 7800f66f451Sopenharmony_ci<p>A macro like SWAP_LE32(x) means "The value in x is stored as a little 7810f66f451Sopenharmony_ciendian 32 bit value, so perform the translation to/from whatever the native 7820f66f451Sopenharmony_ci32-bit format is". You do the swap once on the way in, and once on the way 7830f66f451Sopenharmony_ciout. If your target is already little endian, the macro is a NOP.</p> 7840f66f451Sopenharmony_ci 7850f66f451Sopenharmony_ci<p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions. 7860f66f451Sopenharmony_ciIn each case, the name of the macro refers to the _external_ representation, 7870f66f451Sopenharmony_ciand converts to/from whatever your native representation happens to be (which 7880f66f451Sopenharmony_cican vary depending on what you're currently compiling for).</p> 7890f66f451Sopenharmony_ci 7900f66f451Sopenharmony_ci<a name="lib_llist"><h3>lib/llist.c</h3> 7910f66f451Sopenharmony_ci 7920f66f451Sopenharmony_ci<p>Some generic single and doubly linked list functions, which take 7930f66f451Sopenharmony_ciadvantage of a couple properties of C:</p> 7940f66f451Sopenharmony_ci 7950f66f451Sopenharmony_ci<ul> 7960f66f451Sopenharmony_ci<li><p>Structure elements are laid out in memory in the order listed, and 7970f66f451Sopenharmony_cithe first element has no padding. This means you can always treat (typecast) 7980f66f451Sopenharmony_cia pointer to a structure as a pointer to the first element of the structure, 7990f66f451Sopenharmony_cieven if you don't know anything about the data following it.</p></li> 8000f66f451Sopenharmony_ci 8010f66f451Sopenharmony_ci<li><p>An array of length zero at the end of a structure adds no space 8020f66f451Sopenharmony_cito the sizeof() the structure, but if you calculate how much extra space 8030f66f451Sopenharmony_ciyou want when you malloc() the structure it will be available at the end. 8040f66f451Sopenharmony_ciSince C has no bounds checking, this means each struct can have one variable 8050f66f451Sopenharmony_cilength array.</p></li> 8060f66f451Sopenharmony_ci</ul> 8070f66f451Sopenharmony_ci 8080f66f451Sopenharmony_ci<p>Toybox's list structures always have their <b>next</b> pointer as 8090f66f451Sopenharmony_cithe first entry of each struct, and singly linked lists end with a NULL pointer. 8100f66f451Sopenharmony_ciThis allows generic code to traverse such lists without knowing anything 8110f66f451Sopenharmony_cielse about the specific structs composing them: if your pointer isn't NULL 8120f66f451Sopenharmony_citypecast it to void ** and dereference once to get the next entry.</p> 8130f66f451Sopenharmony_ci 8140f66f451Sopenharmony_ci<p><b>lib/lib.h</b> defines three structure types:</p> 8150f66f451Sopenharmony_ci<ul> 8160f66f451Sopenharmony_ci<li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>), 8170f66f451Sopenharmony_cimemory for which is allocated as part of the node. (I.E. llist_traverse(list, 8180f66f451Sopenharmony_cifree); can clean up after this type of list.)</p></li> 8190f66f451Sopenharmony_ci 8200f66f451Sopenharmony_ci<li><p><b>struct arg_list</b> - stores a pointer to a single string 8210f66f451Sopenharmony_ci(<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li> 8220f66f451Sopenharmony_ci 8230f66f451Sopenharmony_ci<li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list 8240f66f451Sopenharmony_ci*prev</b> along with a <b>char *data</b> for payload.</p></li> 8250f66f451Sopenharmony_ci</ul> 8260f66f451Sopenharmony_ci 8270f66f451Sopenharmony_ci<b>List Functions</b> 8280f66f451Sopenharmony_ci 8290f66f451Sopenharmony_ci<ul> 8300f66f451Sopenharmony_ci<li><p>void *<b>llist_pop</b>(void **list) - advances through a list ala 8310f66f451Sopenharmony_ci<b>node = llist_pop(&list);</b> This doesn't modify the list contents, 8320f66f451Sopenharmony_cibut does advance the pointer you feed it (which is why you pass the _address_ 8330f66f451Sopenharmony_ciof that pointer, not the pointer itself).</p></li> 8340f66f451Sopenharmony_ci 8350f66f451Sopenharmony_ci<li><p>void <b>llist_traverse</b>(void *list, void (*using)(void *data)) - 8360f66f451Sopenharmony_ciiterate through a list calling a function on each node.</p></li> 8370f66f451Sopenharmony_ci 8380f66f451Sopenharmony_ci<li><p>struct double_list *<b>dlist_add</b>(struct double_list **llist, char *data) 8390f66f451Sopenharmony_ci- append an entry to a circular linked list. 8400f66f451Sopenharmony_ciThis function allocates a new struct double_list wrapper and returns the 8410f66f451Sopenharmony_cipointer to the new entry (which you can usually ignore since it's llist->prev, 8420f66f451Sopenharmony_cibut if llist was NULL you need it). The argument is the ->data field for the 8430f66f451Sopenharmony_cinew node.</p></li> 8440f66f451Sopenharmony_ci<ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist, 8450f66f451Sopenharmony_cistruct double_list *new) - append existing struct double_list to 8460f66f451Sopenharmony_cilist, does not allocate anything.</p></li></ul> 8470f66f451Sopenharmony_ci</ul> 8480f66f451Sopenharmony_ci 8490f66f451Sopenharmony_ci<b>List code trivia questions:</b> 8500f66f451Sopenharmony_ci 8510f66f451Sopenharmony_ci<ul> 8520f66f451Sopenharmony_ci<li><p><b>Why do arg_list and double_list contain a char * payload instead of 8530f66f451Sopenharmony_cia void *?</b> - Because you always have to typecast a void * to use it, and 8540f66f451Sopenharmony_citypecasting a char * does no harm. Since strings are the most common 8550f66f451Sopenharmony_cipayload, and doing math on the pointer ala 8560f66f451Sopenharmony_ci"(type *)(ptr+sizeof(thing)+sizeof(otherthing))" requires ptr to be char * 8570f66f451Sopenharmony_cianyway (at least according to the C standard), defaulting to char * saves 8580f66f451Sopenharmony_cia typecast.</p> 8590f66f451Sopenharmony_ci</li> 8600f66f451Sopenharmony_ci 8610f66f451Sopenharmony_ci<li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force 8620f66f451Sopenharmony_ciyou to keep track of which one you're using, calling free(node->str) would 8630f66f451Sopenharmony_cibe bad, and _failing_ to free(node->arg) leaks memory.</p></li> 8640f66f451Sopenharmony_ci 8650f66f451Sopenharmony_ci<li><p><b>Why does llist_pop() take a void * instead of void **?</b> - 8660f66f451Sopenharmony_cibecause the stupid compiler complains about "type punned pointers" when 8670f66f451Sopenharmony_ciyou typecast and dereference on the same line, 8680f66f451Sopenharmony_cidue to insane FSF developers hardwiring limitations of their optimizer 8690f66f451Sopenharmony_ciinto gcc's warning system. Since C automatically typecasts any other 8700f66f451Sopenharmony_cipointer type to and from void *, the current code works fine. It's sad that it 8710f66f451Sopenharmony_ciwon't warn you if you forget the &, but the code crashes pretty quickly in 8720f66f451Sopenharmony_cithat case.</p></li> 8730f66f451Sopenharmony_ci 8740f66f451Sopenharmony_ci<li><p><b>How do I assemble a singly-linked-list in order?</b> - use 8750f66f451Sopenharmony_cia double_list, dlist_add() your entries, and then call dlist_terminate(list) 8760f66f451Sopenharmony_cito break the circle when done (turning the last ->next and the first ->prev 8770f66f451Sopenharmony_ciinto NULLs).</p> 8780f66f451Sopenharmony_ci</ul> 8790f66f451Sopenharmony_ci 8800f66f451Sopenharmony_ci<a name="lib_args"><h3>lib/args.c</h3> 8810f66f451Sopenharmony_ci 8820f66f451Sopenharmony_ci<p>Toybox's main.c automatically parses command line options before calling the 8830f66f451Sopenharmony_cicommand's main function. Option parsing starts in get_optflags(), which stores 8840f66f451Sopenharmony_ciresults in the global structures "toys" (optflags and optargs) and "this".</p> 8850f66f451Sopenharmony_ci 8860f66f451Sopenharmony_ci<p>The option parsing infrastructure stores a bitfield in toys.optflags to 8870f66f451Sopenharmony_ciindicate which options the current command line contained, and defines FLAG 8880f66f451Sopenharmony_cimacros code can use to check whether each argument's bit is set. Arguments 8890f66f451Sopenharmony_ciattached to those options are saved into the command's global structure 8900f66f451Sopenharmony_ci("this"). Any remaining command line arguments are collected together into 8910f66f451Sopenharmony_cithe null-terminated array toys.optargs, with the length in toys.optc. (Note 8920f66f451Sopenharmony_cithat toys.optargs does not contain the current command name at position zero, 8930f66f451Sopenharmony_ciuse "toys.which->name" for that.) The raw command line arguments get_optflags() 8940f66f451Sopenharmony_ciparsed are retained unmodified in toys.argv[].</p> 8950f66f451Sopenharmony_ci 8960f66f451Sopenharmony_ci<p>Toybox's option parsing logic is controlled by an "optflags" string, using 8970f66f451Sopenharmony_cia format reminiscent of getopt's optargs but with several important differences. 8980f66f451Sopenharmony_ciToybox does not use the getopt() 8990f66f451Sopenharmony_cifunction out of the C library, get_optflags() is an independent implementation 9000f66f451Sopenharmony_ciwhich doesn't permute the original arguments (and thus doesn't change how the 9010f66f451Sopenharmony_cicommand is displayed in ps and top), and has many features not present in 9020f66f451Sopenharmony_cilibc optargs() (such as the ability to describe long options in the same string 9030f66f451Sopenharmony_cias normal options).</p> 9040f66f451Sopenharmony_ci 9050f66f451Sopenharmony_ci<p>Each command's NEWTOY() macro has an optflags string as its middle argument, 9060f66f451Sopenharmony_ciwhich sets toy_list.options for that command to tell get_optflags() what 9070f66f451Sopenharmony_cicommand line arguments to look for, and what to do with them. 9080f66f451Sopenharmony_ciIf a command has no option 9090f66f451Sopenharmony_cidefinition string (I.E. the argument is NULL), option parsing is skipped 9100f66f451Sopenharmony_cifor that command, which must look at the raw data in toys.argv to parse its 9110f66f451Sopenharmony_ciown arguments. (If no currently enabled command uses option parsing, 9120f66f451Sopenharmony_ciget_optflags() is optimized out of the resulting binary by the compiler's 9130f66f451Sopenharmony_ci--gc-sections option.)</p> 9140f66f451Sopenharmony_ci 9150f66f451Sopenharmony_ci<p>You don't have to free the option strings, which point into the environment 9160f66f451Sopenharmony_cispace (I.E. the string data is not copied). A TOYFLAG_NOFORK command 9170f66f451Sopenharmony_cithat uses the linked list type "*" should free the list objects but not 9180f66f451Sopenharmony_cithe data they point to, via "llist_free(TT.mylist, NULL);". (If it's not 9190f66f451Sopenharmony_ciNOFORK, exit() will free all the malloced data anyway unless you want 9200f66f451Sopenharmony_cito implement a CONFIG_TOYBOX_FREE cleanup for it.)</p> 9210f66f451Sopenharmony_ci 9220f66f451Sopenharmony_ci<h4>Optflags format string</h4> 9230f66f451Sopenharmony_ci 9240f66f451Sopenharmony_ci<p>Note: the optflags option description string format is much more 9250f66f451Sopenharmony_ciconcisely described by a large comment at the top of lib/args.c.</p> 9260f66f451Sopenharmony_ci 9270f66f451Sopenharmony_ci<p>The general theory is that letters set optflags, and punctuation describes 9280f66f451Sopenharmony_ciother actions the option parsing logic should take.</p> 9290f66f451Sopenharmony_ci 9300f66f451Sopenharmony_ci<p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b> 9310f66f451Sopenharmony_ciis parsed using the optflags string "<b>a#b:c:d</b>". (I.E. 9320f66f451Sopenharmony_citoys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d", 9330f66f451Sopenharmony_ci"walrus", "-a", "42"]). When get_optflags() returns, the following data is 9340f66f451Sopenharmony_ciavailable to command_main(): 9350f66f451Sopenharmony_ci 9360f66f451Sopenharmony_ci<ul> 9370f66f451Sopenharmony_ci<li><p>In <b>struct toys</b>: 9380f66f451Sopenharmony_ci<ul> 9390f66f451Sopenharmony_ci<li>toys.optflags = 13; // FLAG_a = 8 | FLAG_b = 4 | FLAG_d = 1</li> 9400f66f451Sopenharmony_ci<li>toys.optargs[0] = "walrus"; // leftover argument</li> 9410f66f451Sopenharmony_ci<li>toys.optargs[1] = NULL; // end of list</li> 9420f66f451Sopenharmony_ci<li>toys.optc = 1; // there was 1 leftover argument</li> 9430f66f451Sopenharmony_ci<li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments 9440f66f451Sopenharmony_ci</ul> 9450f66f451Sopenharmony_ci<p></li> 9460f66f451Sopenharmony_ci 9470f66f451Sopenharmony_ci<li><p>In <b>union this</b> (treated as <b>long this[]</b>): 9480f66f451Sopenharmony_ci<ul> 9490f66f451Sopenharmony_ci<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> 9500f66f451Sopenharmony_ci<li>this[1] = (long)"fruit"; // argument to -b</li> 9510f66f451Sopenharmony_ci<li>this[2] = 42; // argument to -a</li> 9520f66f451Sopenharmony_ci</ul> 9530f66f451Sopenharmony_ci</p></li> 9540f66f451Sopenharmony_ci</ul> 9550f66f451Sopenharmony_ci 9560f66f451Sopenharmony_ci<p>If the command's globals are:</p> 9570f66f451Sopenharmony_ci 9580f66f451Sopenharmony_ci<blockquote><pre> 9590f66f451Sopenharmony_ciGLOBALS( 9600f66f451Sopenharmony_ci char *c; 9610f66f451Sopenharmony_ci char *b; 9620f66f451Sopenharmony_ci long a; 9630f66f451Sopenharmony_ci) 9640f66f451Sopenharmony_ci</pre></blockquote> 9650f66f451Sopenharmony_ci 9660f66f451Sopenharmony_ci<p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember, 9670f66f451Sopenharmony_cieach entry that receives an argument must be a long or pointer, to line up 9680f66f451Sopenharmony_ciwith the array position. Right to left in the optflags string corresponds to 9690f66f451Sopenharmony_citop to bottom in GLOBALS().</p> 9700f66f451Sopenharmony_ci 9710f66f451Sopenharmony_ci<p>Put globals not filled out by the option parsing logic at the end of the 9720f66f451Sopenharmony_ciGLOBALS block. Common practice is to list the options one per line (to 9730f66f451Sopenharmony_cimake the ordering explicit, first to last in globals corresponds to right 9740f66f451Sopenharmony_cito left in the option string), then leave a blank line before any non-option 9750f66f451Sopenharmony_ciglobals.</p> 9760f66f451Sopenharmony_ci 9770f66f451Sopenharmony_ci<p><b>long toys.optflags</b></p> 9780f66f451Sopenharmony_ci 9790f66f451Sopenharmony_ci<p>Each option in the optflags string corresponds to a bit position in 9800f66f451Sopenharmony_citoys.optflags, with the same value as a corresponding binary digit. The 9810f66f451Sopenharmony_cirightmost argument is (1<<0), the next to last is (1<<1) and so on. If 9820f66f451Sopenharmony_cithe option isn't encountered while parsing argv[], its bit remains 0.</p> 9830f66f451Sopenharmony_ci 9840f66f451Sopenharmony_ci<p>Each option -x has a FLAG_x macro for the command letter. Bare --longopts 9850f66f451Sopenharmony_ciwith no corresponding short option have a FLAG_longopt macro for the long 9860f66f451Sopenharmony_cioptionname. Commands enable these macros by #defining FOR_commandname before 9870f66f451Sopenharmony_ci#including <toys.h>. When multiple commands are implemented in the same 9880f66f451Sopenharmony_cisource file, you can switch flag contexts later in the file by 9890f66f451Sopenharmony_ci#defining CLEANUP_oldcommand and #defining FOR_newcommand, then 9900f66f451Sopenharmony_ci#including <generated/flags.h>.</p> 9910f66f451Sopenharmony_ci 9920f66f451Sopenharmony_ci<p>Options disabled in the current configuration (wrapped in 9930f66f451Sopenharmony_cia USE_BLAH() macro for a CONFIG_BLAH that's switched off) have their 9940f66f451Sopenharmony_cicorresponding FLAG macro set to zero, so code checking them ala 9950f66f451Sopenharmony_ciif (toys.optargs & FLAG_x) gets optimized out via dead code elimination. 9960f66f451Sopenharmony_ci#defining FORCE_FLAGS when switching flag context disables this 9970f66f451Sopenharmony_cibehavior: the flag is never zero even if the config is disabled. This 9980f66f451Sopenharmony_ciallows code shared between multiple commands to use the same flag 9990f66f451Sopenharmony_civalues, as long as the common flags match up right to left in both option 10000f66f451Sopenharmony_cistrings.</p> 10010f66f451Sopenharmony_ci 10020f66f451Sopenharmony_ci<p>For example, 10030f66f451Sopenharmony_cithe optflags string "abcd" would parse the command line argument "-c" to set 10040f66f451Sopenharmony_cioptflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to 10050f66f451Sopenharmony_ci6 (I.E. 4|2), and "-a -c" would set optflags to 10 (2|8). To check if -c 10060f66f451Sopenharmony_ciwas encountered, code could test: if (toys.optflags & FLAG_c) printf("yup"); 10070f66f451Sopenharmony_ci(See the toys/examples directory for more.)</p> 10080f66f451Sopenharmony_ci 10090f66f451Sopenharmony_ci<p>Only letters are relevant to optflags, punctuation is skipped: in the 10100f66f451Sopenharmony_cistring "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter 10110f66f451Sopenharmony_ciusually indicate that the option takes an argument.</p> 10120f66f451Sopenharmony_ci 10130f66f451Sopenharmony_ci<p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is 10140f66f451Sopenharmony_cithe amount a long would have on 32-bit platforms anyway; 64 bit code on 10150f66f451Sopenharmony_ci32 bit platforms is too expensive to require in common code used by almost 10160f66f451Sopenharmony_ciall commands.) Bit positions beyond the 1<<31 aren't recorded, but 10170f66f451Sopenharmony_ciparsing higher options can still set global variables.</p> 10180f66f451Sopenharmony_ci 10190f66f451Sopenharmony_ci<p><b>Automatically setting global variables from arguments (union this)</b></p> 10200f66f451Sopenharmony_ci 10210f66f451Sopenharmony_ci<p>The following punctuation characters may be appended to an optflags 10220f66f451Sopenharmony_ciargument letter, indicating the option takes an additional argument:</p> 10230f66f451Sopenharmony_ci 10240f66f451Sopenharmony_ci<ul> 10250f66f451Sopenharmony_ci<li><b>:</b> - plus a string argument, keep most recent if more than one.</li> 10260f66f451Sopenharmony_ci<li><b>*</b> - plus a string argument, appended to a linked list.</li> 10270f66f451Sopenharmony_ci<li><b>@</b> - plus an occurrence counter (stored in a long)</li> 10280f66f451Sopenharmony_ci<li><b>#</b> - plus a signed long argument. 10290f66f451Sopenharmony_ci<li><b>-</b> - plus a signed long argument defaulting to negative (start argument with + to force a positive value).</li> 10300f66f451Sopenharmony_ci<li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li> 10310f66f451Sopenharmony_ci<ul>The following can be appended to a float or double: 10320f66f451Sopenharmony_ci<li><b><123</b> - error if argument is less than this</li> 10330f66f451Sopenharmony_ci<li><b>>123</b> - error if argument is greater than this</li> 10340f66f451Sopenharmony_ci<li><b>=123</b> - default value if argument not supplied</li> 10350f66f451Sopenharmony_ci</ul> 10360f66f451Sopenharmony_ci</ul> 10370f66f451Sopenharmony_ci 10380f66f451Sopenharmony_ci<p><b>GLOBALS</b></p> 10390f66f451Sopenharmony_ci 10400f66f451Sopenharmony_ci<p>Options which have an argument fill in the corresponding slot in the global 10410f66f451Sopenharmony_ciunion "this" (see generated/globals.h), treating it as an array of longs 10420f66f451Sopenharmony_ciwith the rightmost saved in this[0]. As described above, using "a*b:c#d", 10430f66f451Sopenharmony_ci"-c 42" would set this[0] = 42; and "-b 42" would set this[1] = "42"; each 10440f66f451Sopenharmony_cislot is left NULL if the corresponding argument is not encountered.</p> 10450f66f451Sopenharmony_ci 10460f66f451Sopenharmony_ci<p>This behavior is useful because the LP64 standard ensures long and pointer 10470f66f451Sopenharmony_ciare the same size. C99 guarantees structure members will occur in memory 10480f66f451Sopenharmony_ciin the same order they're declared, and that padding won't be inserted between 10490f66f451Sopenharmony_ciconsecutive variables of register size. Thus the first few entries can 10500f66f451Sopenharmony_cibe longs or pointers corresponding to the saved arguments.</p> 10510f66f451Sopenharmony_ci 10520f66f451Sopenharmony_ci<p>The main downside is that numeric arguments ("#" and "-" format) 10530f66f451Sopenharmony_ciare limited to +- 2 billion on 32 bit platforms (the "truncate -s 8G" 10540f66f451Sopenharmony_ciproblem), because long is only 64 bits on 64 bit hosts, so the capabilities 10550f66f451Sopenharmony_ciof some tools differ when built in 32 bit vs 64 bit mode. Fixing this 10560f66f451Sopenharmony_cikind of ugly and even embedded designs are slowly moving to 64 bits, 10570f66f451Sopenharmony_ciso our current plan is to document the problem and wait it out. (If 10580f66f451Sopenharmony_ci"x32 mode" and similar becomes popular enough, we may revisit this 10590f66f451Sopenharmony_cidecision.)</p> 10600f66f451Sopenharmony_ci 10610f66f451Sopenharmony_ci<p>See toys/example/*.c for longer examples of parsing options into the 10620f66f451Sopenharmony_ciGLOBALS block.</p> 10630f66f451Sopenharmony_ci 10640f66f451Sopenharmony_ci<p><b>char *toys.optargs[]</b></p> 10650f66f451Sopenharmony_ci 10660f66f451Sopenharmony_ci<p>Command line arguments in argv[] which are not consumed by option parsing 10670f66f451Sopenharmony_ci(I.E. not recognized either as -flags or arguments to -flags) will be copied 10680f66f451Sopenharmony_cito toys.optargs[], with the length of that array in toys.optc. 10690f66f451Sopenharmony_ci(When toys.optc is 0, no unrecognized command line arguments remain.) 10700f66f451Sopenharmony_ciThe order of entries is preserved, and as with argv[] this new array is also 10710f66f451Sopenharmony_citerminated by a NULL entry.</p> 10720f66f451Sopenharmony_ci 10730f66f451Sopenharmony_ci<p>Option parsing can require a minimum or maximum number of optargs left 10740f66f451Sopenharmony_ciover, by adding "<1" (read "at least one") or ">9" ("at most nine") to the 10750f66f451Sopenharmony_cistart of the optflags string.</p> 10760f66f451Sopenharmony_ci 10770f66f451Sopenharmony_ci<p>The special argument "--" terminates option parsing, storing all remaining 10780f66f451Sopenharmony_ciarguments in optargs. The "--" itself is consumed.</p> 10790f66f451Sopenharmony_ci 10800f66f451Sopenharmony_ci<p><b>Other optflags control characters</b></p> 10810f66f451Sopenharmony_ci 10820f66f451Sopenharmony_ci<p>The following characters may occur at the start of each command's 10830f66f451Sopenharmony_cioptflags string, before any options that would set a bit in toys.optflags:</p> 10840f66f451Sopenharmony_ci 10850f66f451Sopenharmony_ci<ul> 10860f66f451Sopenharmony_ci<li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li> 10870f66f451Sopenharmony_ci<li><b>?</b> - allow unknown arguments (pass non-option arguments starting 10880f66f451Sopenharmony_ciwith - through to optargs instead of erroring out).</li> 10890f66f451Sopenharmony_ci<li><b>&</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li> 10900f66f451Sopenharmony_ci<li><b><</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li> 10910f66f451Sopenharmony_ci<li><b>></b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li> 10920f66f451Sopenharmony_ci</ul> 10930f66f451Sopenharmony_ci 10940f66f451Sopenharmony_ci<p>The following characters may be appended to an option character, but do 10950f66f451Sopenharmony_cinot by themselves indicate an extra argument should be saved in this[]. 10960f66f451Sopenharmony_ci(Technically any character not recognized as a control character sets an 10970f66f451Sopenharmony_cioptflag, but letters are never control characters.)</p> 10980f66f451Sopenharmony_ci 10990f66f451Sopenharmony_ci<ul> 11000f66f451Sopenharmony_ci<li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li> 11010f66f451Sopenharmony_ci<li><b>|</b> - this option is required. If more than one marked, only one is required.</li> 11020f66f451Sopenharmony_ci</ul> 11030f66f451Sopenharmony_ci 11040f66f451Sopenharmony_ci<p>The following may be appended to a float or double:</p> 11050f66f451Sopenharmony_ci 11060f66f451Sopenharmony_ci<ul> 11070f66f451Sopenharmony_ci<li><b><123</b> - error if argument is less than this</li> 11080f66f451Sopenharmony_ci<li><b>>123</b> - error if argument is greater than this</li> 11090f66f451Sopenharmony_ci<li><b>=123</b> - default value if argument not supplied</li> 11100f66f451Sopenharmony_ci</ul> 11110f66f451Sopenharmony_ci 11120f66f451Sopenharmony_ci<p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT 11130f66f451Sopenharmony_ciis enabled. (Otherwise the code to determine where floating point constants 11140f66f451Sopenharmony_ciend drops out. When disabled, it can reserve a global data slot for the 11150f66f451Sopenharmony_ciargument so offsets won't change, but will never fill it out.) You can handle 11160f66f451Sopenharmony_cithis by using the USE_BLAH() macros with C string concatenation, ala:</p> 11170f66f451Sopenharmony_ci 11180f66f451Sopenharmony_ci<blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote> 11190f66f451Sopenharmony_ci 11200f66f451Sopenharmony_ci<p><b>--longopts</b></p> 11210f66f451Sopenharmony_ci 11220f66f451Sopenharmony_ci<p>The optflags string can contain long options, which are enclosed in 11230f66f451Sopenharmony_ciparentheses. They may be appended to an existing option character, in 11240f66f451Sopenharmony_ciwhich case the --longopt is a synonym for that option, ala "a:(--fred)" 11250f66f451Sopenharmony_ciwhich understands "-a blah" or "--fred blah" as synonyms.</p> 11260f66f451Sopenharmony_ci 11270f66f451Sopenharmony_ci<p>Longopts may also appear before any other options in the optflags string, 11280f66f451Sopenharmony_ciin which case they have no corresponding short argument, but instead set 11290f66f451Sopenharmony_citheir own bit based on position. So for "(walrus)#(blah)xy:z", "command 11300f66f451Sopenharmony_ci--walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8) 11310f66f451Sopenharmony_ciand would assign this[1] = 42;</p> 11320f66f451Sopenharmony_ci 11330f66f451Sopenharmony_ci<p>A short option may have multiple longopt synonyms, "a(one)(two)", but 11340f66f451Sopenharmony_cieach "bare longopt" (ala "(one)(two)abc" before any option characters) 11350f66f451Sopenharmony_cialways sets its own bit (although you can group them with +X).</p> 11360f66f451Sopenharmony_ci 11370f66f451Sopenharmony_ci<p>Only bare longopts have a FLAG_ macro with the longopt name 11380f66f451Sopenharmony_ci(ala --fred would #define FLAG_fred). Other longopts use the short 11390f66f451Sopenharmony_cioption's FLAG macro to test the toys.optflags bit.</p> 11400f66f451Sopenharmony_ci 11410f66f451Sopenharmony_ci<p>Options with a semicolon ";" after their data type can only set their 11420f66f451Sopenharmony_cicorresponding GLOBALS() entry via "--longopt=value". For example, option 11430f66f451Sopenharmony_cistring "x(boing): y" would set TT.x if it saw "--boing=value", but would 11440f66f451Sopenharmony_citreat "--boing value" as setting FLAG_x in toys.optargs, leaving TT.x NULL, 11450f66f451Sopenharmony_ciand keeping "value" in toys.optargs[]. (This lets "ls --color" and 11460f66f451Sopenharmony_ci"ls --color=auto" both work.)</p> 11470f66f451Sopenharmony_ci 11480f66f451Sopenharmony_ci<p><b>[groups]</b></p> 11490f66f451Sopenharmony_ci 11500f66f451Sopenharmony_ci<p>At the end of the option string, square bracket groups can define 11510f66f451Sopenharmony_cirelationships between existing options. (This only applies to short 11520f66f451Sopenharmony_cioptions, bare --longopts can't participate.)</p> 11530f66f451Sopenharmony_ci 11540f66f451Sopenharmony_ci<p>The first character of the group defines the type, the remaining 11550f66f451Sopenharmony_cicharacters are options it applies to:</p> 11560f66f451Sopenharmony_ci 11570f66f451Sopenharmony_ci<ul> 11580f66f451Sopenharmony_ci<li><b>-</b> - Exclusive, switch off all others in this group.</li> 11590f66f451Sopenharmony_ci<li><b>+</b> - Inclusive, switch on all others in this group.</li> 11600f66f451Sopenharmony_ci<li><b>!</b> - Error, fail if more than one defined.</li> 11610f66f451Sopenharmony_ci</ul> 11620f66f451Sopenharmony_ci 11630f66f451Sopenharmony_ci<p>So "abc[-abc]" means -ab = -b, -ba = -a, -abc = -c. "abc[+abc]" 11640f66f451Sopenharmony_cimeans -ab=-abc, -c=-abc, and "abc[!abc] means -ab calls error_exit("no -b 11650f66f451Sopenharmony_ciwith -a"). Note that [-] groups clear the GLOBALS option slot of 11660f66f451Sopenharmony_cioptions they're switching back off, but [+] won't set options it didn't see 11670f66f451Sopenharmony_ci(just the optflags).</p> 11680f66f451Sopenharmony_ci 11690f66f451Sopenharmony_ci<p><b>whitespace</b></p> 11700f66f451Sopenharmony_ci 11710f66f451Sopenharmony_ci<p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42"). 11720f66f451Sopenharmony_ciThe command line argument "-abc" may be interepreted many different ways: 11730f66f451Sopenharmony_cithe optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4 11740f66f451Sopenharmony_ciand saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves 11750f66f451Sopenharmony_ci"c" as the argument to -b.</p> 11760f66f451Sopenharmony_ci 11770f66f451Sopenharmony_ci<p>Note that & changes whitespace handling, so that the command line 11780f66f451Sopenharmony_ci"tar cvfCj outfile.tar.bz2 topdir filename" is parsed the same as 11790f66f451Sopenharmony_ci"tar filename -c -v -j -f outfile.tar.bz2 -C topdir". Note that "tar -cvfCj 11800f66f451Sopenharmony_cione two three" would equal "tar -c -v -f Cj one two three". (This matches 11810f66f451Sopenharmony_cihistorical usage.)</p> 11820f66f451Sopenharmony_ci 11830f66f451Sopenharmony_ci<p>Appending a space to the option in the option string ("a: b") makes it 11840f66f451Sopenharmony_cirequire a space, I.E. "-ab" is interpreted as "-a" "-b". That way "kill -stop" 11850f66f451Sopenharmony_cidiffers from "kill -s top".</p> 11860f66f451Sopenharmony_ci 11870f66f451Sopenharmony_ci<p>Appending ; to a longopt in the option string makes its argument optional, 11880f66f451Sopenharmony_ciand only settable with =, so in ls "(color):;" can accept "ls --color" and 11890f66f451Sopenharmony_ci"ls --color=auto" without complaining that the first has no argument.</p> 11900f66f451Sopenharmony_ci 11910f66f451Sopenharmony_ci<a name="lib_dirtree"><h3>lib/dirtree.c</h3> 11920f66f451Sopenharmony_ci 11930f66f451Sopenharmony_ci<p>The directory tree traversal code should be sufficiently generic 11940f66f451Sopenharmony_cithat commands never need to use readdir(), scandir(), or the fts.h family 11950f66f451Sopenharmony_ciof functions.</p> 11960f66f451Sopenharmony_ci 11970f66f451Sopenharmony_ci<p>These functions do not call chdir() or rely on PATH_MAX. Instead they 11980f66f451Sopenharmony_ciuse openat() and friends, using one filehandle per directory level to 11990f66f451Sopenharmony_cirecurse into subdirectories. (I.E. they can descend 1000 directories deep 12000f66f451Sopenharmony_ciif setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default 12010f66f451Sopenharmony_ciin /proc/self/limits is generally 1024.)</p> 12020f66f451Sopenharmony_ci 12030f66f451Sopenharmony_ci<p>There are two main ways to use dirtree: 1) assemble a tree of nodes 12040f66f451Sopenharmony_cirepresenting a snapshot of directory state and traverse them using the 12050f66f451Sopenharmony_ci->next and ->child pointers, or 2) traverse the tree calling a callback 12060f66f451Sopenharmony_cifunction on each entry, and freeing its node afterwards. (You can also 12070f66f451Sopenharmony_cicombine the two, using the callback as a filter to determine which nodes 12080f66f451Sopenharmony_cito keep.)</p> 12090f66f451Sopenharmony_ci 12100f66f451Sopenharmony_ci<p>The basic dirtree functions are:</p> 12110f66f451Sopenharmony_ci 12120f66f451Sopenharmony_ci<ul> 12130f66f451Sopenharmony_ci<li><p><b>struct dirtree *dirtree_read(char *path, int (*callback)(struct 12140f66f451Sopenharmony_cidirtree node))</b> - recursively read files and directories, calling 12150f66f451Sopenharmony_cicallback() on each, and returning a tree of saved nodes (if any). 12160f66f451Sopenharmony_ciIf path doesn't exist, returns DIRTREE_ABORTVAL. If callback is NULL, 12170f66f451Sopenharmony_cireturns a single node at that path.</p> 12180f66f451Sopenharmony_ci 12190f66f451Sopenharmony_ci<li><p><b>dirtree_notdotdot(struct dirtree *new)</b> - standard callback 12200f66f451Sopenharmony_ciwhich discards "." and ".." entries and returns DIRTREE_SAVE|DIRTREE_RECURSE 12210f66f451Sopenharmony_cifor everything else. Used directly, this assembles a snapshot tree of 12220f66f451Sopenharmony_cithe contents of this directory and its subdirectories 12230f66f451Sopenharmony_cito be processed after dirtree_read() returns (by traversing the 12240f66f451Sopenharmony_cistruct dirtree's ->next and ->child pointers from the returned root node).</p> 12250f66f451Sopenharmony_ci 12260f66f451Sopenharmony_ci<li><p><b>dirtree_path(struct dirtree *node, int *plen)</b> - malloc() a 12270f66f451Sopenharmony_cistring containing the path from the root of this tree to this node. If 12280f66f451Sopenharmony_ciplen isn't NULL then *plen is how many extra bytes to malloc at the end 12290f66f451Sopenharmony_ciof string.</p></li> 12300f66f451Sopenharmony_ci 12310f66f451Sopenharmony_ci<li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of 12320f66f451Sopenharmony_cidirectory containing this node, for use with openat() and such.</p></li> 12330f66f451Sopenharmony_ci</ul> 12340f66f451Sopenharmony_ci 12350f66f451Sopenharmony_ci<p>The <b>dirtree_read()</b> function is the standard way to start 12360f66f451Sopenharmony_cidirectory traversal. It takes two arguments: a starting path for 12370f66f451Sopenharmony_cithe root of the tree, and a callback function. The callback() is called 12380f66f451Sopenharmony_cion each directory entry, its argument is a fully populated 12390f66f451Sopenharmony_ci<b>struct dirtree *</b> (from lib/lib.h) describing the node, and its 12400f66f451Sopenharmony_cireturn value tells the dirtree infrastructure what to do next.</p> 12410f66f451Sopenharmony_ci 12420f66f451Sopenharmony_ci<p>(There's also a three argument version, 12430f66f451Sopenharmony_ci<b>dirtree_flagread(char *path, int flags, int (*callback)(struct 12440f66f451Sopenharmony_cidirtree node))</b>, which lets you apply flags like DIRTREE_SYMFOLLOW and 12450f66f451Sopenharmony_ciDIRTREE_SHUTUP to reading the top node, but this only affects the top node. 12460f66f451Sopenharmony_ciChild nodes use the flags returned by callback().</p> 12470f66f451Sopenharmony_ci 12480f66f451Sopenharmony_ci<p><b>struct dirtree</b></p> 12490f66f451Sopenharmony_ci 12500f66f451Sopenharmony_ci<p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat 12510f66f451Sopenharmony_cist</b> entries describing a file, plus a <b>char *symlink</b> 12520f66f451Sopenharmony_ciwhich is NULL for non-symlinks.</p> 12530f66f451Sopenharmony_ci 12540f66f451Sopenharmony_ci<p>During a callback function, the <b>int dirfd</b> field of directory nodes 12550f66f451Sopenharmony_cicontains a directory file descriptor (for use with the openat() family of 12560f66f451Sopenharmony_cifunctions). This isn't usually used directly, intstead call dirtree_parentfd() 12570f66f451Sopenharmony_cion the callback's node argument. The <b>char again</b> field is 0 for the 12580f66f451Sopenharmony_cifirst callback on a node, and 1 on the second callback (triggered by returning 12590f66f451Sopenharmony_ciDIRTREE_COMEAGAIN on a directory, made after all children have been processed). 12600f66f451Sopenharmony_ci</p> 12610f66f451Sopenharmony_ci 12620f66f451Sopenharmony_ci<p>Users of this code may put anything they like into the <b>long extra</b> 12630f66f451Sopenharmony_cifield. For example, "cp" and "mv" use this to store a dirfd for the destination 12640f66f451Sopenharmony_cidirectory (and use DIRTREE_COMEAGAIN to get the second callback so they can 12650f66f451Sopenharmony_ciclose(node->extra) to avoid running out of filehandles). 12660f66f451Sopenharmony_ciThis field is not directly used by the dirtree code, and 12670f66f451Sopenharmony_cithanks to LP64 it's large enough to store a typecast pointer to an 12680f66f451Sopenharmony_ciarbitrary struct.</p> 12690f66f451Sopenharmony_ci 12700f66f451Sopenharmony_ci<p>The return value of the callback combines flags (with boolean or) to tell 12710f66f451Sopenharmony_cithe traversal infrastructure how to behave:</p> 12720f66f451Sopenharmony_ci 12730f66f451Sopenharmony_ci<ul> 12740f66f451Sopenharmony_ci<li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without 12750f66f451Sopenharmony_cithis the struct dirtree is freed after the callback returns. Filtering out 12760f66f451Sopenharmony_cisiblings is fine, but discarding a parent while keeping its child leaks 12770f66f451Sopenharmony_cimemory.)</p></li> 12780f66f451Sopenharmony_ci<li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this 12790f66f451Sopenharmony_cidirectory. (Does not propagate up tree: to abort entire traversal, 12800f66f451Sopenharmony_cireturn DIRTREE_ABORT from parent callbacks too.)</p></li> 12810f66f451Sopenharmony_ci<li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for 12820f66f451Sopenharmony_cinon-directory entries. The remaining flags only take effect when 12830f66f451Sopenharmony_cirecursing into the children of a directory.</p></li> 12840f66f451Sopenharmony_ci<li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback on this node a second time 12850f66f451Sopenharmony_ciafter examining all directory contents, allowing depth-first traversal. 12860f66f451Sopenharmony_ciOn the second call, dirtree->again is nonzero.</p></li> 12870f66f451Sopenharmony_ci<li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's 12880f66f451Sopenharmony_ci<b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of 12890f66f451Sopenharmony_cidirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to 12900f66f451Sopenharmony_cidirectories as directories. (Avoiding infinite recursion is the callback's 12910f66f451Sopenharmony_ciproblem: the non-NULL dirtree->symlink can still distinguish between 12920f66f451Sopenharmony_cithem. The "find" command follows ->parent up the tree to the root node 12930f66f451Sopenharmony_cieach time, checking to make sure that stat's dev and inode pair don't 12940f66f451Sopenharmony_cimatch any ancestors.)</p></li> 12950f66f451Sopenharmony_ci</ul> 12960f66f451Sopenharmony_ci 12970f66f451Sopenharmony_ci<p>Each struct dirtree contains three pointers (next, parent, and child) 12980f66f451Sopenharmony_cito other struct dirtree.</p> 12990f66f451Sopenharmony_ci 13000f66f451Sopenharmony_ci<p>The <b>parent</b> pointer indicates the directory 13010f66f451Sopenharmony_cicontaining this entry; even when not assembling a persistent tree of 13020f66f451Sopenharmony_cinodes the parent entries remain live up to the root of the tree while 13030f66f451Sopenharmony_cichild nodes are active. At the top of the tree the parent pointer is 13040f66f451Sopenharmony_ciNULL, meaning the node's name[] is either an absolute path or relative 13050f66f451Sopenharmony_cito cwd. The function dirtree_parentfd() gets the directory file descriptor 13060f66f451Sopenharmony_cifor use with openat() and friends, returning AT_FDCWD at the top of tree.</p> 13070f66f451Sopenharmony_ci 13080f66f451Sopenharmony_ci<p>The <b>child</b> pointer points to the first node of the list of contents of 13090f66f451Sopenharmony_cithis directory. If the directory contains no files, or the entry isn't 13100f66f451Sopenharmony_cia directory, child is NULL.</p> 13110f66f451Sopenharmony_ci 13120f66f451Sopenharmony_ci<p>The <b>next</b> pointer indicates sibling nodes in the same directory as this 13130f66f451Sopenharmony_cinode, and since it's the first entry in the struct the llist.c traversal 13140f66f451Sopenharmony_cimechanisms work to iterate over sibling nodes. Each dirtree node is a 13150f66f451Sopenharmony_cisingle malloc() (even char *symlink points to memory at the end of the node), 13160f66f451Sopenharmony_ciso llist_free() works but its callback must descend into child nodes (freeing 13170f66f451Sopenharmony_cia tree, not just a linked list), plus whatever the user stored in extra.</p> 13180f66f451Sopenharmony_ci 13190f66f451Sopenharmony_ci<p>The <b>dirtree_flagread</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>() 13200f66f451Sopenharmony_cito create a root node relative to the current directory, then calling 13210f66f451Sopenharmony_ci<b>dirtree_handle_callback</b>() on that node (which recurses as instructed by the callback 13220f66f451Sopenharmony_cireturn flags). The flags argument primarily lets you 13230f66f451Sopenharmony_cicontrol whether or not to follow symlinks to the root node; symlinks 13240f66f451Sopenharmony_cilisted on the command line are often treated differently than symlinks 13250f66f451Sopenharmony_ciencountered during recursive directory traversal. 13260f66f451Sopenharmony_ci 13270f66f451Sopenharmony_ci<p>The ls command not only bypasses this wrapper, but never returns 13280f66f451Sopenharmony_ci<b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually 13290f66f451Sopenharmony_cifrom elsewhere in the program. This gives ls -lR manual control 13300f66f451Sopenharmony_ciof traversal order, which is neither depth first nor breadth first but 13310f66f451Sopenharmony_ciinstead a sort of FIFO order requried by the ls standard.</p> 13320f66f451Sopenharmony_ci 13330f66f451Sopenharmony_ci<a name="toys"> 13340f66f451Sopenharmony_ci<h1><a href="#toys">Directory toys/</a></h1> 13350f66f451Sopenharmony_ci 13360f66f451Sopenharmony_ci<p>This directory contains command implementations. Each command is a single 13370f66f451Sopenharmony_ciself-contained file. Adding a new command involves adding a single 13380f66f451Sopenharmony_cifile, and removing a command involves removing that file. Commands use 13390f66f451Sopenharmony_cishared infrastructure from the lib/ and generated/ directories.</p> 13400f66f451Sopenharmony_ci 13410f66f451Sopenharmony_ci<p>Currently there are five subdirectories under "toys/" containing "posix" 13420f66f451Sopenharmony_cicommands described in POSIX-2008, "lsb" commands described in the Linux 13430f66f451Sopenharmony_ciStandard Base 4.1, "other" commands not described by either standard, 13440f66f451Sopenharmony_ci"pending" commands awaiting cleanup (which default to "n" in menuconfig 13450f66f451Sopenharmony_cibecause they don't necessarily work right yet), and "example" code showing 13460f66f451Sopenharmony_cihow toybox infrastructure works and providing template/skeleton files to 13470f66f451Sopenharmony_cistart new commands.</p> 13480f66f451Sopenharmony_ci 13490f66f451Sopenharmony_ci<p>The only difference directory location makes is which menu the command 13500f66f451Sopenharmony_cishows up in during "make menuconfig", the directories are otherwise identical. 13510f66f451Sopenharmony_ciNote that the commands exist within a single namespace at runtime, so you can't 13520f66f451Sopenharmony_cihave the same command in multiple subdirectories. (The build tries to fail 13530f66f451Sopenharmony_ciinformatively when you do that.)</p> 13540f66f451Sopenharmony_ci 13550f66f451Sopenharmony_ci<p>There is one more sub-menus in "make menuconfig" containing global 13560f66f451Sopenharmony_ciconfiguration options for toybox. This menu is defined in the top level 13570f66f451Sopenharmony_ciConfig.in.</p> 13580f66f451Sopenharmony_ci 13590f66f451Sopenharmony_ci<p>See <a href="#adding">adding a new command</a> for details on the 13600f66f451Sopenharmony_cilayout of a command file.</p> 13610f66f451Sopenharmony_ci 13620f66f451Sopenharmony_ci<a name="scripts"> 13630f66f451Sopenharmony_ci<h2>Directory scripts/</h2> 13640f66f451Sopenharmony_ci 13650f66f451Sopenharmony_ci<p>Build infrastructure. The makefile calls scripts/make.sh for "make" 13660f66f451Sopenharmony_ciand scripts/install.sh for "make install".</p> 13670f66f451Sopenharmony_ci 13680f66f451Sopenharmony_ci<p>There's also a test suite, "make test" calls make/test.sh, which runs all 13690f66f451Sopenharmony_cithe tests in make/test/*. You can run individual tests via 13700f66f451Sopenharmony_ci"scripts/test.sh command", or "TEST_HOST=1 scripts/test.sh command" to run 13710f66f451Sopenharmony_cithat test against the host implementation instead of the toybox one.</p> 13720f66f451Sopenharmony_ci 13730f66f451Sopenharmony_ci<h3>scripts/cfg2files.sh</h3> 13740f66f451Sopenharmony_ci 13750f66f451Sopenharmony_ci<p>Run .config through this filter to get a list of enabled commands, which 13760f66f451Sopenharmony_ciis turned into a list of files in toys via a sed invocation in the top level 13770f66f451Sopenharmony_ciMakefile. 13780f66f451Sopenharmony_ci</p> 13790f66f451Sopenharmony_ci 13800f66f451Sopenharmony_ci<h2>Directory kconfig/</h2> 13810f66f451Sopenharmony_ci 13820f66f451Sopenharmony_ci<p>Menuconfig infrastructure copied from the Linux kernel a long time ago 13830f66f451Sopenharmony_ci(version 2.6.16). See the 13840f66f451Sopenharmony_ciLinux kernel's Documentation/kbuild/kconfig-language.txt</p> 13850f66f451Sopenharmony_ci 13860f66f451Sopenharmony_ci<!-- todo 13870f66f451Sopenharmony_ci 13880f66f451Sopenharmony_ciBetter OLDTOY and multiple command explanation. From Config.in: 13890f66f451Sopenharmony_ci 13900f66f451Sopenharmony_ci<p>A command with multiple names (or multiple similar commands implemented in 13910f66f451Sopenharmony_cithe same .c file) should have config symbols prefixed with the name of their 13920f66f451Sopenharmony_ciC file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names 13930f66f451Sopenharmony_cihave config symbols they must be options (symbols with an underscore and 13940f66f451Sopenharmony_cisuffix) to the NEWTOY() name. (See generated/toylist.h)</p> 13950f66f451Sopenharmony_ci--> 13960f66f451Sopenharmony_ci 13970f66f451Sopenharmony_ci<!--#include file="footer.html" --> 1398