Add NOFORK/NOEXEC documentation.

1 files changed, 70 insertions, 0 deletions

diff --git a/docs/nofork_noexec.txt b/docs/nofork_noexec.txt
new file mode 100644
index 000000000..d54f19642
--- /dev/null
+++ b/docs/nofork_noexec.txt
@@ -0,0 +1,70 @@
+        NOEXEC and NOFORK applets.
+
+Unix shells traditionally execute some commands internally in the attempt
+to dramatically speed up execution. It will be slow as hell if for every
+"echo blah" shell with fork and exec /bin/echo. For this end, shells
+have to _reimplement_ these commands internally.
+
+Busybox is unique in this regard because it already is a collection
+of reimplemented Unix commands, and we can do the same trick
+for speeding up busybox shells, and more. NOEXEC and NOFORK applets
+are exactly those applets which are eligible for these tricks.
+
+Applet will be subject to NOFORK/NOEXEC tricks if it is marked as such
+in applets.h. CONFIG_FEATURE_PREFER_APPLETS is a config option which
+globally enables usage of NOFORK/NOEXEC tricks. 
+
+If you want to call a program and wait for it, use spawn_and_wait(argv).
+It will check whether argv[0] is an applet name and will optionally
+do NOFORK/NOEXEC thing.
+
+NOEXEC
+
+NOEXEC applet should work correctly if another applet forks and then
+executes exit(<applet>_main(argc,argv)) in the child. The rules
+roughly are:
+
+* do not expect shared global variables/buffers to be in their
+  "initialized" state. Examples: xfunc_error_retval can be != 1,
+  bb_common_bufsiz1 can be scribbled over, ...
+* do not expect that stdio wasn't used before. Calling set[v]buf()
+  can be disastrous.
+* ...
+
+NOEXEC applets save only one half of fork+exec overhead.
+NOEXEC trick is disabled for NOMMU compile.
+
+NOFORK
+
+NOFORK applet should work correctly if another applet simply runs
+<applet>_main(argc,argv) and then continues with its business (xargs,
+find, shells can do it). This poses much more serious limitations
+on what applet can/cannot do:
+
+* all NOEXEC limitations apply.
+* do not ever exit() or exec().
+  - xfuncs are okay. They are using special trick to return
+    to the caller applet instead of dying when they detect "x" condition.
+  - you may "exit" to caller applet by calling xfunc_die(). Return value
+    is taken from xfunc_error_retval.
+  - fflush_stdout_and_exit(n) is ok to use.
+* do not use shared global data, or save/restore shared global data
+  prior to returning. (e.g. bb_common_bufsiz1 is off-limits).
+  - getopt32() is ok to use. You do not need to save/restore option_mask32,
+    it is already done by core code.
+* if you allocate memory, you can use xmalloc() only on the very first
+  allocation. All other allocations should use malloc[_or_warn]().
+  After first allocation, you cannot use any xfuncs.
+* All allocated data, opened files, signal handlers, termios settings,
+  O_NONBLOCK flags etc should be freed/closed/restored prior to return.
+* ...
+
+NOFORK applets give the most of speed advantage, but are trickiest
+to implement. In order to minimize amount of bugs and maintenance,
+prime candidates for NOFORK-ification are those applets which
+are small and easy to audit, and those which are more likely to be
+frequently executed from shell/find/xargs, particularly in shell
+script loops. Applets which mess with signal handlers, termios etc
+are probably not worth the effort.
+
+Any NOFORK applet is also a NOEXEC applet.