docs/nofork_noexec.txt

   1         NOEXEC and NOFORK applets.
   2
   3 Unix shells traditionally execute some commands internally in the attempt
   4 to dramatically speed up execution. It will be slow as hell if for every
   5 "echo blah" shell will fork and exec /bin/echo. To this end, shells
   6 have to _reimplement_ these commands internally.
   7
   8 Busybox is unique in this regard because it already is a collection
   9 of reimplemented Unix commands, and we can do the same trick
  10 for speeding up busybox shells, and more. NOEXEC and NOFORK applets
  11 are exactly those applets which are eligible for these tricks.
  12
  13 Applet will be subject to NOFORK/NOEXEC tricks if it is marked as such
  14 in applets.h. FEATURE_PREFER_APPLETS is a config option which
  15 globally enables usage of NOFORK/NOEXEC tricks.
  16 If it is enabled, FEATURE_SH_STANDALONE can be enabled too,
  17 and then shells will use NOFORK/NOEXEC tricks for ordinary commands.
  18 NB: shell builtins use these tricks regardless of FEATURE_SH_STANDALONE
  19 or FEATURE_PREFER_APPLETS.
  20
  21 In C, if you want to call a program and wait for it, use
  22 spawn_and_wait(argv), BB_EXECVP(prog,argv) or BB_EXECLP(prog,argv0,...).
  23 They check whether program name is an applet name and optionally
  24 do NOFORK/NOEXEC thing depending on configuration.
  25
  26
  27         NOEXEC
  28
  29 NOEXEC applet should work correctly if another applet forks and then
  30 executes exit(<applet>_main(argc,argv)) in the child. The rules
  31 roughly are:
  32
  33 * do not expect shared global variables/buffers to be in their
  34   "initialized" state. Examples: xfunc_error_retval can be != 1,
  35   bb_common_bufsiz1 can be scribbled over, ...
  36   (although usually xfunc_error_retval's state is not a problem).
  37 * do not expect that stdio wasn't used before. Calling set[v]buf()
  38   can be disastrous.
  39 * ...
  40
  41 NOEXEC applets save only one half of fork+exec overhead.
  42 NOEXEC trick is disabled for NOMMU build.
  43
  44
  45         NOFORK
  46
  47 NOFORK applet should work correctly if another applet simply runs
  48 <applet>_main(argc,argv) and then continues with its business.
  49 xargs, find, shells do it (grep for "spawn_and_wait" and
  50 "run_nofork_applet" to find more users).
  51
  52 This poses much more serious limitations on what applet can do:
  53
  54 * all NOEXEC limitations apply.
  55 * do not run for a long time or wait for user input:
  56   hush shell only handles signals (like ^C) after you return
  57   from APPLET_main().
  58 * do not ever exit() or exec().
  59   - xfuncs are okay. They are using special trick to return
  60     to the caller applet instead of dying when they detect "x" condition.
  61   - you may "exit" to caller applet by calling xfunc_die(). Return value
  62     is taken from xfunc_error_retval.
  63   - fflush_stdout_and_exit(n) is ok to use.
  64 * do not use shared global data, or save/restore shared global data
  65   (e.g. bb_common_bufsiz1) prior to returning.
  66   - getopt32() is ok to use. You do not need to save/restore option_mask32,
  67     it is already done by core code.
  68 * if you allocate memory, you can use xmalloc() only on the very first
  69   allocation. All other allocations should use malloc[_or_warn]().
  70   After first allocation, you cannot use any xfuncs.
  71   Otherwise, failing xfunc will return to caller applet
  72   without freeing malloced data!
  73 * All allocated data, opened files, signal handlers, termios settings,
  74   O_NONBLOCK flags etc should be freed/closed/restored prior to return.
  75 * ...
  76
  77 NOFORK applets give the most of speed advantage, but are trickiest
  78 to implement. In order to minimize amount of bugs and maintenance,
  79 prime candidates for NOFORK-ification are those applets which
  80 are small and easy to audit, and those which are more likely to be
  81 frequently executed from shell/find/xargs, particularly in shell
  82 script loops. Applets which mess with signal handlers, termios etc
  83 are probably not worth the effort.
  84
  85 Any NOFORK applet is also a NOEXEC applet.
  86
  87
  88         Calling NOFORK applets
  89
  90 API to call NOFORK applets is two functions:
  91
  92         run_nofork_applet(appno, argv)
  93         spawn_and_wait(argv) // only if FEATURE_PREFER_APPLETS=y
  94
  95 First one is directly used by shells if FEATURE_SH_NOFORK=y.
  96 Second one is used by many applets, but main users are xargs and find.
  97 It itself calls run_nofork_applet(), if argv[0] turned out to be a name
  98 of a NOFORK applet.
  99
 100 run_nofork_applet() saves/inits/restores option parsing, xfunc_error_retval,
 101 applet_name. Thus, for example, caller does not need to worry about
 102 option_mask32 getting trashed.
 103
 104
 105         Calling NOEXEC applets
 106
 107 It's the same trusty spawn_and_wait(argv). If FEATURE_PREFER_APPLETS=y,
 108 it does NOEXEC trick. It resets xfunc_error_retval = 1 and
 109 logmode = LOGMODE_STDIO in the child.
 110
 111
 112         Relevant CONFIG options
 113
 114 FEATURE_PREFER_APPLETS
 115   BB_EXECVP(cmd, argv) will try to exec /proc/self/exe
 116   if command's name matches some applet name;
 117   spawn_and_wait(argv) will do NOFORK/NOEXEC tricks
 118
 119 //TODO: the above two things probably should have separate options?
 120
 121 FEATURE_SH_STANDALONE
 122   shells will try to exec /proc/self/exe if command's name matches
 123   some applet name; shells will do NOEXEC trick on NOEXEC applets
 124
 125 //TODO: split (same as for PREFER_APPLETS)
 126
 127 FEATURE_SH_NOFORK
 128   shells will do NOFORK trick on NOFORK applets