toybox: www/code.html annotate

annotate www/code.html @ 1501:c51a4dbe5db7 draft

Don't segfault for --help of single.sh build of OLDTOY commands that use another command's help.

author	Rob Landley <rob@landley.net>
date	Sat, 27 Sep 2014 19:58:18 -0500
parents	44cf038d297d
children	f9926018344c

rev	line source
1180 94eb7b9127d2 Change header and pages so each page has its own title. Rob Landley <rob@landley.net> parents: 1167 diff changeset	1 <html><head><title>toybox source code walkthrough</title></head>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	2 <!--#include file="header.html" -->
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	3
1015 27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	4 <p><h1><a name="style" /><a href="#style">Code style</a></h1></p>
505 c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	5
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	6 <p>The primary goal of toybox is _simple_ code. Keeping the code small is
529 b93517f238d1 Web page updates. Rob Landley <rob@landley.net> parents: 505 diff changeset	7 second, with speed and lots of features coming in somewhere after that.
b93517f238d1 Web page updates. Rob Landley <rob@landley.net> parents: 505 diff changeset	8 (For more on that, see the <a href=design.html>design</a> page.)</p>
505 c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	9
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	10 <p>A simple implementation usually takes up fewer lines of source code,
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	11 meaning more code can fit on the screen at once, meaning the programmer can
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	12 see more of it on the screen and thus keep more if in their head at once.
529 b93517f238d1 Web page updates. Rob Landley <rob@landley.net> parents: 505 diff changeset	13 This helps code auditing and thus reduces bugs. That said, sometimes being
b93517f238d1 Web page updates. Rob Landley <rob@landley.net> parents: 505 diff changeset	14 more explicit is preferable to being clever enough to outsmart yourself:
b93517f238d1 Web page updates. Rob Landley <rob@landley.net> parents: 505 diff changeset	15 don't be so terse your code is unreadable.</p>
217 ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	16
1291 00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html. Rob Landley <rob@landley.net> parents: 1247 diff changeset	17 <p>Toybox has an actual coding style guide over on
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html. Rob Landley <rob@landley.net> parents: 1247 diff changeset	18 <a href=design.html#codestyle>the design page</a>, but in general we just
00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html. Rob Landley <rob@landley.net> parents: 1247 diff changeset	19 want the code to be consistent.</p>
217 ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	20
1015 27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	21 <p><h1><a name="building" /><a href="#building">Building Toybox</a></h1></p>
505 c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	22
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	23 <p>Toybox is configured using the Kconfig language pioneered by the Linux
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	24 kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc).
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	25 This generates a ".config" file containing the selected options, which
694 786841fdb1e0 Reindent to two spaces per level. Remove vi: directives that haven't worked right in years (ubuntu broke its' vim implementation). Remove trailing spaces. Add/remove blank lines. Re-wordwrap in places. Update documentation with new coding style. Rob Landley <rob@landley.net> parents: 677 diff changeset	26 controls which features are included when compiling toybox.</p>
505 c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	27
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	28 <p>Each configuration option has a default value. The defaults indicate the
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	29 "maximum sane configuration", I.E. if the feature defaults to "n" then it
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	30 either isn't complete or is a special-purpose option (such as debugging
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	31 code) that isn't intended for general purpose use.</p>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	32
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	33 <p>The standard build invocation is:</p>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	34
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	35 <ul>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	36 <li>make defconfig #(or menuconfig)</li>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	37 <li>make</li>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	38 <li>make install</li>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	39 </ul>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	40
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	41 <p>Type "make help" to see all available build options.</p>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	42
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	43 <p>The file "configure" contains a number of environment variable definitions
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	44 which influence the build, such as specifying which compiler to use or where
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	45 to install the resulting binaries. This file is included by the build, but
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	46 accepts existing definitions of the environment variables, so it may be sourced
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	47 or modified by the developer before building and the definitions exported
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	48 to the environment will take precedence.</p>
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	49
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	50 <p>(To clarify: "configure" describes the build and installation environment,
c08cd17224c0 Make documentation even fluffier. Rob Landley <rob@landley.net> parents: 501 diff changeset	51 ".config" lists the features selected by defconfig/menuconfig.)</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	52
1015 27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	53 <p><h1><a name="running"><a href="#running">Running a command</a></h1></p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	54
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	55 <h2>main</h2>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	56
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	57 <p>The toybox main() function is at the end of main.c at the top level. It has
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	58 two possible codepaths, only one of which is configured into any given build
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	59 of toybox.</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	60
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	61 <p>If CONFIG_SINGLE is selected, toybox is configured to contain only a single
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	62 command, so most of the normal setup can be skipped. In this case the
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	63 multiplexer isn't used, instead main() calls toy_singleinit() (also in main.c)
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	64 to set up global state and parse command line arguments, calls the command's
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	65 main 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
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	66 it flushes stdout (detecting error) and returns toys.exitval.</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	67
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	68 <p>When CONFIG_SINGLE is not selected, main() uses basename() to find the
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	69 name it was run as, shifts its argument list one to the right so it lines up
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	70 with where the multiplexer function expects it, and calls toybox_main(). This
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	71 leverages the multiplexer command's infrastructure to find and run the
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	72 appropriate command. (A command name starting with "toybox" will
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	73 recursively call toybox_main(); you can go "./toybox toybox toybox toybox ls"
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	74 if you want to...)</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	75
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	76 <h2>toybox_main</h2>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	77
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	78 <p>The toybox_main() function is also in main,c. It handles a possible
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	79 --help option ("toybox --help ls"), prints the list of available commands if no
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	80 arguments were provided to the multiplexer (or with full path names if any
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	81 other option is provided before a command name, ala "toybox --list").
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	82 Otherwise it calls toy_exec() on its argument list.</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	83
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	84 <p>Note that the multiplexer is the first entry in toy_list (the rest of the
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	85 list is sorted alphabetically to allow binary search), so toybox_main can
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	86 cheat and just grab the first entry to quickly set up its context without
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	87 searching. Since all command names go through the multiplexer at least once
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	88 in the non-TOYBOX_SINGLE case, this avoids a redundant search of
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	89 the list.</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	90
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	91 <p>The toy_exec() function is also in main.c. It performs toy_find() to
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	92 perform a binary search on the toy_list array to look up the command's
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	93 entry by name and saves it in the global variable which, calls toy_init()
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	94 to parse command line arguments and set up global state (using which->options),
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	95 and calls the appropriate command's main() function (which->toy_main). On
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	96 return it flushes all pending ansi FILE * I/O, detects if stdout had an
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	97 error, and then calls xexit() (which uses toys.exitval).</p>
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	98
27275d0d97e9 Document the toybox entry path from main() into a command. Rob Landley <rob@landley.net> parents: 694 diff changeset	99 <p><h1><a name="infrastructure" /><a href="#infrastructure">Infrastructure</a></h1></p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	100
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	101 <p>The toybox source code is in following directories:</p>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	102 <ul>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	103 <li>The <a href="#top">top level directory</a> contains the file main.c (were
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	104 execution starts), the header file toys.h (included by every command), and
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	105 other global infrastructure.</li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	106 <li>The <a href="#lib">lib directory</a> contains common functions shared by
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	107 multiple commands:</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	108 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	109 <li><a href="#lib_lib">lib/lib.c</a></li>
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	110 <li><a href="#lib_xwrap">lib/xwrap.c</a></li>
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	111 <li><a href="#lib_llist">lib/llist.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	112 <li><a href="#lib_args">lib/args.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	113 <li><a href="#lib_dirtree">lib/dirtree.c</a></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	114 </ul>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	115 <li>The <a href="#toys">toys directory</a> contains the C files implementating
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	116 each command. Currently it contains five subdirectories categorizing the
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	117 commands: posix, lsb, other, example, and pending.</li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	118 <li>The <a href="#scripts">scripts directory</a> contains the build and
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	119 test infrastructure.</li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	120 <li>The <a href="#kconfig">kconfig directory</a> contains the configuration
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	121 infrastructure implementing menuconfig (copied from the Linux kernel).</li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	122 <li>The <a href="#generated">generated directory</a> contains intermediate
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	123 files generated from other parts of the source code.</li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	124 </ul>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	125
501 8abb9e307d0c Web page tweaks. Remove background image (makes it hard ot read for some people), and use local roadmap instead of third party wiki. Rob Landley <rob@landley.net> parents: 432 diff changeset	126 <a name="adding" />
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	127 <p><h1><a href="#adding">Adding a new command</a></h1></p>
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	128 <p>To add a new command to toybox, add a C file implementing that command to
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	129 one of the subdirectories under the toys directory. No other files need to
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	130 be modified; the build extracts all the information it needs (such as command
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	131 line arguments) from specially formatted comments and macros in the C file.
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	132 (See the description of the <a href="#generated">"generated" directory</a>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	133 for details.)</p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	134
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	135 <p>Currently there are five subdirectories under "toys", one for commands
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	136 defined by the POSIX standard, one for commands defined by the Linux Standard
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	137 Base, an "other" directory for commands not covered by an obvious standard,
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	138 a directory of example commands (templates to use when starting new commands),
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	139 and a "pending" directory of commands that need further review/cleanup
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	140 before moving to one of the other directories (run these at your own risk,
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	141 cleanup patches welcome).
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	142 These directories are just for developer convenience sorting the commands,
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	143 the directories are otherwise functionally identical. To add a new category,
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	144 create the appropriate directory with a README file in it whose first line
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	145 is the description menuconfig should use for the directory.)</p>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	146
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	147 <p>An easy way to start a new command is copy the file "toys/example/hello.c"
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	148 to the name of the new command, and modify this copy to implement the new
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	149 command (more or less by turning every instance of "hello" into the
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	150 name of your command, updating the command line arguments, globals, and
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	151 help data, and then filling out its "main" function with code that does
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	152 something interesting).</p>
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	153
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	154 <p>You could also start with "toys/example/skeleton.c", which provides a lot
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	155 more example code (showing several variants of command line option
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	156 parsing, how to implement multiple commands in the same file, and so on).
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	157 But usually it's just more stuff to delete.</p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	158
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	159 <p>Here's a checklist of steps to turn hello.c into another command:</p>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	160
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	161 <ul>
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	162 <li><p>First "cp toys/example/hello.c toys/other/yourcommand.c" and open
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	163 the new file in your preferred text editor.</p>
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	164 <ul><li><p>Note that the
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	165 name of the new file is significant: it's the name of the new command you're
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	166 adding to toybox. The build includes all .c files under toys// whose
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	167 names are a case insensitive match for an enabled config symbol. So
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	168 toys/posix/cat.c only gets included if you have "CAT=y" in ".config".</p></li>
2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	169 </ul></p></li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	170
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	171 <li><p>Change the one line comment at the top of the file (currently
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	172 "hello.c - A hello world program") to describe your new file.</p></li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	173
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	174 <li><p>Change the copyright notice to your name, email, and the current
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	175 year.</p></li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	176
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	177 <li><p>Give a URL to the relevant standards document, where applicable.
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	178 (Sample links to SUSv4 and LSB are provided, feel free to link to other
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	179 documentation or standards as appropriate.)</p></li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	180
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	181 <li><p>Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line.
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	182 The NEWTOY macro fills out this command's <a href="#toy_list">toy_list</a>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	183 structure. The arguments to the NEWTOY macro are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	184
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	185 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	186 <li><p>the name used to run your command</p></li>
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	187 <li><p>the command line argument <a href="#lib_args">option parsing string</a> (0 if none)</p></li>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	188 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	189 (defined in toys.h) providing additional information such as where your
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	190 command should be installed on a running system, whether to blank umask
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	191 before running, whether or not the command must run as root (and thus should
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	192 retain root access if installed SUID), and so on.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	193 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	194 </li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	195
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	196 <li><p>Change the kconfig data (from "config YOURCOMMAND" to the end of the
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	197 comment block) to supply your command's configuration and help
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	198 information. The uppper case config symbols are used by menuconfig, and are
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	199 also what the CFG_ and USE_() macros are generated from (see [TODO]). The
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	200 help information here is used by menuconfig, and also by the "help" command to
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	201 describe your new command. (See [TODO] for details.) By convention,
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	202 unfinished commands default to "n" and finished commands default to "y",
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	203 so "make defconfig" selects all finished commands. (Note, "finished" means
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	204 "ready to be used", not that it'll never change again.)<p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	205
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	206 <p>Each help block should start with a "usage: yourcommand" line explaining
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	207 any command line arguments added by this config option. The "help" command
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	208 outputs this text, and scripts/config2help.c in the build infrastructure
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	209 collates these usage lines for commands with multiple configuration
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	210 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	211 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	212
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	213 <li><p>Change the "#define FOR_hello" line to "#define FOR_yourcommand" right
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	214 before the "#include <toys.h>". (This selects the appropriate FLAG_ macros and
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	215 does a "#define TT this.yourcommand" so you can access the global variables
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	216 out of the space-saving union of structures. If you aren't using any command
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	217 flag bits and aren't defining a GLOBAL block, you can delete this line.)</p></li>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	218
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	219 <li><p>Update the GLOBALS() macro to contain your command's global
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	220 variables. If your command has no global variables, delete this macro.</p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	221
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	222 <p>Variables in the GLOBALS() block are are stored in a space saving
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	223 <a href="#toy_union">union of structures</a> format, which may be accessed
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	224 using the TT macro as if TT were a global structure (so TT.membername).
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	225 If you specified two-character command line arguments in
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	226 NEWTOY(), the first few global variables will be initialized by the automatic
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	227 argument parsing logic, and the type and order of these variables must
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	228 correspond to the arguments specified in NEWTOY().
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	229 (See <a href="#lib_args">lib/args.c</a> for details.)</p></li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	230
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	231 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	232 where execution of your command starts. Your command line options are
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	233 already sorted into this.optflags, this.optargs, this.optc, and the GLOBALS()
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	234 as appropriate by the time this function is called. (See
1303 2b89b13df19e Update docs for example and pending directories. Rob Landley <rob@landley.net> parents: 1291 diff changeset	235 <a href="#lib_args">get_optflags()</a> for details.)</p></li>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	236 </ul>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	237
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	238 <a name="headers" /><h2><a href="#headers">Headers.</a></h2>
1167 17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	239
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	240 <p>Commands generally don't have their own headers. If it's common code
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	241 it can live in lib/, if it isn't put it in the command's .c file. (The line
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	242 between implementing multiple commands in a C file via OLDTOY() to share
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	243 infrastructure and moving that shared infrastructure to lib/ is a judgement
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	244 call. Try to figure out which is simplest.)</p>
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	245
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	246 <p>The top level toys.h should #include all the standard (posix) headers
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	247 that any command uses. (Partly this is friendly to ccache and partly this
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	248 makes the command implementations shorter.) Individual commands should only
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	249 need to include nonstandard headers that might prevent that command from
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	250 building in some context we'd care about (and thus requiring that command to
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	251 be disabled to avoid a build break).</p>
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	252
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	253 <p>Target-specific stuff (differences between compiler versions, libc versions,
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	254 or operating systems) should be confined to lib/portability.h and
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	255 lib/portability.c. (There's even some minimal compile-time environment probing
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	256 that writes data to generated/portability.h, see scripts/genconfig.sh.)</p>
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	257
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	258 <p>Only include linux/*.h headers from individual commands (not from other
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	259 headers), and only if you really need to. Data that varies per architecture
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	260 is a good reason to include a header. If you just need a couple constants
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	261 that haven't changed since the 1990's, it's ok to #define them yourself or
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	262 just use the constant inline with a comment explaining what it is. (A
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	263 #define that's only used once isn't really helping.)</p>
17387db4d979 New section on #including header files. Rob Landley <rob@landley.net> parents: 1073 diff changeset	264
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	265 <p><a name="top" /><h1><a href="#top">Top level directory.</a></h1></p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	266
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	267 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	268
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	269 <h3>toys.h</h3>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	270 <p>Each command #includes "toys.h" as part of its standard prolog. It
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	271 may "#define FOR_commandname" before doing so to get some extra entries
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	272 specific to this command.</p>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	273
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	274 <p>This file sucks in most of the commonly used standard #includes, so
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	275 individual files can just #include "toys.h" and not have to worry about
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	276 stdargs.h and so on. Individual commands still need to #include
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	277 special-purpose headers that may not be present on all systems (and thus would
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	278 prevent toybox from building that command on such a system with that command
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	279 enabled). Examples include regex support, any "linux/" or "asm/" headers, mtab
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	280 support (mntent.h and sys/mount.h), and so on.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	281
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	282 <p>The toys.h header also defines structures for most of the global variables
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	283 provided to each command by toybox_main(). These are described in
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	284 detail in the description for main.c, where they are initialized.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	285
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	286 <p>The global variables are grouped into structures (and a union) for space
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	287 savings, to more easily track the amount of memory consumed by them,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	288 so that they may be automatically cleared/initialized as needed, and so
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	289 that access to global variables is more easily distinguished from access to
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	290 local variables.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	291
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	292 <h3>main.c</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	293 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	294 common infrastructure to initialize global variables and select which command
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	295 to run. The "toybox" multiplexer command also lives here. (This is the
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	296 only command defined outside of the toys directory.)</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	297
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	298 <p>Execution starts in main() which trims any path off of the first command
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	299 name and calls toybox_main(), which calls toy_exec(), which calls toy_find()
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	300 and toy_init() before calling the appropriate command's function from
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	301 toy_list[] (via toys.which->toy_main()).
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	302 If the command is "toybox", execution recurses into toybox_main(), otherwise
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	303 the call goes to the appropriate commandname_main() from a C file in the toys
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	304 directory.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	305
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	306 <p>The following global variables are defined in main.c:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	307 <ul>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	308 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	309 <li><p><b>struct toy_list toy_list[]</b> - array describing all the
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	310 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	311 for the "toybox" multiplexer command, which runs all the other built-in commands
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	312 without symlinks by using its first argument as the name of the command to
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	313 run and the rest as that command's argument list (ala "./toybox echo hello").
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	314 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	315 binary search).</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	316
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	317 <p>This is a read-only array initialized at compile time by
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	318 defining macros and #including generated/newtoys.h.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	319
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	320 <p>Members of struct toy_list (defined in "toys.h") include:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	321 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	322 <li><p>char *<b>name</b> - the name of this command.</p></li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	323 <li><p>void (*<b>toy_main</b>)(void) - function pointer to run this
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	324 command.</p></li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	325 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	326 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	327 entries in the toy's GLOBALS struct). When this is NULL, no option
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	328 parsing is done before calling toy_main().</p></li>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	329 <li><p>int <b>flags</b> - Behavior flags for this command. The following flags are currently understood:</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	330
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	331 <ul>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	332 <li><b>TOYFLAG_USR</b> - Install this command under /usr</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	333 <li><b>TOYFLAG_BIN</b> - Install this command under /bin</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	334 <li><b>TOYFLAG_SBIN</b> - Install this command under /sbin</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	335 <li><b>TOYFLAG_NOFORK</b> - This command can be used as a shell builtin.</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	336 <li><b>TOYFLAG_UMASK</b> - Call umask(0) before running this command.</li>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	337 <li><b>TOYFLAG_STAYROOT</b> - Don't drop permissions for this command if toybox is installed SUID root.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	338 <li><b>TOYFLAG_NEEDROOT</b> - This command cannot function unless run with root access.</li>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	339 </ul>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	340 <br>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	341
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	342 <p>These flags are combined with \| (or). For example, to install a command
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	343 in /usr/bin, or together TOYFLAG_USR\|TOYFLAG_BIN.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	344 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	345 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	346
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	347 <li><p><b>struct toy_context toys</b> - global structure containing information
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	348 common to all commands, initializd by toy_init() and defined in "toys.h".
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	349 Members of this structure include:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	350 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	351 <li><p>struct toy_list *<b>which</b> - a pointer to this command's toy_list
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	352 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	353 (toys->which.name).</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	354 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	355 <li><p>int <b>exitval</b> - Exit value of this command. Defaults to zero. The
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	356 error_exit() functions will return 1 if this is zero, otherwise they'll
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	357 return this value.</p></li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	358 <li><p>char **<b>argv</b> - "raw" command line options, I.E. the original
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	359 unmodified string array passed in to main(). Note that modifying this changes
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	360 "ps" output, and is not recommended. This array is null terminated; a NULL
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	361 entry indicates the end of the array.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	362 <p>Most commands don't use this field, instead the use optargs, optflags,
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	363 and the fields in the GLOBALS struct initialized by get_optflags().</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	364 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	365 <li><p>unsigned <b>optflags</b> - Command line option flags, set by
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	366 <a href="#lib_args">get_optflags()</a>. Indicates which of the command line options listed in
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	367 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	368
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	369 <p>The rightmost command line argument listed in toys->which.options sets bit
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	370 1, the next one sets bit 2, and so on. This means the bits are set in the same
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	371 order the binary digits would be listed if typed out as a string. For example,
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	372 the option string "abcd" would parse the command line "-c" to set optflags to 2,
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	373 "-a" would set optflags to 8, and "-bd" would set optflags to 6 (4\|2).</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	374
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	375 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2,
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	376 b=4, a=8. Punctuation after a letter initializes global variables at the
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	377 start of the GLOBALS() block (see <a href="#toy_union">union toy_union this</a>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	378 for details).</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	379
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	380 <p>The build infrastructure creates FLAG_ macros for each option letter,
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	381 corresponding to the bit position, so you can check (toys.optflags & FLAG_x)
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	382 to see if a flag was specified. (The correct set of FLAG_ macros is selected
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	383 by defining FOR_mycommand before #including toys.h. The macros live in
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	384 toys/globals.h which is generated by scripts/make.sh.)</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	385
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	386 <p>For more information on option parsing, see <a href="#lib_args">get_optflags()</a>.</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	387
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	388 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	389 <li><p>char **<b>optargs</b> - Null terminated array of arguments left over
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	390 after get_optflags() removed all the ones it understood. Note: optarg[0] is
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	391 the first argument, not the command name. Use toys.which->name for the command
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	392 name.</p></li>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	393 <li><p>int <b>optc</b> - Optarg count, equivalent to argc but for
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	394 optargs[].<p></li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	395 <li><p>int <b>exithelp</b> - Whether error_exit() should print a usage message
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	396 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	397 false afterwards.)</p></li>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	398 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	399
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	400 <a name="toy_union" />
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	401 <li><p><b>union toy_union this</b> - Union of structures containing each
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	402 command's global variables.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	403
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	404 <p>Global variables are useful: they reduce the overhead of passing extra
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	405 command line arguments between functions, they conveniently start prezeroed to
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	406 save initialization costs, and the command line argument parsing infrastructure
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	407 can also initialize global variables with its results.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	408
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	409 <p>But since each toybox process can only run one command at a time, allocating
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	410 space for global variables belonging to other commands you aren't currently
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	411 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	412
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	413 <p>Toybox handles this by encapsulating each command's global variables in
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	414 a structure, and declaring a union of those structures with a single global
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	415 instance (called "this"). The GLOBALS() macro contains the global
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	416 variables that should go in the current command's global structure. Each
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	417 variable can then be accessed as "this.commandname.varname".
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	418 If you #defined FOR_commandname before including toys.h, the macro TT is
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	419 #defined to this.commandname so the variable can then be accessed as
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	420 "TT.variable". See toys/hello.c for an example.</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	421
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	422 <p>A command that needs global variables should declare a structure to
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	423 contain them all, and add that structure to this union. A command should never
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	424 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	425 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	426 variables.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	427
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	428 <p>The first few fields of this structure can be intialized by <a href="#lib_args">get_optargs()</a>,
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	429 as specified by the options field off this command's toy_list entry. See
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	430 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	431 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	432
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	433 <li><b>char toybuf[4096]</b> - a common scratch space buffer so
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	434 commands don't need to allocate their own. Any command is free to use this,
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	435 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	436 commands are free to pass toybuf in to a library function as an argument).</li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	437 </ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	438
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	439 <p>The following functions are defined in main.c:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	440 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	441 <li><p>struct toy_list <b>toy_find</b>(char name) - Return the toy_list
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	442 structure for this command name, or NULL if not found.</p></li>
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	443 <li><p>void <b>toy_init</b>(struct toy_list which, char argv[]) - fill out
a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	444 the global toys structure, calling get_optargs() if necessary.</p></li>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	445 <li><p>void <b>toy_exec</b>(char *argv[]) - Run a built-in command with
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	446 arguments.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	447 <p>Calls toy_find() on argv[0] (which must be just a command name
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	448 without path). Returns if it can't find this command, otherwise calls
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	449 toy_init(), toys->which.toy_main(), and exit() instead of returning.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	450
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	451 <p>Use the library function xexec() to fall back to external executables
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	452 in $PATH if toy_exec() can't find a built-in command. Note that toy_exec()
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	453 does not strip paths before searching for a command, so "./command" will
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	454 never match an internal command.</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	455
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	456 <li><p>void <b>toybox_main</b>(void) - the main function for the multiplexer
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	457 command (I.E. "toybox"). Given a command name as its first argument, calls
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	458 toy_exec() on its arguments. With no arguments, it lists available commands.
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	459 If the first argument starts with "-" it lists each command with its default
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	460 install path prepended.</p></li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	461
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	462 </ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	463
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	464 <h3>Config.in</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	465
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	466 <p>Top level configuration file in a stylized variant of
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	467 <a href=http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt>kconfig</a> format. Includes generated/Config.in.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	468
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	469 <p>These files are directly used by "make menuconfig" to select which commands
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	470 to build into toybox (thus generating a .config file), and by
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	471 scripts/config2help.py to create generated/help.h.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	472
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	473 <a name="generated" />
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	474 <h1><a href="#generated">Temporary files:</a></h1>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	475
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	476 <p>There is one temporary file in the top level source directory:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	477 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	478 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	479 which commands (and options to commands) are currently enabled. Used
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	480 to make generated/config.h and determine which toys//.c files to build.</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	481
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	482 <p>You can create a human readable "miniconfig" version of this file using
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	483 <a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	484 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	485 </li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	486 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	487
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	488 <p><h2>Directory generated/</h2></p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	489
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	490 <p>The remaining temporary files live in the "generated/" directory,
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	491 which is for files generated at build time from other source files.</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	492
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	493 <ul>
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	494 <li><p><b>generated/Config.in</b> - Kconfig entries for each command, included
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	495 from the top level Config.in. The help text here is used to generate
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	496 help.h.</p>
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	497
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	498 <p>Each command has a configuration entry with an upper case version of
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	499 the command name. Options to commands start with the command
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	500 name followed by an underscore and the option name. Global options are attached
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	501 to the "toybox" command, and thus use the prefix "TOYBOX_". This organization
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	502 is used by scripts/cfg2files to select which toys//.c files to compile for a
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	503 given .config.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	504 </li>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	505
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	506 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	507 generated from .config by a sed invocation in scripts/make.sh.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	508
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	509 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	510 disabled symbols. This allows the use of normal if() statements to remove
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	511 code at compile time via the optimizer's dead code elimination (which removes
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	512 from the binary any code that cannot be reached). This saves space without
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	513 cluttering the code with #ifdefs or leading to configuration dependent build
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	514 breaks. (See the 1992 Usenix paper
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	515 <a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	516 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	517
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	518 <p>When you can't entirely avoid an #ifdef, the USE_SYMBOL(code) macro
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	519 provides a less intrusive alternative, evaluating to the code in parentheses
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	520 when the symbol is enabled, and nothing when the symbol is disabled. This
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	521 is most commonly used around NEWTOY() declarations (so only the enabled
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	522 commands show up in toy_list), and in option strings. This can also be used
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	523 for things like varargs or structure members which can't always be
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	524 eliminated by a simple test on CFG_SYMBOL. Remember, unlike CFG_SYMBOL
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	525 this is really just a variant of #ifdef, and can still result in configuration
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	526 dependent build breaks. Use with caution.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	527 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	528
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	529 <li><p><b>generated/flags.h</b> - FLAG_? macros indicating which command
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	530 line options were seen. The option parsing in lib/args.c sets bits in
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	531 toys.optflags, which can be tested by anding with the appropriate FLAG_
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	532 macro. (Bare longopts, which have no corresponding short option, will
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	533 have the longopt name after FLAG_. All others use the single letter short
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	534 option.)</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	535
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	536 <p>To get the appropriate macros for your command, #define FOR_commandname
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	537 before #including toys.h. To switch macro sets (because you have an OLDTOY()
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	538 with different options in the same .c file), #define CLEANUP_oldcommand
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	539 and also #define FOR_newcommand, then #include "generated/flags.h" to switch.
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	540 </p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	541 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	542
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	543 <li><p><b>generated/globals.h</b> -
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	544 Declares structures to hold the contents of each command's GLOBALS(),
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	545 and combines them into "global_union this". (Yes, the name was
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	546 chosen to piss off C++ developers who think that C
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	547 is merely a subset of C++, not a language in its own right.)</p>
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	548
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	549 <p>The union reuses the same memory for each command's global struct:
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	550 since only one command's globals are in use at any given time, collapsing
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	551 them together saves space. The headers #define TT to the appropriate
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	552 "this.commandname", so you can refer to the current command's global
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	553 variables out of "this" as TT.variablename.</p>
213 db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	554
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	555 <p>The globals start zeroed, and the first few are filled out by the
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	556 lib/args.c argument parsing code called from main.c.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	557 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	558
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	559 <li><p><b>toys/help.h</b> - Help strings for use by the "help" command and
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	560 --help options. This file #defines a help_symbolname string for each
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	561 symbolname, but only the symbolnames matching command names get used
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	562 by show_help() in lib/help.c to display help for commands.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	563
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	564 <p>This file is created by scripts/make.sh, which compiles scripts/config2help.c
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	565 into the binary generated/config2help, and then runs it against the top
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	566 level .config and Config.in files to extract the help text from each config
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	567 entry and collate together dependent options.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	568
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	569 <p>This file contains help text for all commands, regardless of current
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	570 configuration, but only the ones currently enabled in the .config file
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	571 wind up in the help_data[] array, and only the enabled dependent options
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	572 have their help text added to the command they depend on.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	573 </li>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	574
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	575 <li><p><b>generated/newtoys.h</b> -
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	576 All the NEWTOY() and OLDTOY() macros from toys//.c. The "toybox" multiplexer
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	577 is the first entry, the rest are in alphabetical order. Each line should be
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	578 inside an appropriate USE_ macro, so code that #includes this file only sees
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	579 the currently enabled commands.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	580
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	581 <p>By #definining NEWTOY() to various things before #including this file,
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	582 it may be used to create function prototypes (in toys.h), initialize the
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	583 help_data array (in lib/help.c), initialize the toy_list array (in main.c,
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	584 the alphabetical order lets toy_find() do a binary search, the exception to
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	585 the alphabetical order lets it use the multiplexer without searching), and so
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	586 on. (It's even used to initialize the NEED_OPTIONS macro, which produces a 1
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	587 or 0 for each command using command line option parsing, which is ORed together
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	588 to allow compile-time dead code elimination to remove the whole of
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	589 lib/args.c if nothing currently enabled is using it.)<p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	590
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	591 <p>Each NEWTOY and OLDTOY macro contains the command name, command line
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	592 option string (telling lib/args.c how to parse command line options for
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	593 this command), recommended install location, and miscelaneous data such
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	594 as whether this command should retain root permissions if installed suid.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	595 </li>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	596
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	597 <li><p><b>toys/oldtoys.h</b> - Macros with the command line option parsing
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	598 string for each NEWTOY. This allows an OLDTOY that's just an alias for an
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	599 existing command to refer to the existing option string instead of
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	600 having to repeat it.</p>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	601 </li>
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	602 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	603
536 2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	604 <a name="lib">
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	605 <h2>Directory lib/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	606
536 2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	607 <p>TODO: document lots more here.</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	608
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	609 <p>lib: getmountlist(), error_msg/error_exit, xmalloc(),
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	610 strlcpy(), xexec(), xopen()/xread(), xgetcwd(), xabspath(), find_in_path(),
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	611 itoa().</p>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	612
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	613
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	614
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	615 <a name="lib_xwrap"><h3>lib/xwrap.c</h3>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	616
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	617 <p>Functions prefixed with the letter x call perror_exit() when they hit
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	618 errors, to eliminate common error checking. This prints an error message
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	619 and the strerror() string for the errno encountered.</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	620
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	621 <p>You can intercept this exit by assigning a setjmp/longjmp buffer to
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	622 toys.rebound (set it back to zero to restore the default behavior).
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	623 If you do this, cleaning up resource leaks is your problem.</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	624
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	625 <ul>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	626 <li><b>void xstrncpy(char dest, char src, size_t size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	627 <li><b>void xexit(void)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	628 <li><b>void *xmalloc(size_t size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	629 <li><b>void *xzalloc(size_t size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	630 <li><b>void xrealloc(void ptr, size_t size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	631 <li><b>char xstrndup(char s, size_t n)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	632 <li><b>char xstrdup(char s)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	633 <li><b>char xmprintf(char format, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	634 <li><b>void xprintf(char *format, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	635 <li><b>void xputs(char *s)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	636 <li><b>void xputc(char c)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	637 <li><b>void xflush(void)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	638 <li><b>pid_t xfork(void)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	639 <li><b>void xexec_optargs(int skip)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	640 <li><b>void xexec(char **argv)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	641 <li><b>pid_t xpopen(char *argv, int pipes)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	642 <li><b>int xpclose(pid_t pid, int *pipes)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	643 <li><b>void xaccess(char *path, int flags)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	644 <li><b>void xunlink(char *path)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	645 <li><p><b>int xcreate(char *path, int flags, int mode)<br />
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	646 int xopen(char *path, int flags)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	647
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	648 <p>The xopen() and xcreate() functions open an existing file (exiting if
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	649 it's not there) and create a new file (exiting if it can't).</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	650
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	651 <p>They default to O_CLOEXEC so the filehandles aren't passed on to child
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	652 processes. Feed in O_CLOEXEC to disable this.</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	653 </li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	654 <li><p><b>void xclose(int fd)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	655
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	656 <p>Because NFS is broken, and won't necessarily perform the requested
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	657 operation (and report the error) until you close the file. Of course, this
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	658 being NFS, it's not guaranteed to report the error there either, but it
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	659 _can_.</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	660
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	661 <p>Nothing else ever reports an error on close, everywhere else it's just a
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	662 VFS operation freeing some resources. NFS is _special_, in a way that
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	663 other network filesystems like smbfs and v9fs aren't..</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	664 </li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	665 <li><b>int xdup(int fd)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	666 <li><p><b>size_t xread(int fd, void *buf, size_t len)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	667
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	668 <p>Can return 0, but not -1.</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	669 </li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	670 <li><p><b>void xreadall(int fd, void *buf, size_t len)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	671
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	672 <p>Reads the entire len-sized buffer, retrying to complete short
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	673 reads. Exits if it can't get enough data.</p></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	674
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	675 <li><p><b>void xwrite(int fd, void *buf, size_t len)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	676
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	677 <p>Retries short writes, exits if can't write the entire buffer.</p></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	678
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	679 <li><b>off_t xlseek(int fd, off_t offset, int whence)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	680 <li><b>char *xgetcwd(void)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	681 <li><b>void xstat(char path, struct stat st)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	682 <li><p><b>char xabspath(char path, int exact) </b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	683
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	684 <p>After several years of
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	685 <a href=http://landley.net/notes-2007.html#18-06-2007>wrestling</a>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	686 <a href=http://landley.net/notes-2008.html#19-01-2008>with</a> realpath(),
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	687 I broke down and <a href=http://landley.net/notes-2012.html#20-11-2012>wrote
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	688 my own</a> implementation that doesn't use the one in libc. As I explained:
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	689
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	690 <blockquote><p>If the path ends with a broken link,
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	691 readlink -f should show where the link points to, not where the broken link
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	692 lives. (The point of readlink -f is "if I write here, where would it attempt
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	693 to create a file".) The problem is, realpath() returns NULL for a path ending
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	694 with a broken link, and I can't beat different behavior out of code locked
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	695 away in libc.</p></blockquote>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	696
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	697 <p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	698 </li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	699 <li><b>void xchdir(char *path)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	700 <li><b>void xchroot(char *path)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	701
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	702 <li><p><b>struct passwd *xgetpwuid(uid_t uid)<br />
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	703 struct group *xgetgrgid(gid_t gid)<br />
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	704 struct passwd xgetpwnam(char name)</b></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	705
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	706 <p></p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	707 </li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	708
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	709
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	710
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	711 <li><b>void xsetuser(struct passwd *pwd)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	712 <li><b>char xreadlink(char name)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	713 <li><b>char xreadfile(char name, char *buf, off_t len)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	714 <li><b>int xioctl(int fd, int request, void *data)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	715 <li><b>void xpidfile(char *name)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	716 <li><b>void xsendfile(int in, int out)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	717 <li><b>long xparsetime(char arg, long units, long fraction)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	718 <li><b>void xregcomp(regex_t preg, char regex, int cflags)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	719 </ul>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	720
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	721 <a name="lib_lib"><h3>lib/lib.c</h3>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	722 <p>Eight gazillion common functions:</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	723
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	724 <ul>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	725 <li><b>void verror_msg(char *msg, int err, va_list va)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	726 <li><b>void error_msg(char *msg, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	727 <li><b>void perror_msg(char *msg, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	728 <li><b>void error_exit(char *msg, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	729 <li><b>void perror_exit(char *msg, ...)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	730 <li><b>ssize_t readall(int fd, void *buf, size_t len)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	731 <li><b>ssize_t writeall(int fd, void *buf, size_t len)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	732 <li><b>off_t lskip(int fd, off_t offset)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	733 <li><b>int mkpathat(int atfd, char *dir, mode_t lastmode, int flags)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	734 <li><b>struct string_list *splitpath(char path, struct string_list **list)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	735 <li><b>struct string_list find_in_path(char path, char *filename)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	736 <li><b>long atolx(char *numstr)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	737 <li><b>long atolx_range(char *numstr, long low, long high)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	738 <li><b>int numlen(long l)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	739 <li><b>int stridx(char *haystack, char needle)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	740 <li><b>int strstart(char *a, char b)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	741 <li><b>off_t fdlength(int fd)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	742 <li><b>char readfile(char name, char *ibuf, off_t len)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	743 <li><b>void msleep(long miliseconds)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	744 <li><b>int64_t peek_le(void *ptr, unsigned size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	745 <li><b>int64_t peek_be(void *ptr, unsigned size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	746 <li><b>int64_t peek(void *ptr, unsigned size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	747 <li><b>void poke(void *ptr, uint64_t val, int size)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	748 <li><b>void loopfiles_rw(char **argv, int flags, int permissions, int failok,</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	749 <li><b>void loopfiles(char *argv, void (function)(int fd, char *name))</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	750 <li><b>char get_rawline(int fd, long plen, char end)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	751 <li><b>char *get_line(int fd)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	752 <li><b>int wfchmodat(int fd, char *name, mode_t mode)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	753 <li><b>static void tempfile_handler(int i)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	754 <li><b>int copy_tempfile(int fdin, char name, char *tempname)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	755 <li><b>void delete_tempfile(int fdin, int fdout, char **tempname)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	756 <li><b>void replace_tempfile(int fdin, int fdout, char **tempname)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	757 <li><b>void crc_init(unsigned int *crc_table, int little_endian)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	758 <li><b>int terminal_size(unsigned xx, unsigned yy)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	759 <li><b>int yesno(char *prompt, int def)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	760 <li><b>void generic_signal(int sig)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	761 <li><b>void sigatexit(void *handler)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	762 <li><b>int sig_to_num(char *pidstr)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	763 <li><b>char *num_to_sig(int sig)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	764 <li><b>mode_t string_to_mode(char *modestr, mode_t mode)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	765 <li><b>void mode_to_string(mode_t mode, char *buf)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	766 <li><b>void names_to_pid(char *names, int (callback)(pid_t pid, char *name))</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	767 <li><b>int human_readable(char *buf, unsigned long long num)</b></li>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	768 </ul>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	769
536 2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	770 <h3>lib/portability.h</h3>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	771
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	772 <p>This file is automatically included from the top of toys.h, and smooths
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	773 over differences between platforms (hardware targets, compilers, C libraries,
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	774 operating systems, etc).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	775
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	776 <p>This file provides SWAP macros (SWAP_BE16(x) and SWAP_LE32(x) and so on).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	777
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	778 <p>A macro like SWAP_LE32(x) means "The value in x is stored as a little
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	779 endian 32 bit value, so perform the translation to/from whatever the native
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	780 32-bit format is". You do the swap once on the way in, and once on the way
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	781 out. If your target is already little endian, the macro is a NOP.</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	782
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	783 <p>The SWAP macros come in BE and LE each with 16, 32, and 64 bit versions.
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	784 In each case, the name of the macro refers to the _external_ representation,
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	785 and converts to/from whatever your native representation happens to be (which
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	786 can vary depending on what you're currently compiling for).</p>
2c1cb0d35031 Add lib/portability.h description with explanation of SWAP() macros. Rob Landley <rob@landley.net> parents: 529 diff changeset	787
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	788 <a name="lib_llist"><h3>lib/llist.c</h3>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	789
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	790 <p>Some generic single and doubly linked list functions, which take
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	791 advantage of a couple properties of C:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	792
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	793 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	794 <li><p>Structure elements are laid out in memory in the order listed, and
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	795 the first element has no padding. This means you can always treat (typecast)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	796 a pointer to a structure as a pointer to the first element of the structure,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	797 even if you don't know anything about the data following it.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	798
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	799 <li><p>An array of length zero at the end of a structure adds no space
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	800 to the sizeof() the structure, but if you calculate how much extra space
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	801 you want when you malloc() the structure it will be available at the end.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	802 Since C has no bounds checking, this means each struct can have one variable
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	803 length array.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	804 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	805
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	806 <p>Toybox's list structures always have their <b>next</b> pointer as
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	807 the first entry of each struct, and singly linked lists end with a NULL pointer.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	808 This allows generic code to traverse such lists without knowing anything
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	809 else about the specific structs composing them: if your pointer isn't NULL
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	810 typecast it to void ** and dereference once to get the next entry.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	811
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	812 <p><b>lib/lib.h</b> defines three structure types:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	813 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	814 <li><p><b>struct string_list</b> - stores a single string (<b>char str[0]</b>),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	815 memory for which is allocated as part of the node. (I.E. llist_traverse(list,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	816 free); can clean up after this type of list.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	817
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	818 <li><p><b>struct arg_list</b> - stores a pointer to a single string
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	819 (<b>char *arg</b>) which is stored in a separate chunk of memory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	820
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	821 <li><p><b>struct double_list</b> - has a second pointer (<b>struct double_list
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	822 prev</b> along with a <b>char data</b> for payload.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	823 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	824
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	825 <b>List Functions</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	826
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	827 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	828 <li><p>void <b>llist_pop</b>(void *list) - advances through a list ala
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	829 <b>node = llist_pop(&list);</b> This doesn't modify the list contents,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	830 but does advance the pointer you feed it (which is why you pass the _address_
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	831 of that pointer, not the pointer itself).</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	832
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	833 <li><p>void <b>llist_traverse</b>(void list, void (using)(void *data)) -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	834 iterate through a list calling a function on each node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	835
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	836 <li><p>struct double_list <b>dlist_add</b>(struct double_list llist, char data)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	837 - append an entry to a circular linked list.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	838 This function allocates a new struct double_list wrapper and returns the
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	839 pointer to the new entry (which you can usually ignore since it's llist->prev,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	840 but if llist was NULL you need it). The argument is the ->data field for the
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	841 new node.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	842 <ul><li><p>void <b>dlist_add_nomalloc</b>(struct double_list **llist,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	843 struct double_list *new) - append existing struct double_list to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	844 list, does not allocate anything.</p></li></ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	845 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	846
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	847 <b>List code trivia questions:</b>
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	848
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	849 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	850 <li><p><b>Why do arg_list and double_list contain a char * payload instead of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	851 a void ?</b> - Because you always have to typecast a void to use it, and
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	852 typecasting a char * does no harm. Since strings are the most common
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	853 payload, and doing math on the pointer ala
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	854 "(type )(ptr+sizeof(thing)+sizeof(otherthing))" requires ptr to be char
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	855 anyway (at least according to the C standard), defaulting to char * saves
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	856 a typecast.</p>
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	857 </li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	858
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	859 <li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	860 you to keep track of which one you're using, calling free(node->str) would
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	861 be bad, and _failing_ to free(node->arg) leaks memory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	862
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	863 <li><p><b>Why does llist_pop() take a void * instead of void **?</b> -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	864 because the stupid compiler complains about "type punned pointers" when
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	865 you typecast and dereference on the same line,
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	866 due to insane FSF developers hardwiring limitations of their optimizer
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	867 into gcc's warning system. Since C automatically typecasts any other
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	868 pointer type to and from void *, the current code works fine. It's sad that it
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	869 won't warn you if you forget the &, but the code crashes pretty quickly in
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	870 that case.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	871
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	872 <li><p><b>How do I assemble a singly-linked-list in order?</b> - use
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	873 a double_list, dlist_add() your entries, and then break the circle with
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	874 <b>list->prev->next = NULL;</b> when done.</li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	875 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	876
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	877 <a name="lib_args"><h3>lib/args.c</h3>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	878
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	879 <p>Toybox's main.c automatically parses command line options before calling the
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	880 command's main function. Option parsing starts in get_optflags(), which stores
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	881 results in the global structures "toys" (optflags and optargs) and "this".</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	882
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	883 <p>The option parsing infrastructure stores a bitfield in toys.optflags to
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	884 indicate which options the current command line contained. Arguments
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	885 attached to those options are saved into the command's global structure
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	886 ("this"). Any remaining command line arguments are collected together into
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	887 the null-terminated array toys.optargs, with the length in toys.optc. (Note
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	888 that toys.optargs does not contain the current command name at position zero,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	889 use "toys.which->name" for that.) The raw command line arguments get_optflags()
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	890 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	891
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	892 <p>Toybox's option parsing logic is controlled by an "optflags" string, using
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	893 a format reminiscent of getopt's optargs but has several important differences.
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	894 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	895 function out of the C library, get_optflags() is an independent implementation
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	896 which doesn't permute the original arguments (and thus doesn't change how the
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	897 command is displayed in ps and top), and has many features not present in
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	898 libc optargs() (such as the ability to describe long options in the same string
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	899 as normal options).</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	900
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	901 <p>Each command's NEWTOY() macro has an optflags string as its middle argument,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	902 which sets toy_list.options for that command to tell get_optflags() what
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	903 command line arguments to look for, and what to do with them.
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	904 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	905 definition string (I.E. the argument is NULL), option parsing is skipped
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	906 for that command, which must look at the raw data in toys.argv to parse its
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	907 own arguments. (If no currently enabled command uses option parsing,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	908 get_optflags() is optimized out of the resulting binary by the compiler's
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	909 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	910
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	911 <p>You don't have to free the option strings, which point into the environment
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	912 space (I.E. the string data is not copied). A TOYFLAG_NOFORK command
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	913 that uses the linked list type "*" should free the list objects but not
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	914 the data they point to, via "llist_free(TT.mylist, NULL);". (If it's not
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	915 NOFORK, exit() will free all the malloced data anyway unless you want
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	916 to implement a CONFIG_TOYBOX_FREE cleanup for it.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	917
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	918 <h4>Optflags format string</h4>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	919
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	920 <p>Note: the optflags option description string format is much more
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	921 concisely described by a large comment at the top of lib/args.c.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	922
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	923 <p>The general theory is that letters set optflags, and punctuation describes
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	924 other actions the option parsing logic should take.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	925
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	926 <p>For example, suppose the command line <b>command -b fruit -d walrus -a 42</b>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	927 is parsed using the optflags string "<b>a#b:c:d</b>". (I.E.
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	928 toys.which->options="a#b:c:d" and argv = ["command", "-b", "fruit", "-d",
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	929 "walrus", "-a", "42"]). When get_optflags() returns, the following data is
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	930 available to command_main():
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	931
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	932 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	933 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	934 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	935 <li>toys.optflags = 13; // -a = 8 \| -b = 4 \| -d = 1</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	936 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	937 <li>toys.optargs[1] = NULL; // end of list</li>
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	938 <li>toys.optc = 1; // there was 1 leftover argument</li>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	939 <li>toys.argv[] = {"-b", "fruit", "-d", "walrus", "-a", "42"}; // The original command line arguments
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	940 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	941 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	942
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	943 <li><p>In <b>union this</b> (treated as <b>long this[]</b>):
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	944 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	945 <li>this[0] = NULL; // -c didn't get an argument this time, so get_optflags() didn't change it and toys_init() zeroed "this" during setup.)</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	946 <li>this[1] = (long)"fruit"; // argument to -b</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	947 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	948 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	949 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	950 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	951
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	952 <p>If the command's globals are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	953
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	954 <blockquote><pre>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	955 GLOBALS(
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	956 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	957 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	958 long a;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	959 )
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	960 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	961 <p>That would mean TT.c == NULL, TT.b == "fruit", and TT.a == 42. (Remember,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	962 each entry that receives an argument must be a long or pointer, to line up
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	963 with the array position. Right to left in the optflags string corresponds to
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	964 top to bottom in GLOBALS().</p>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	965
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	966 <p>Put globals not filled out by the option parsing logic at the end of the
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	967 GLOBALS block. Common practice is to list the options one per line (to
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	968 make the ordering explicit, first to last in globals corresponds to right
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	969 to left in the option string), then leave a blank line before any non-option
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	970 globals.</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	971
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	972 <p><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	973
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	974 <p>Each option in the optflags string corresponds to a bit position in
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	975 toys.optflags, with the same value as a corresponding binary digit. The
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	976 rightmost argument is (1<<0), the next to last is (1<<1) and so on. If
432 01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	977 the option isn't encountered while parsing argv[], its bit remains 0.</p>
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	978
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	979 <p>For example,
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	980 the optflags string "abcd" would parse the command line argument "-c" to set
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	981 optflags to 2, "-a" would set optflags to 8, "-bd" would set optflags to
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	982 6 (I.E. 4\|2), and "-a -c" would set optflags to 10 (2\|8).</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	983
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	984 <p>Only letters are relevant to optflags, punctuation is skipped: in the
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	985 string "a*b:c#d", d=1, c=2, b=4, a=8. The punctuation after a letter
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	986 usually indicate that the option takes an argument.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	987
432 01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	988 <p>Since toys.optflags is an unsigned int, it only stores 32 bits. (Which is
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	989 the amount a long would have on 32-bit platforms anyway; 64 bit code on
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	990 32 bit platforms is too expensive to require in common code used by almost
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	991 all commands.) Bit positions beyond the 1<<31 aren't recorded, but
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	992 parsing higher options can still set global variables.</p>
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	993
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	994 <p><b>Automatically setting global variables from arguments (union this)</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	995
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	996 <p>The following punctuation characters may be appended to an optflags
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	997 argument letter, indicating the option takes an additional argument:</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	998
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	999 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1000 <li><b>:</b> - plus a string argument, keep most recent if more than one.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1001 <li><b>*</b> - plus a string argument, appended to a linked list.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1002 <li><b>@</b> - plus an occurrence counter (stored in a long)</li>
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1003 <li><b>#</b> - plus a signed long argument.
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1004 <li><b>-</b> - plus a signed long argument defaulting to negative (start argument with + to force a positive value).</li>
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1005 <li><b>.</b> - plus a floating point argument (if CFG_TOYBOX_FLOAT).</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1006 <ul>The following can be appended to a float or double:
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1007 <li><b><123</b> - error if argument is less than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1008 <li><b>>123</b> - error if argument is greater than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1009 <li><b>=123</b> - default value if argument not supplied</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1010 </ul>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1011 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1012
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1013 <p>A note about "." and CFG_TOYBOX_FLOAT: option parsing only understands <>=
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1014 after . when CFG_TOYBOX_FLOAT
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1015 is enabled. (Otherwise the code to determine where floating point constants
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1016 end drops out; it requires floating point). When disabled, it can reserve a
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1017 global data slot for the argument (so offsets won't change in your
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1018 GLOBALS[] block), but will never fill it out. You can handle
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1019 this by using the USE_BLAH() macros with C string concatenation, ala:
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1020 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1021
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1022 <p><b>GLOBALS</b></p>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1023
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1024 <p>Options which have an argument fill in the corresponding slot in the global
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1025 union "this" (see generated/globals.h), treating it as an array of longs
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1026 with the rightmost saved in this[0]. As described above, using "a*b:c#d",
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1027 "-c 42" would set this[0] = 42; and "-b 42" would set this[1] = "42"; each
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1028 slot is left NULL if the corresponding argument is not encountered.</p>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1029
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1030 <p>This behavior is useful because the LP64 standard ensures long and pointer
432 01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	1031 are the same size. C99 guarantees structure members will occur in memory
01473712c9fe Document that optflags is always an int (so 32 bit and 64 bit platforms behave the same). Rob Landley <rob@landley.net> parents: 415 diff changeset	1032 in the same order they're declared, and that padding won't be inserted between
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1033 consecutive variables of register size. Thus the first few entries can
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1034 be longs or pointers corresponding to the saved arguments.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1035
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1036 <p>See toys/other/hello.c for a longer example of parsing options into the
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1037 GLOBALS block.</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1038
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1039 <p><b>char *toys.optargs[]</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1040
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1041 <p>Command line arguments in argv[] which are not consumed by option parsing
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1042 (I.E. not recognized either as -flags or arguments to -flags) will be copied
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1043 to toys.optargs[], with the length of that array in toys.optc.
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1044 (When toys.optc is 0, no unrecognized command line arguments remain.)
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1045 The order of entries is preserved, and as with argv[] this new array is also
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1046 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1047
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1048 <p>Option parsing can require a minimum or maximum number of optargs left
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1049 over, by adding "<1" (read "at least one") or ">9" ("at most nine") to the
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1050 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1051
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1052 <p>The special argument "--" terminates option parsing, storing all remaining
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1053 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1054
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1055 <p><b>Other optflags control characters</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1056
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1057 <p>The following characters may occur at the start of each command's
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1058 optflags string, before any options that would set a bit in toys.optflags:</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1059
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1060 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1061 <li><b>^</b> - stop at first nonoption argument (for nice, xargs...)</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1062 <li><b>?</b> - allow unknown arguments (pass non-option arguments starting
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1063 with - through to optargs instead of erroring out).</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1064 <li><b>&</b> - the first argument has imaginary dash (ala tar/ps. If given twice, all arguments have imaginary dash.)</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1065 <li><b><</b> - must be followed by a decimal digit indicating at least this many leftover arguments are needed in optargs (default 0)</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1066 <li><b>></b> - must be followed by a decimal digit indicating at most this many leftover arguments allowed (default MAX_INT)</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1067 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1068
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1069 <p>The following characters may be appended to an option character, but do
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1070 not by themselves indicate an extra argument should be saved in this[].
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1071 (Technically any character not recognized as a control character sets an
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1072 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1073
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1074 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1075 <li><b>^</b> - stop parsing options after encountering this option, everything else goes into optargs.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1076 <li><b>\|</b> - this option is required. If more than one marked, only one is required.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1077 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1078
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1079 <p>The following may be appended to a float or double:</p>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1080
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1081 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1082 <li><b><123</b> - error if argument is less than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1083 <li><b>>123</b> - error if argument is greater than this</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1084 <li><b>=123</b> - default value if argument not supplied</li>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1085 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1086
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1087 <p>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1088 is enabled. (Otherwise the code to determine where floating point constants
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1089 end drops out. When disabled, it can reserve a global data slot for the
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1090 argument so offsets won't change, but will never fill it out.). You can handle
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1091 this by using the USE_BLAH() macros with C string concatenation, ala:</p>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1092
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1093 <blockquote>"abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</blockquote>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	1094
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1095 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1096
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1097 <p>The optflags string can contain long options, which are enclosed in
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1098 parentheses. They may be appended to an existing option character, in
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1099 which case the --longopt is a synonym for that option, ala "a:(--fred)"
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1100 which understands "-a blah" or "--fred blah" as synonyms.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1101
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1102 <p>Longopts may also appear before any other options in the optflags string,
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1103 in which case they have no corresponding short argument, but instead set
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1104 their own bit based on position. So for "(walrus)#(blah)xy:z" "command
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1105 --walrus 42" would set toys.optflags = 16 (-z = 1, -y = 2, -x = 4, --blah = 8)
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1106 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1107
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1108 <p>A short option may have multiple longopt synonyms, "a(one)(two)", but
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1109 each "bare longopt" (ala "(one)(two)abc" before any option characters)
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1110 always sets its own bit (although you can group them with +X).</p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	1111
1073 3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1112 <p><b>[groups]</b></p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1113
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1114 <p>At the end of the option string, square bracket groups can define
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1115 relationships between existing options. (This only applies to short
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1116 options, bare --longopts can't participate.)</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1117
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1118 <p>The first character of the group defines the type, the remaining
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1119 characters are options it applies to:</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1120
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1121 <ul>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1122 <li><b>-</b> - Exclusive, switch off all others in this group.</li>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1123 <li><b>+</b> - Inclusive, switch on all others in this group.</li>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1124 <li><b>!</b> - Error, fail if more than one defined.</li>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1125 </ul>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1126
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1127 <p>So "abc[-abc]" means -ab = -b, -ba = -a, -abc = -c. "abc[+abc]"
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1128 means -ab=-abc, -c=-abc, and "abc[!abc] means -ab calls error_exit("no -b
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1129 with -a"). Note that [-] groups clear the GLOBALS option slot of
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1130 options they're switching back off, but [+] won't set options it didn't see
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1131 (just the optflags).</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1132
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1133 <p><b>whitespace</b></p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1134
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1135 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1136 The command line argument "-abc" may be interepreted many different ways:
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1137 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1138 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1139 "c" as the argument to -b.</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1140
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1141 <p>Note that & changes whitespace handling, so that the command line
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1142 "tar cvfCj outfile.tar.bz2 topdir filename" is parsed the same as
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1143 "tar filename -c -v -j -f outfile.tar.bz2 -C topdir". Note that "tar -cvfCj
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1144 one two three" would equal "tar -c -v -f Cj one two three". (This matches
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1145 historical usage.)</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1146
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1147 <p>Appending a space to the option in the option string ("a: b") makes it
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1148 require a space, I.E. "-ab" is interpreted as "-a" "-b". That way "kill -stop"
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1149 differs from "kill -s top".</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1150
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1151 <p>Appending ; to a longopt in the option string makes its argument optional,
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1152 and only settable with =, so in ls "(color):;" can accept "ls --color" and
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1153 "ls --color=auto" without complaining that the first has no argument.</p>
3c0e653070d8 Update lib/args.c docs. Rob Landley <rob@landley.net> parents: 1015 diff changeset	1154
625 1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1155 <a name="lib_dirtree"><h3>lib/dirtree.c</h3>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1156
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1157 <p>The directory tree traversal code should be sufficiently generic
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1158 that commands never need to use readdir(), scandir(), or the fts.h family
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1159 of functions.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1160
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1161 <p>These functions do not call chdir() or rely on PATH_MAX. Instead they
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1162 use openat() and friends, using one filehandle per directory level to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1163 recurseinto subdirectories. (I.E. they can descend 1000 directories deep
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1164 if setrlimit(RLIMIT_NOFILE) allows enough open filehandles, and the default
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1165 in /proc/self/limits is generally 1024.)</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1166
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1167 <p>The basic dirtree functions are:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1168
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1169 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1170 <li><p><b>dirtree_read(char path, int (callback)(struct dirtree node))</b> -
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1171 recursively read directories, either applying callback() or returning
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1172 a tree of struct dirtree if callback is NULL.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1173
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1174 <li><p><b>dirtree_path(struct dirtree node, int plen)</b> - malloc() a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1175 string containing the path from the root of this tree to this node. If
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1176 plen isn't NULL then *plen is how many extra bytes to malloc at the end
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1177 of string.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1178
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1179 <li><p><b>dirtree_parentfd(struct dirtree *node)</b> - return fd of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1180 containing directory, for use with openat() and such.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1181 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1182
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1183 <p>The <b>dirtree_read()</b> function takes two arguments, a starting path for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1184 the root of the tree, and a callback function. The callback takes a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1185 <b>struct dirtree *</b> (from lib/lib.h) as its argument. If the callback is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1186 NULL, the traversal uses a default callback (dirtree_notdotdot()) which
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1187 recursively assembles a tree of struct dirtree nodes for all files under
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1188 this directory and subdirectories (filtering out "." and ".." entries),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1189 after which dirtree_read() returns the pointer to the root node of this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1190 snapshot tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1191
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1192 <p>Otherwise the callback() is called on each entry in the directory,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1193 with struct dirtree * as its argument. This includes the initial
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1194 node created by dirtree_read() at the top of the tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1195
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1196 <p><b>struct dirtree</b></p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1197
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1198 <p>Each struct dirtree node contains <b>char name[]</b> and <b>struct stat
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1199 st</b> entries describing a file, plus a <b>char *symlink</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1200 which is NULL for non-symlinks.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1201
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1202 <p>During a callback function, the <b>int data</b> field of directory nodes
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1203 contains a dirfd (for use with the openat() family of functions). This is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1204 generally used by calling dirtree_parentfd() on the callback's node argument.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1205 For symlinks, data contains the length of the symlink string. On the second
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1206 callback from DIRTREE_COMEAGAIN (depth-first traversal) data = -1 for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1207 all nodes (that's how you can tell it's the second callback).</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1208
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1209 <p>Users of this code may put anything they like into the <b>long extra</b>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1210 field. For example, "cp" and "mv" use this to store a dirfd for the destination
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1211 directory (and use DIRTREE_COMEAGAIN to get the second callback so they can
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1212 close(node->extra) to avoid running out of filehandles).
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1213 This field is not directly used by the dirtree code, and
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1214 thanks to LP64 it's large enough to store a typecast pointer to an
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1215 arbitrary struct.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1216
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1217 <p>The return value of the callback combines flags (with boolean or) to tell
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1218 the traversal infrastructure how to behave:</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1219
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1220 <ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1221 <li><p><b>DIRTREE_SAVE</b> - Save this node, assembling a tree. (Without
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1222 this the struct dirtree is freed after the callback returns. Filtering out
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1223 siblings is fine, but discarding a parent while keeping its child leaks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1224 memory.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1225 <li><p><b>DIRTREE_ABORT</b> - Do not examine any more entries in this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1226 directory. (Does not propagate up tree: to abort entire traversal,
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1227 return DIRTREE_ABORT from parent callbacks too.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1228 <li><p><b>DIRTREE_RECURSE</b> - Examine directory contents. Ignored for
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1229 non-directory entries. The remaining flags only take effect when
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1230 recursing into the children of a directory.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1231 <li><p><b>DIRTREE_COMEAGAIN</b> - Call the callback a second time after
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1232 examining all directory contents, allowing depth-first traversal.
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1233 On the second call, dirtree->data = -1.</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1234 <li><p><b>DIRTREE_SYMFOLLOW</b> - follow symlinks when populating children's
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1235 <b>struct stat st</b> (by feeding a nonzero value to the symfollow argument of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1236 dirtree_add_node()), which means DIRTREE_RECURSE treats symlinks to
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1237 directories as directories. (Avoiding infinite recursion is the callback's
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1238 problem: the non-NULL dirtree->symlink can still distinguish between
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1239 them.)</p></li>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1240 </ul>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1241
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1242 <p>Each struct dirtree contains three pointers (next, parent, and child)
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1243 to other struct dirtree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1244
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1245 <p>The <b>parent</b> pointer indicates the directory
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1246 containing this entry; even when not assembling a persistent tree of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1247 nodes the parent entries remain live up to the root of the tree while
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1248 child nodes are active. At the top of the tree the parent pointer is
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1249 NULL, meaning the node's name[] is either an absolute path or relative
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1250 to cwd. The function dirtree_parentfd() gets the directory file descriptor
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1251 for use with openat() and friends, returning AT_FDCWD at the top of tree.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1252
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1253 <p>The <b>child</b> pointer points to the first node of the list of contents of
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1254 this directory. If the directory contains no files, or the entry isn't
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1255 a directory, child is NULL.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1256
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1257 <p>The <b>next</b> pointer indicates sibling nodes in the same directory as this
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1258 node, and since it's the first entry in the struct the llist.c traversal
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1259 mechanisms work to iterate over sibling nodes. Each dirtree node is a
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1260 single malloc() (even char *symlink points to memory at the end of the node),
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1261 so llist_free() works but its callback must descend into child nodes (freeing
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1262 a tree, not just a linked list), plus whatever the user stored in extra.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1263
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1264 <p>The <b>dirtree_read</b>() function is a simple wrapper, calling <b>dirtree_add_node</b>()
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1265 to create a root node relative to the current directory, then calling
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1266 <b>handle_callback</b>() on that node (which recurses as instructed by the callback
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1267 return flags). Some commands (such as chgrp) bypass this wrapper, for example
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1268 to control whether or not to follow symlinks to the root node; symlinks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1269 listed on the command line are often treated differently than symlinks
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1270 encountered during recursive directory traversal).
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1271
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1272 <p>The ls command not only bypasses the wrapper, but never returns
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1273 <b>DIRTREE_RECURSE</b> from the callback, instead calling <b>dirtree_recurse</b>() manually
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1274 from elsewhere in the program. This gives ls -lR manual control
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1275 of traversal order, which is neither depth first nor breadth first but
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1276 instead a sort of FIFO order requried by the ls standard.</p>
1a368546afd9 Add documentation for lib/llist.c and lib/dirtree.c. Rob Landley <rob@landley.net> parents: 536 diff changeset	1277
1247 d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	1278 <a name="toys">
d630b3be752f Document some of the new temporary files in generated/, add anchor tags. Rob Landley <rob@landley.net> parents: 1180 diff changeset	1279 <h1><a href="#toys">Directory toys/</a></h1>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1280
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1281 <p>This directory contains command implementations. Each command is a single
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1282 self-contained file. Adding a new command involves adding a single
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1283 file, and removing a command involves removing that file. Commands use
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1284 shared infrastructure from the lib/ and generated/ directories.</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1285
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1286 <p>Currently there are five subdirectories under "toys/" containing "posix"
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1287 commands described in POSIX-2008, "lsb" commands described in the Linux
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1288 Standard Base 4.1, "other" commands not described by either standard,
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1289 "pending" commands awaiting cleanup (which default to "n" in menuconfig
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1290 because they don't necessarily work right yet), and "example" code showing
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1291 how toybox infrastructure works and providing template/skeleton files to
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1292 start new commands.</p>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1293
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1294 <p>The only difference directory location makes is which menu the command
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1295 shows up in during "make menuconfig", the directories are otherwise identical.
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1296 Note that the commands exist within a single namespace at runtime, so you can't
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1297 have the same command in multiple subdirectories. (The build tries to fail
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1298 informatively when you do that.)</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1299
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1300 <p>There is one more sub-menus in "make menuconfig" containing global
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1301 configuration options for toybox. This menu is defined in the top level
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1302 Config.in.</p>
674 7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1303
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1304 <p>See <a href="#adding">adding a new command</a> for details on the
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1305 layout of a command file.</p>
7e846e281e38 New build infrastructure to generate FLAG_ macros and TT alias, #define FOR_commandname before #including toys.h to trigger it. Rename DEFINE_GLOBALS() to just GLOBALS() (because I could never remember if it was DECLARE_GLOBALS). Convert existing commands to use new infrastructure, and replace optflag constants with FLAG_ macros where appropriate. Rob Landley <rob@landley.net> parents: 625 diff changeset	1306
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	1307 <h2>Directory scripts/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1308
677 43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1309 <p>Build infrastructure. The makefile calls scripts/make.sh for "make"
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1310 and scripts/install.sh for "make install".</p>
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1311
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1312 <p>There's also a test suite, "make test" calls make/test.sh, which runs all
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1313 the tests in make/test/*. You can run individual tests via
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1314 "scripts/test.sh command", or "TEST_HOST=1 scripts/test.sh command" to run
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1315 that test against the host implementation instead of the toybox one.</p>
43c4f709b9ff Doc tweak about test suite. Rob Landley <rob@landley.net> parents: 674 diff changeset	1316
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1317 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1318
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1319 <p>Run .config through this filter to get a list of enabled commands, which
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1320 is turned into a list of files in toys via a sed invocation in the top level
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1321 Makefile.
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1322 </p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1323
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	1324 <h2>Directory kconfig/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1325
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1326 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1327 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1328
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1329 <!-- todo
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1330
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1331 Better OLDTOY and multiple command explanation. From Config.in:
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	1332
1490 44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1333 <p>A command with multiple names (or multiple similar commands implemented in
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1334 the same .c file) should have config symbols prefixed with the name of their
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1335 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1336 have config symbols they must be options (symbols with an underscore and
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1337 suffix) to the NEWTOY() name. (See generated/toylist.h)</p>
44cf038d297d Fluff out the documentation some more. Rob Landley <rob@landley.net> parents: 1303 diff changeset	1338 -->
1291 00938a3d0955 Fluff out the coding style section, but the result was a bit big for the start of code.html, so move it to design.html. Rob Landley <rob@landley.net> parents: 1247 diff changeset	1339
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1340 <!--#include file="footer.html" -->

Mercurial > hg > toybox

annotate www/code.html @ 1501:c51a4dbe5db7 draft