diff options
| author | Denis Vlasenko <vda.linux@googlemail.com> | 2007-04-11 16:16:41 +0000 |
|---|---|---|
| committer | Denis Vlasenko <vda.linux@googlemail.com> | 2007-04-11 16:16:41 +0000 |
| commit | 0d058361e722757af84fefdf1b1b8eac7ba53fc0 (patch) | |
| tree | f5ca2cd86c41f3699bed4b53c879fa83974d85e3 /docs | |
| parent | 03fc408de6c40e9abca6dd14fde7938f28595bc6 (diff) | |
| download | busybox-w32-0d058361e722757af84fefdf1b1b8eac7ba53fc0.tar.gz busybox-w32-0d058361e722757af84fefdf1b1b8eac7ba53fc0.tar.bz2 busybox-w32-0d058361e722757af84fefdf1b1b8eac7ba53fc0.zip | |
Add NOFORK/NOEXEC documentation.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/nofork_noexec.txt | 70 |
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 @@ | |||
| 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 with fork and exec /bin/echo. For 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. CONFIG_FEATURE_PREFER_APPLETS is a config option which | ||
| 15 | globally enables usage of NOFORK/NOEXEC tricks. | ||
| 16 | |||
| 17 | If you want to call a program and wait for it, use spawn_and_wait(argv). | ||
| 18 | It will check whether argv[0] is an applet name and will optionally | ||
| 19 | do NOFORK/NOEXEC thing. | ||
| 20 | |||
| 21 | NOEXEC | ||
| 22 | |||
| 23 | NOEXEC applet should work correctly if another applet forks and then | ||
| 24 | executes exit(<applet>_main(argc,argv)) in the child. The rules | ||
| 25 | roughly are: | ||
| 26 | |||
| 27 | * do not expect shared global variables/buffers to be in their | ||
| 28 | "initialized" state. Examples: xfunc_error_retval can be != 1, | ||
| 29 | bb_common_bufsiz1 can be scribbled over, ... | ||
| 30 | * do not expect that stdio wasn't used before. Calling set[v]buf() | ||
| 31 | can be disastrous. | ||
| 32 | * ... | ||
| 33 | |||
| 34 | NOEXEC applets save only one half of fork+exec overhead. | ||
| 35 | NOEXEC trick is disabled for NOMMU compile. | ||
| 36 | |||
| 37 | NOFORK | ||
| 38 | |||
| 39 | NOFORK applet should work correctly if another applet simply runs | ||
| 40 | <applet>_main(argc,argv) and then continues with its business (xargs, | ||
| 41 | find, shells can do it). This poses much more serious limitations | ||
| 42 | on what applet can/cannot do: | ||
| 43 | |||
| 44 | * all NOEXEC limitations apply. | ||
| 45 | * do not ever exit() or exec(). | ||
| 46 | - xfuncs are okay. They are using special trick to return | ||
| 47 | to the caller applet instead of dying when they detect "x" condition. | ||
| 48 | - you may "exit" to caller applet by calling xfunc_die(). Return value | ||
| 49 | is taken from xfunc_error_retval. | ||
| 50 | - fflush_stdout_and_exit(n) is ok to use. | ||
| 51 | * do not use shared global data, or save/restore shared global data | ||
| 52 | prior to returning. (e.g. bb_common_bufsiz1 is off-limits). | ||
| 53 | - getopt32() is ok to use. You do not need to save/restore option_mask32, | ||
| 54 | it is already done by core code. | ||
| 55 | * if you allocate memory, you can use xmalloc() only on the very first | ||
| 56 | allocation. All other allocations should use malloc[_or_warn](). | ||
| 57 | After first allocation, you cannot use any xfuncs. | ||
| 58 | * All allocated data, opened files, signal handlers, termios settings, | ||
| 59 | O_NONBLOCK flags etc should be freed/closed/restored prior to return. | ||
| 60 | * ... | ||
| 61 | |||
| 62 | NOFORK applets give the most of speed advantage, but are trickiest | ||
| 63 | to implement. In order to minimize amount of bugs and maintenance, | ||
| 64 | prime candidates for NOFORK-ification are those applets which | ||
| 65 | are small and easy to audit, and those which are more likely to be | ||
| 66 | frequently executed from shell/find/xargs, particularly in shell | ||
| 67 | script loops. Applets which mess with signal handlers, termios etc | ||
| 68 | are probably not worth the effort. | ||
| 69 | |||
| 70 | Any NOFORK applet is also a NOEXEC applet. | ||