Bump to version 1.22.1

[platform/upstream/busybox.git] / docs / nofork_noexec.txt

diff --git a/docs/nofork_noexec.txt b/docs/nofork_noexec.txt
index d4abdf4..c58f5a8 100644 (file)
--- a/docs/nofork_noexec.txt
+++ b/docs/nofork_noexec.txt
@@ -2,7 +2,7 @@
 
 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 will fork and exec /bin/echo. For this end, shells
+"echo blah" shell will fork and exec /bin/echo. To this end, shells
 have to _reimplement_ these commands internally.
 
 Busybox is unique in this regard because it already is a collection
@@ -11,14 +11,20 @@ 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
+in applets.h. FEATURE_PREFER_APPLETS is a config option which
 globally enables usage of NOFORK/NOEXEC tricks.
+If it is enabled, FEATURE_SH_STANDALONE can be enabled too,
+and then shells will use NOFORK/NOEXEC tricks for ordinary commands.
+NB: shell builtins use these tricks regardless of FEATURE_SH_STANDALONE
+or FEATURE_PREFER_APPLETS.
 
-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.
+In C, if you want to call a program and wait for it, use
+spawn_and_wait(argv), BB_EXECVP(prog,argv) or BB_EXECLP(prog,argv0,...).
+They check whether program name is an applet name and optionally
+do NOFORK/NOEXEC thing depending on configuration.
 
-NOEXEC
+
+       NOEXEC
 
 NOEXEC applet should work correctly if another applet forks and then
 executes exit(<applet>_main(argc,argv)) in the child. The rules
@@ -32,14 +38,17 @@ roughly are:
 * ...
 
 NOEXEC applets save only one half of fork+exec overhead.
-NOEXEC trick is disabled for NOMMU compile.
+NOEXEC trick is disabled for NOMMU build.
+
 
-NOFORK
+       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:
+<applet>_main(argc,argv) and then continues with its business.
+xargs, find, shells do it (grep for "spawn_and_wait" and
+"run_nofork_applet" to find more users).
+
+This poses much more serious limitations on what applet can do:
 
 * all NOEXEC limitations apply.
 * do not ever exit() or exec().
@@ -49,12 +58,14 @@ on what applet can/cannot do:
     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).
+  (e.g. bb_common_bufsiz1) prior to returning.
   - 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.
+  Otherwise, failing xfunc will return to caller applet
+  without freeing malloced data!
 * All allocated data, opened files, signal handlers, termios settings,
   O_NONBLOCK flags etc should be freed/closed/restored prior to return.
 * ...
@@ -68,3 +79,20 @@ script loops. Applets which mess with signal handlers, termios etc
 are probably not worth the effort.
 
 Any NOFORK applet is also a NOEXEC applet.
+
+
+       Relevant CONFIG options
+
+FEATURE_PREFER_APPLETS
+  BB_EXECVP(cmd, argv) will try to exec /proc/self/exe
+    if command's name matches some applet name
+  applet tables will contain NOFORK/NOEXEC bits
+  spawn_and_wait(argv) will do NOFORK/NOEXEC tricks
+
+FEATURE_SH_STANDALONE (needs FEATURE_PREFER_APPLETS=y)
+  shells will try to exec /proc/self/exe if command's name matches
+    some applet name
+  shells will do NOEXEC trick on NOEXEC applets
+
+FEATURE_SH_NOFORK (needs FEATURE_PREFER_APPLETS=y)
+  shells will do NOFORK trick on NOFORK applets