Merge remote-tracking branch \'toybox/master\' into HEAD

[android-x86/external-toybox.git] / www / code.html

diff --git a/www/code.html b/www/code.html
index 7e15e18..c0566b4 100644 (file)
--- a/www/code.html
+++ b/www/code.html
@@ -55,6 +55,13 @@ to the environment will take precedence.</p>
 I.E. "what to build", and "configure" describes the build and installation
 environment, I.E. "how to build it".)</p>
 
+<p>By default "make install" puts files in /usr/toybox. Adding this to the
+$PATH is up to you. The environment variable $PREFIX can change the
+install location, ala "PREFIX=/usr/local/bin make install".</p>
+
+<p>If you need an unstripped (debug) version of any of these binaries,
+look in generated/unstripped.</p>
+
 <p><h1><a name="running"><a href="#running">Running a command</a></h1></p>
 
 <h2>main</h2>
@@ -444,10 +451,15 @@ as specified by the options field off this command's toy_list entry.  See
 the get_optargs() description in lib/args.c for details.</p>
 </li>
 
-<li><b>char toybuf[4096]</b> - a common scratch space buffer so
-commands don't need to allocate their own.  Any command is free to use this,
-and it should never be directly referenced by functions in lib/ (although
-commands are free to pass toybuf in to a library function as an argument).</li>
+<li><b>char toybuf[4096]</b> - a common scratch space buffer guaranteed
+to start zeroed, so commands don't need to allocate/initialize their own.
+Any command is free to use this, and it should never be directly referenced
+by functions in lib/ (although commands are free to pass toybuf in to a
+library function as an argument).</li>
+
+<li><b>char libbuf[4096]</b> - like toybuf, but for use by common code in
+lib/*.c. Commands should never directly reference libbuf, and library
+could should nnever directly reference toybuf.</li>
 </ul>
 
 <p>The following functions are defined in main.c:</p>
@@ -632,13 +644,28 @@ itoa().</p>
 errors, to eliminate common error checking. This prints an error message
 and the strerror() string for the errno encountered.</p>
 
-<p>You can intercept this exit by assigning a setjmp/longjmp buffer to
+<p>We replaced exit(), _exit(), and atexit() with xexit(), _xexit(), and
+sigatexit(). This gives _xexit() the option to siglongjmp(toys.rebound, 1)
+instead of exiting, lets xexit() report stdout flush failures to stderr
+and change the exit code to indicate error, lets our toys.exit function
+change happen for signal exit paths and lets us remove the functions
+after we've called them.</p>
+
+<p>You can intercept our exit by assigning a setjmp/longjmp buffer to
 toys.rebound (set it back to zero to restore the default behavior).
 If you do this, cleaning up resource leaks is your problem.</p>
 
 <ul>
 <li><b>void xstrncpy(char *dest, char *src, size_t size)</b></li>
-<li><b>void xexit(void)</b></li>
+<li><p><b><p>void _xexit(void)</b></p>
+<p>Calls siglongjmp(toys.rebound, 1), or else _exit(toys.exitval). This
+lets you ignore errors with the NO_EXIT() macro wrapper, or intercept
+them with WOULD_EXIT().</p>
+<li><b><p>void xexit(void)</b></p>
+<p>Calls toys.xexit functions (if any) and flushes stdout/stderr (reporting
+failure to write to stdout both to stderr and in the exit code), then
+calls _xexit().</p>
+</li>
 <li><b>void *xmalloc(size_t size)</b></li>
 <li><b>void *xzalloc(size_t size)</b></li>
 <li><b>void *xrealloc(void *ptr, size_t size)</b></li>