0d058361e
Denis Vlasenko
2007-04-11
Subject
Add NOFORK/NOEXEC documentation.
Binary
No binary (build failed)
Architecture & Compiler Flags
—
Build Log
(log yok)
Commit Diff GitHub →
docs/nofork_noexec.txt+70 -0
| @@ -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. |