toybox: www/code.html annotate

annotate www/code.html @ 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.

author	Rob Landley <rob@landley.net>
date	Sun, 26 Feb 2012 21:53:15 -0600
parents	01473712c9fe
children	c08cd17224c0

rev	line source
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	1 <!--#include file="header.html" -->
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	2
217 ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	3 <p><h1>Code style</h1></p>
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	4
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	5 <p>Toybox source is formatted to be read with 4-space tab stops. Each file
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	6 starts with a special comment telling vi to set the tab stop to 4. Note that
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	7 one of the bugs in Ubuntu 7.10 broke vi's ability to parse these comments; you
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	8 must either rebuild vim from source, or go ":ts=4" yourself each time you load
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	9 the file.</p>
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	10
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	11 <p>Gotos are allowed for error handling, and for breaking out of
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	12 nested loops. In general, a goto should only jump forward (not back), and
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	13 should either jump to the end of an outer loop, or to error handling code
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	14 at the end of the function. Goto labels are never indented: they override the
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	15 block structure of the file. Putting them at the left edge makes them easy
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	16 to spot as overrides to the normal flow of control, which they are.</p>
ca48a878255d Brief note about code style. Rob Landley <rob@landley.net> parents: 213 diff changeset	17
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	18 <p>The primary goal of toybox is _simple_ code. Small is second,
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	19 speed and lots of features come in somewhere after that. Note that
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	20 environmental dependencies are a type of complexity, so needing other packages
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	21 to build or run is a big downside. For example, don't use curses when you can
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	22 output ansi escape sequences instead.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	23
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	24 <p><h1>Infrastructure:</h1></p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	25
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	26 <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	27 <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	28 <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	29 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	30 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	31 <li>The <a href="#lib">lib directory</a> contains common functions shared by
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	32 multiple commands.</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	33 <li>The <a href="#toys">toys directory</a> contains the C files implementating
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	34 each command.</li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	35 <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	36 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	37 <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	38 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	39 <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	40 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	41 </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	42
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	43 <a name="adding" />
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	44 <p><h1>Adding a new command</h1></p>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	45 <p>To add a new command to toybox, add a C file implementing that command to
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	46 the toys directory. No other files need to be modified; the build extracts
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	47 all the information it needs (such as command line arguments) from specially
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	48 formatted comments and macros in the C file. (See the description 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	49 <a href="#generated">generated directory</a> for details.)</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	50
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	51 <p>An easy way to start a new command is copy the file "hello.c" to
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	52 the name of the new command, and modify this copy to implement the new command.
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	53 This file is an example command meant to be used as a "skeleton" for
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	54 new commands (more or less by turning every instance of "hello" into the
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	55 name of your command, updating the command line arguments, globals, and
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	56 help data, and then filling out its "main" function with code that does
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	57 something interesting). It provides examples of all the build infrastructure
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	58 (including optional elements like command line argument parsing and global
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	59 variables that a "hello world" program doesn't strictly need).</p>
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	60
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	61 <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	62
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	63 <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	64 <li><p>First "cd toys" and "cp hello.c yourcommand.c". Note that the name
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	65 of this file is significant, it's the name of the new command you're adding
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	66 to toybox. Open your new file in your favorite editor.</p></li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	67
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	68 <li><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	69 "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	70
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	71 <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	72 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	73
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	74 <li><p>Give a URL to the relevant standards document, or say "Not in SUSv4" if
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	75 there is no relevant standard. (Currently both lines are there, delete
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	76 whichever is inappropriate.) The existing link goes to the directory of SUSv4
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	77 command line utility standards on the Open Group's website, where there's often
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	78 a relevant commandname.html file. Feel free to link to other documentation or
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	79 standards as appropriate.</p></li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	80
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	81 <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	82 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	83 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	84
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	85 <ol>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	86 <li><p>the name used to run your command</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	87 <li><p>the command line argument <a href="#lib_args">option parsing string</a> (NULL if none)</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	88 <li><p>a bitfield of TOYFLAG values
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	89 (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	90 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	91 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	92 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	93 </ol>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	94 </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	95
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	96 <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	97 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	98 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	99 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	100 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	101 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	102 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	103 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	104 "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	105
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	106 <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	107 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	108 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	109 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	110 options when producing generated/help.h.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	111 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	112
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	113 <li><p>Update the DEFINE_GLOBALS() macro to contain your command's global
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	114 variables, and also change the name "hello" in the #define TT line afterwards
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	115 to the name of your command. If your command has no global variables, delete
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	116 this macro (and the #define TT line afterwards). Note that if you specified
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	117 two-character command line arguments in NEWTOY(), the first few global
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	118 variables will be initialized by the automatic argument parsing logic, and
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	119 the type and order of these variables must correspond to the arguments
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	120 specified in NEWTOY(). See [TODO] for details.</p></li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	121
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	122 <li><p>If you didn't delete the DEFINE_GLOBALS macro, change the "#define TT
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	123 this.hello" line to use your command name in place of the "hello". This is a
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	124 shortcut to access your global variables as if they were members of the global
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	125 struct "TT". (Access these members with a period ".", not a right arrow
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	126 "->".)</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	127
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	128 <li><p>Rename hello_main() to yourcommand_main(). This is the main() function
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	129 where execution of your command starts. See [TODO] to figure out what
239 4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	130 happened to your command line arguments and how to access them.</p></li>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	131 </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	132
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	133 <p><a name="top" /><h2>Top level directory.</h2></p>
4f1ca01db000 Fluff out hello.c to supply more example code as a skeleton for new commands, Rob Landley <rob@landley.net> parents: 217 diff changeset	134
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	135 <p>This directory contains global infrastructure.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	136
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	137 <h3>toys.h</h3>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	138 <p>Each command #includes "toys.h" as part of its standard prolog.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	139
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	140 <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	141 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	142 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	143 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	144 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	145 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	146 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	147
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	148 <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	149 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	150 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	151
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	152 <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	153 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	154 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	155 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	156 local variables.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	157
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	158 <h3>main.c</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	159 <p>Contains the main() function where execution starts, plus
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	160 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	161 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	162 only command defined outside of the toys directory.)</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	163
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	164 <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	165 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	166 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	167 toy_list[] (via toys.which->toy_main()).
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	168 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	169 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	170 directory.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	171
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	172 <p>The following global variables are defined in main.c:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	173 <ul>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	174 <a name="toy_list" />
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	175 <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	176 commands currently configured into toybox. The first entry (toy_list[0]) is
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	177 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	178 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	179 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	180 The remaining entries are the commands in alphabetical order (for efficient
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	181 binary search).</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	182
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	183 <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	184 defining macros and #including generated/newtoys.h.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	185
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	186 <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	187 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	188 <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	189 <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	190 command.</p></li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	191 <li><p>char *<b>options</b> - command line option string (used by
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	192 get_optflags() in lib/args.c to intialize toys.optflags, toys.optargs, and
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	193 entries in the toy's DEFINE_GLOBALS struct). When this is NULL, no option
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	194 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	195 <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	196
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	197 <ul>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	198 <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	199 <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	200 <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	201 <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	202 <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	203 <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	204 <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	205 </ul>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	206 <br>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	207
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	208 <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	209 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	210 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	211 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	212
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	213 <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	214 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	215 Members of this structure include:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	216 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	217 <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	218 structure. Mostly used to grab the name of the running command
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	219 (toys->which.name).</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	220 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	221 <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	222 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	223 return this value.</p></li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	224 <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	225 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	226 "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	227 entry indicates the end of the array.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	228 <p>Most commands don't use this field, instead the use optargs, optflags,
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	229 and the fields in the DEFINE_GLOBALS struct initialized by get_optflags().</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	230 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	231 <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	232 <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	233 toys->which.options occurred this time.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	234
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	235 <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	236 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	237 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	238 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	239 "-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	240
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	241 <p>Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2,
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	242 b=4, a=8. The punctuation after a letter initializes global variables
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	243 (see [TODO] DECLARE_GLOBALS() for details).</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	244
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	245 <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	246
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	247 </li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	248 <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	249 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	250 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	251 name.</p></li>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	252 <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	253 optargs[].<p></li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	254 <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	255 via help_main() before exiting. (True during option parsing, defaults to
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	256 false afterwards.)</p></li>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	257 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	258
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	259 <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	260 command's global variables.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	261
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	262 <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	263 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	264 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	265 can also initialize global variables with its results.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	266
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	267 <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	268 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	269 running would be wasteful.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	270
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	271 <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	272 a structure, and declaring a union of those structures with a single global
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	273 instance (called "this"). The DEFINE_GLOBALS() macro contains the global
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	274 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	275 variable can then be accessed as "this.commandname.varname".
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	276 Generally, the macro TT is #defined to this.commandname so the variable
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	277 can then be accessed as "TT.variable". See toys/hello.c for an example.</p>
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	278
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	279 <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	280 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	281 declare global variables outside of this, because such global variables would
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	282 allocate memory when running other commands that don't use those global
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	283 variables.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	284
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	285 <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	286 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	287 the get_optargs() description in lib/args.c for details.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	288 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	289
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	290 <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	291 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	292 and it should never be directly referenced by functions in lib/ (although
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	293 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	294 </ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	295
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	296 <p>The following functions are defined in main.c:</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	297 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	298 <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	299 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	300 <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	301 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	302 <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	303 arguments.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	304 <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	305 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	306 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	307
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	308 <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	309 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	310 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	311 never match an internal command.</li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	312
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	313 <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	314 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	315 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	316 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	317 install path prepended.</p></li>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	318
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	319 </ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	320
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	321 <h3>Config.in</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	322
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	323 <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	324 <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	325
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	326 <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	327 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	328 scripts/config2help.py to create generated/help.h.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	329
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	330 <h3>Temporary files:</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	331
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	332 <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	333 <ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	334 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	335 which commands (and options to commands) are currently enabled. Used
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	336 to make generated/config.h and determine which toys/*.c files to build.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	337
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	338 <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	339 <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	340 instructions</a>.</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	341 </li>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	342 </ul>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	343
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	344 <p>The "generated/" directory contains files generated from other source code
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	345 in toybox. All of these files can be recreated by the build system, although
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	346 some (such as generated/help.h) are shipped in release versions to reduce
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	347 environmental dependencies (I.E. so you don't need python on your build
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	348 system).</p>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	349
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	350 <ul>
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	351 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	352 generated from .config by a sed invocation in the top level Makefile.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	353
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	354 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	355 disabled symbols. This allows the use of normal if() statements to remove
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	356 code at compile time via the optimizer's dead code elimination (which removes
20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	357 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	358 cluttering the code with #ifdefs or leading to configuration dependent build
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	359 breaks. (See the 1992 Usenix paper
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	360 <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	361 Considered Harmful</a> for more information.)</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	362
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	363 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	364 is enabled, and nothing when the symbol is disabled. This can be used
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	365 for things like varargs or variable declarations which can't always be
256 20f1e3da0492 Partial update. Needs more work. Rob Landley <rob@landley.net> parents: 239 diff changeset	366 eliminated by a simple test on CFG_SYMBOL. Note that
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	367 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	368 still result in configuration dependent build breaks. Use with caution.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	369 </li>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	370 </ul>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	371
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	372 <p><h2>Directory toys/</h2></p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	373
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	374 <h3>toys/Config.in</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	375
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	376 <p>Included from the top level Config.in, contains one or more
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	377 configuration entries for each command.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	378
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	379 <p>Each command has a configuration entry matching the command name (although
a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	380 configuration symbols are uppercase and command names are lower case).
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	381 Options to commands start with the command name followed by an underscore and
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	382 the option name. Global options are attached to the "toybox" command,
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	383 and thus use the prefix "TOYBOX_". This organization is used by
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	384 scripts/cfg2files to select which toys/*.c files to compile for a given
a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	385 .config.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	386
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	387 <p>A command with multiple names (or multiple similar commands implemented in
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	388 the same .c file) should have config symbols prefixed with the name of their
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	389 C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	390 have config symbols they're options (symbols with an underscore and suffix)
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	391 to the NEWTOY() name. (See toys/toylist.h)</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	392
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	393 <h3>toys/toylist.h</h3>
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	394 <p>The first half of this file prototypes all the structures to hold
213 db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	395 global variables for each command, and puts them in toy_union. These
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	396 prototypes are only included if the macro NEWTOY isn't defined (in which
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	397 case NEWTOY is defined to a default value that produces function
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	398 prototypes).</p>
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	399
213 db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	400 <p>The second half of this file lists all the commands in alphabetical
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	401 order, along with their command line arguments and install location.
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	402 Each command has an appropriate configuration guard so only the commands that
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	403 are enabled wind up in the list.</p>
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	404
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	405 <p>The first time this header is #included, it defines structures and
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	406 produces function prototypes for the commands in the toys directory.</p>
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	407
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	408
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	409 <p>The first time it's included, it defines structures and produces function
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	410 prototypes.
db91356e3c43 More random unfinished code documentation. Rob Landley <rob@landley.net> parents: 210 diff changeset	411 This
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	412 is used to initialize toy_list in main.c, and later in that file to initialize
a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	413 NEED_OPTIONS (to figure out whether the command like parsing logic is needed),
a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	414 and to put the help entries in the right order in toys/help.c.</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	415
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	416 <h3>toys/help.h</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	417
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	418 <p>#defines two help text strings for each command: a single line
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	419 command_help and an additinal command_help_long. This is used by help_main()
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	420 in toys/help.c to display help for commands.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	421
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	422 <p>Although this file is generated from Config.in help entries by
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	423 scripts/config2help.py, it's shipped in release tarballs so you don't need
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	424 python on the build system. (If you check code out of source control, or
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	425 modify Config.in, then you'll need python installed to rebuild it.)</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	426
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	427 <p>This file contains help for all commands, regardless of current
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	428 configuration, but only the currently enabled ones are entered into help_data[]
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	429 in toys/help.c.</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	430
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	431 <h2>Directory lib/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	432
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	433 <p>lib: llist, getmountlist(), error_msg/error_exit, xmalloc(),
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	434 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	435 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	436
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	437 <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	438
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	439 <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	440 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	441 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	442
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	443 <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	444 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	445 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	446 ("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	447 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	448 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	449 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	450 parsed are retained unmodified in toys.argv[].</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	451
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	452 <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	453 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	454 Toybox does not use the getopt()
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	455 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	456 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	457 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	458 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	459 as normal options).</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	460
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	461 <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	462 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	463 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	464 If a command has no option
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	465 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	466 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	467 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	468 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	469 --gc-sections option.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	470
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	471 <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	472 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	473 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	474 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	475 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	476 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	477
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	478 <h4>Optflags format string</h4>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	479
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	480 <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	481 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	482
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	483 <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	484 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	485
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	486 <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	487 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	488 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	489 "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	490 available to command_main():
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	491
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	492 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	493 <li><p>In <b>struct toys</b>:
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	494 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	495 <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	496 <li>toys.optargs[0] = "walrus"; // leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	497 <li>toys.optargs[1] = NULL; // end of list</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	498 <li>toys.optc=1; // there was 1 leftover argument</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	499 <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	500 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	501 <p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	502
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	503 <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	504 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	505 <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	506 <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	507 <li>this[2] = 42; // argument to -a</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	508 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	509 </p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	510 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	511
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	512 <p>If the command's globals are:</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	513
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	514 <blockquote><pre>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	515 DECLARE_GLOBALS(
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	516 char *c;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	517 char *b;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	518 long a;
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	519 )
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	520 #define TT this.command
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	521 </pre></blockquote>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	522 <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	523 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	524 with the array position. Right to left in the optflags string corresponds to
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	525 top to bottom in DECLARE_GLOBALS().</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	526
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	527 <p><b>long toys.optflags</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	528
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	529 <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	530 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	531 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	532 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	533
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	534 <p>For example,
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	535 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	536 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	537 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	538
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	539 <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	540 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	541 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	542
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	543 <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	544 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	545 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	546 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	547 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	548
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	549 <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	550
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	551 <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	552 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	553
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	554 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	555 <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	556 <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	557 <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	558 <li><b>#</b> - plus a signed long argument.
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	559 <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	560 <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	561 <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	562 <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	563 <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	564 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	565 <ul><li>Option parsing only understands <>= after . when CFG_TOYBOX_FLOAT
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	566 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	567 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	568 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	569 this by using the USE_BLAH() macros with C string concatenation, ala:
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	570 "abc." USE_TOYBOX_FLOAT("<1.23>4.56=7.89") "def"</li></ul>
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	571 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	572
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	573 <p>Arguments may occur with or without a space (I.E. "-a 42" or "-a42").
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	574 The command line argument "-abc" may be interepreted many different ways:
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	575 the optflags string "cba" sets toys.optflags = 7, "c:ba" sets toys.optflags=4
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	576 and saves "ba" as the argument to -c, and "cb:a" sets optflags to 6 and saves
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	577 "c" as the argument to -b.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	578
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	579 <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	580 union "this" (see generated/globals.h), treating it as an array of longs
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	581 with the rightmost saved in this[0]. Again using "a*b:c#d", "-c 42" would set
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	582 this[0]=42; and "-b 42" would set this[1]="42"; each slot is left NULL if
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	583 the corresponding argument is not encountered.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	584
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	585 <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	586 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	587 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	588 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	589 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	590
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	591 <p><b>char *toys.optargs[]</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	592
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	593 <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	594 (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	595 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	596 (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	597 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	598 terminated by a NULL entry.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	599
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	600 <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	601 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	602 start of the optflags string.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	603
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	604 <p>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	605 arguments in optargs. The "--" itself is consumed.</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	606
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	607 <p><b>Other optflags control characters</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	608
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	609 <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	610 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	611
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	612 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	613 <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	614 <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	615 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	616 <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	617 <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	618 <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	619 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	620
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	621 <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	622 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	623 (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	624 optflag, but letters are never control characters.)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	625
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	626 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	627 <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	628 <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	629 <li><b>+X</b> enabling this option also enables option X (switch bit on).</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	630 <li><b>~X</b> enabling this option disables option X (switch bit off).</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	631 <li><b>!X</b> this option cannot be used in combination with X (die with error).</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	632 <li><b>[yz]</b> this option requires at least one of y or z to also be enabled.</li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	633 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	634
415 2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	635 <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	636
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	637 <ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	638 <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	639 <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	640 <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	641 </ul>
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	642
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	643 <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	644 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	645 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	646 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	647 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	648
2cbbd4c5eaaa Add <>= to lib/args.c, with documentation. Rob Landley <rob@landley.net> parents: 403 diff changeset	649 <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	650
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	651 <p><b>--longopts</b></p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	652
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	653 <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	654 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	655 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	656 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	657
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	658 <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	659 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	660 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	661 --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	662 and would assign this[1] = 42;</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	663
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	664 <p>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	665 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	666 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	667
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	668 <h2>Directory scripts/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	669
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	670 <h3>scripts/cfg2files.sh</h3>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	671
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	672 <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	673 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	674 Makefile.
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	675 </p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	676
210 a71c502a028c Fluff out code.html a bit more. Rob Landley <rob@landley.net> parents: 200 diff changeset	677 <h2>Directory kconfig/</h2>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	678
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	679 <p>Menuconfig infrastructure copied from the Linux kernel. See the
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	680 Linux kernel's Documentation/kbuild/kconfig-language.txt</p>
f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	681
403 f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	682 <a name="generated">
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	683 <h2>Directory generated/</h2>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	684
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	685 <p>All the files in this directory except the README are generated by the
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	686 build. (See scripts/make.sh)</p>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	687
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	688 <ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	689 <li><p><b>config.h</b> - CFG_COMMAND and USE_COMMAND() macros set by menuconfig via .config.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	690
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	691 <li><p><b>Config.in</b> - Kconfig entries for each command. Included by top level Config.in. The help text in here is used to generated help.h</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	692
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	693 <li><p><b>help.h</b> - Help text strings for use by "help" command. Building
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	694 this file requires python on the host system, so the prebuilt file is shipped
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	695 in the build tarball to avoid requiring python to build toybox.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	696
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	697 <li><p><b>newtoys.h</b> - List of NEWTOY() or OLDTOY() macros for all available
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	698 commands. Associates command_main() functions with command names, provides
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	699 option string for command line parsing (<a href="#lib_args">see lib/args.c</a>),
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	700 specifies where to install each command and whether toysh should fork before
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	701 calling it.</p></li>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	702 </ul>
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	703
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	704 <p>Everything in this directory is a derivative file produced from something
f6ffc6685a9e Fluff out documentation and skeleton code. Rob Landley <rob@landley.net> parents: 256 diff changeset	705 else. The entire directory is deleted by "make distclean".</p>
200 f868f933bd3b Update web pages. Rob Landley <rob@landley.net> parents: diff changeset	706 <!--#include file="footer.html" -->

Mercurial > hg > toybox

annotate www/code.html @ 501:8abb9e307d0c