From 4aca87515a5083ae0e31ce3177189fd43b6d05ac Mon Sep 17 00:00:00 2001 From: Andreas Baumann Date: Sat, 3 Jan 2015 13:58:15 +0100 Subject: patch to Vanilla Tomato 1.28 --- release/src/router/busybox/docs/nofork_noexec.txt | 79 +++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 release/src/router/busybox/docs/nofork_noexec.txt (limited to 'release/src/router/busybox/docs/nofork_noexec.txt') diff --git a/release/src/router/busybox/docs/nofork_noexec.txt b/release/src/router/busybox/docs/nofork_noexec.txt new file mode 100644 index 00000000..06c789af --- /dev/null +++ b/release/src/router/busybox/docs/nofork_noexec.txt @@ -0,0 +1,79 @@ + 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 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 +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. 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. + +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 applet should work correctly if another applet forks and then +executes exit(_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 build. + + + NOFORK + +NOFORK applet should work correctly if another applet simply runs +_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. + 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. +* ... + +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. -- cgit v1.2.3-54-g00ecf