[git commit] Delete or fix outdated information
Denys Vlasenko
vda.linux at googlemail.com
Sun Aug 6 11:45:40 UTC 2017
commit: https://git.busybox.net/busybox-website/commit/?id=9228ff0e8acc1a27dba025ba7f3ca61cd82258da
branch: https://git.busybox.net/busybox-website/commit/?id=refs/heads/master
Signed-off-by: Denys Vlasenko <vda.linux at googlemail.com>
---
FAQ.html | 95 ++++++++++++++++------------------------------------------------
1 file changed, 24 insertions(+), 71 deletions(-)
diff --git a/FAQ.html b/FAQ.html
index 29db55c..97f155f 100644
--- a/FAQ.html
+++ b/FAQ.html
@@ -31,7 +31,6 @@ have additions/corrections to this document, we would love to add them.
<li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li>
<li><a href="#init">Busybox init isn't working!</a></li>
<li><a href="#emu">I am observing a bug in BusyBox on an obscure platform. Help.</a></li>
-<li><a href="#sed">I can't configure Busybox on my system</a></li>
<li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li>
<li><a href="#touch_config">sed "/CONFIG_FOO/s/.*/CONFIG_FOO=y/" -i .config; make; does not enable applet foo</a></li>
<li><a href="#symlink_danger">I installed a package on my Busybox system and now nothing works!</a></li>
@@ -88,7 +87,8 @@ have additions/corrections to this document, we would love to add them.
solution for running modems, or wireless access points, etc.
Busybox is only a set of programs. Even though it is a fairly
comprehensive set of programs needed to run a Linux system, these
- programs per se can not "run a modem".
+ programs per se can not "run a modem", just like construction worker's
+ toolbox and materials can't build a house by themselves.
</p>
<p> In order to make Busybox-based system useful, developers of this system
@@ -818,35 +818,6 @@ int main(int argc, char *argv)
</p>
<hr />
-<h2><a name="sed">I can't configure Busybox on my system</a></h2>
-
-<p>
- Configuring Busybox depends on a recent version of sed. Older
- distributions (Red Hat 7.2, Debian 3.0) may not come with a
- usable version. Luckily Busybox can use its own sed to configure itself,
- although this leads to a bit of a chicken and egg problem.
- You can work around this by hand-configuring Busybox to build with just
- sed, then putting that sed in your path to configure the rest of Busybox
- with, like so:
-</p>
-
-<pre>
- tar xvjf sources/busybox-x.x.x.tar.bz2
- cd busybox-x.x.x
- make allnoconfig
- make include/bb_config.h
- echo "CONFIG_SED=y" >> .config
- echo "#undef ENABLE_SED" >> include/bb_config.h
- echo "#define ENABLE_SED 1" >> include/bb_config.h
- make
- mv busybox sed
- export PATH=`pwd`:"$PATH"
-</pre>
-</p>
-
-<p>Then you can run "make defconfig" or "make menuconfig" normally.</p>
-
-<hr />
<h2><a name="job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></h2>
<p>
@@ -950,7 +921,8 @@ int main(int argc, char *argv)
<a name="standalone_shell">"standalone shell"</a>, where the Busybox
shell runs any built-in applets before checking the command path. This
feature is not enabled by "make defconfig". To try it out, set
- CONFIG_FEATURE_PREFER_APPLETS and CONFIG_FEATURE_SH_STANDALONE to 'y'
+ CONFIG_FEATURE_PREFER_APPLETS, CONFIG_FEATURE_SH_STANDALONE
+ and CONFIG_FEATURE_SH_NOFORK to 'y'
in .config (using text editor, or by running "make menuconfig" and
setting these options interactively), rebuild Busybox, then run
the command line "PATH= ./busybox ash".
@@ -1067,16 +1039,15 @@ writing.</p>
<hr />
<h2><a name="source_applets">The applet directories</a></h2>
-<p>The directory "applets" contains the Busybox startup code (applets.c and
-Busybox.c), and several subdirectories containing the code for the individual
-applets.</p>
+<p>Source tree has several subdirectories containing the code
+for the individual applets.</p>
-<p>Busybox execution starts with the main() function in applets/busybox.c,
+<p>Busybox execution starts with the main() function in libbb/appletlib.c,
which sets the global variable applet_name to argv[0] and calls
-run_applet_and_exit() in applets/applets.c. That uses the applets[] array
-(defined in include/busybox.h and filled out in include/applets.h) to
-transfer control to the appropriate APPLET_main() function (such as
-cat_main() or sed_main()). The individual applet takes it from there.</p>
+run_applet_and_exit(). That uses the applets[] array
+(defined in include/applets.h) to transfer control to the appropriate
+APPLET_main() function (such as cat_main() or sed_main()).
+The individual applet takes it from there.</p>
<p>This is why calling Busybox under a different name triggers different
functionality: main() looks up argv[0] in applets[] to get a function pointer
@@ -1098,8 +1069,8 @@ file defining that configuration sub-menu (with dependencies and help text
for each applet), and the makefile segment (Kbuild) for that
subdirectory.</p>
-<p>The run-time --help is stored in usage_messages[], which is initialized at
-the start of applets/applets.c and gets its help text from usage.h. During the
+<p>The run-time --help is stored in usage_messages[], which is initialized in
+libbb/appletlib.c and gets its help text from usage.h. During the
build this help text is also used to generate the Busybox documentation (in
html, txt, and man page formats) in the docs directory. See
<a href="#adding">adding an applet to Busybox</a> for more
@@ -1186,28 +1157,10 @@ a corresponding CONFIG_NAME. Then do this:</p>
and put your source code there. Be sure to use APPLET_main() instead
of main(), where APPLET is the name of your applet.</li>
-<li>Add your applet to the relevant Config.in file (which file you add
-it to determines where it shows up in "make menuconfig"). This uses
-the same general format as the linux kernel's configuration system.</li>
-
-<li>Add your applet to the relevant Kbuild file (in the same directory
-as the Config.in you chose), using the existing entries as a template
-and the same CONFIG symbol as you used for Config.in.</li>
-
-<li>Add your applet to "include/applets.h", using one of the existing
-entries as a template. (Note: they are in alphabetical order. Applets
-are found via binary search, and if you add an applet out of order it
-won't work.)</li>
-
-<li>Add your applet's runtime help text to "include/usage.h". You need
-at least appname_trivial_usage (the minimal help text, always included
-in the Busybox binary when this applet is enabled) and appname_full_usage
-(extra help text included in the Busybox binary with
-CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile.
-The other two help entry types (appname_example_usage and
-appname_notes_usage) are optional. They don't take up space in the binary,
-but instead show up in the generated documentation (BusyBox.html,
-BusyBox.txt, and the man page busybox.1).</li>
+<li>Your source .c file should contain config directives, applet table
+entries, instructions for make, and usage texts
+(//config:, //applet:, //kbuild: and //usage: lines).
+See other applets for examples.</li>
<li>Run menuconfig, switch your applet on, compile, test, and fix the
bugs. Be sure to try both "allyesconfig" and "allnoconfig".</li>
@@ -1371,15 +1324,14 @@ encrypted, and the second is a string in "$type$salt$password" format, from
which the "type" and "salt" fields will be extracted to produce an encrypted
value. (Only the first two fields are needed, the third $ is equivalent to
the end of the string.) The return value is an encrypted password in
-/etc/passwd format, with all three $ separated fields. It's stored in
-a static buffer, 128 bytes long.</p>
+/etc/passwd format, with all three $ separated fields.</p>
<p>So when checking an existing password, if pw_encrypt(text,
old_encrypted_password) returns a string that compares identical to
old_encrypted_password, you've got the right password. When setting a new
password, generate a random 8 character salt string, put it in the right
format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the
-second argument to pw_encrypt(text,buffer).</p>
+second argument to pw_encrypt(text, buffer).</p>
<hr />
<h2><a name="tips_vfork">Fork and vfork</a></h2>
@@ -1441,8 +1393,8 @@ until that happens. In fact without suspending the parent there's no way to
even store separate copies of the return value (the pid) from the vfork() call
itself: both assignments write into the same memory location.</p>
-<p>One way to understand (and in fact implement) vfork() is this: imagine
-the parent does a setjmp and then continues on (pretending to be the child)
+<p>One way to understand vfork() is this: imagine the parent does
+a setjmp and then continues on (pretending to be the child)
until the exec() comes around, then the _exec_ does the actual fork, and the
parent does a longjmp back to the original vfork call and continues on from
there. (It thus becomes obvious why the child should not return (this would
@@ -1462,8 +1414,9 @@ is good enough.</p>
<p>Another thing to keep in mind is that if vforked child allocates any memory
and does not free it before exec or exit, parent will also have this memory
allocated. Unless child takes care to record the address of these memory areas
-and parent frees them, they will be leaked. This should be avoided
-if parent process is long lived. The prime example is the shell.</p>
+and parent frees them, they will be leaked. This applies to "hidden" allocations
+as well, in particular, ones inside setenv().
+The prime example is the shell.</p>
<hr />
<h2><a name="tips_sort_read">Short reads and writes</a></h2>
More information about the busybox-cvs
mailing list