FAQ: move "standalone shell" into troubleshooting section

Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>

1 files changed, 76 insertions, 66 deletions

diff --git a/FAQ.html b/FAQ.html
index 1b1fda4..d7f5f56 100644
--- a/FAQ.html
+++ b/FAQ.html
@@ -33,6 +33,7 @@ have additions/corrections to this document, we would love to add them.
 <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>
+<li><a href="#standalone_shell">I selected "standalone shell" option and now I have problems</a></li>
 </ol>
 
 <h2>Misc. questions</h2>
@@ -263,72 +264,6 @@ have additions/corrections to this document, we would love to add them.
  LDFLAGS="--static" make -j 4 CROSS_COMPILE="armv4tl-"
 </pre>
 
-<h3>Standalone shell</h3>
-
-<p>
-    Busybox also has a feature called the
-    <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'
-    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".
-    This will blank your command search path
-    and run Busybox as your command shell, so the only commands it can find
-    (without an explicit path such as /bin/ls) are the built-in Busybox ones.
-    Note that the standalone shell also requires CONFIG_BUSYBOX_EXEC_PATH
-    to be set appropriately, and the default value, /proc/self/exe, would work
-    only if /proc filesystem is mounted.
-    (So if you set it to /proc/self/exe, and happen to be able to chroot into
-    your rootfs, you must mount /proc beforehand.)
-    If you do not have /proc mouted, then point that config option
-    to the location of your Busybox binary, usually /bin/busybox.
-</p>
-<p>
-    A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to
-    /proc/self/exe but /proc is not mounted:
-</p>
-<pre>
-$ /bin/echo $PATH
-/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11
-$ echo $PATH
-/bin/sh: echo: not found
-</pre>
-<p>
-    If this is a serious limitation for you, you may patch the kernel
-    so that it always understands exec("/proc/self/exe"), even if /proc
-    is not mounted. For example, in linux-2.6.30, you need to patch
-    open_exec() function in fs/exec.c file:
-</p>
-<pre>
-        file = do_filp_open(AT_FDCWD, name,
-                                O_LARGEFILE | O_RDONLY | FMODE_EXEC, 0,
-                                MAY_EXEC | MAY_OPEN);
--       if (IS_ERR(file))
--               goto out;
-+       if (IS_ERR(file)) {
-+               if ((PTR_ERR(file) == -ENOENT || PTR_ERR(file) == -EACCES)
-+                && strcmp(name, "/proc/self/exe") == 0
-+               ) {
-+                       struct file *sv = file;
-+                       struct mm_struct *mm;
-
-+                       mm = get_task_mm(current);
-+                       if (!mm)
-+                               goto out;
-+                       file = get_mm_exe_file(mm);
-+                       mmput(mm);
-+                       if (file)
-+                               goto ok;
-+                       file = sv;
-+               }
-+               goto out;
-+       }
-+ok:
-        err = -EACCES;
-</pre>
-
 <hr />
 <h2><a name="configure">How do I configure Busybox?</a></h2>
 
@@ -916,6 +851,81 @@ int main(int argc, char *argv)
 </p>
 
 <hr />
+<h2><a name="standalone_shell">I selected "standalone shell" option and now I have problems</a></h2>
+
+<p>
+    Busybox has a feature called the
+    <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'
+    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".
+    This will blank your command search path
+    and run Busybox as your command shell, so the only commands it can find
+    (without an explicit path such as /bin/ls) are the built-in Busybox ones.
+    Note that the standalone shell also requires CONFIG_BUSYBOX_EXEC_PATH
+    to be set appropriately, and the default value, /proc/self/exe, would work
+    only if /proc filesystem is mounted.
+    (So if you set it to /proc/self/exe, and happen to be able to chroot into
+    your rootfs, you must mount /proc beforehand.)
+    If you do not have /proc mouted, then point that config option
+    to the location of your Busybox binary, usually /bin/busybox.
+</p>
+<p>
+    A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to
+    /proc/self/exe but /proc is not mounted:
+</p>
+<pre>
+$ /bin/echo $PATH
+/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11
+$ echo $PATH
+/bin/sh: echo: not found
+</pre>
+<p>
+    If this is a serious limitation for you, you may patch the kernel
+    so that it always understands exec("/proc/self/exe"), even if /proc
+    is not mounted. For example, in linux-2.6.30, you need to patch
+    open_exec() function in fs/exec.c file:
+</p>
+<pre>
+        file = do_filp_open(AT_FDCWD, name,
+                                O_LARGEFILE | O_RDONLY | FMODE_EXEC, 0,
+                                MAY_EXEC | MAY_OPEN);
+-       if (IS_ERR(file))
+-               goto out;
++       if (IS_ERR(file)) {
++               if ((PTR_ERR(file) == -ENOENT || PTR_ERR(file) == -EACCES)
++                && strcmp(name, "/proc/self/exe") == 0
++               ) {
++                       struct file *sv = file;
++                       struct mm_struct *mm;
+
++                       mm = get_task_mm(current);
++                       if (!mm)
++                               goto out;
++                       file = get_mm_exe_file(mm);
++                       mmput(mm);
++                       if (file)
++                               goto ok;
++                       file = sv;
++               }
++               goto out;
++       }
++ok:
+        err = -EACCES;
+</pre>
+<p>
+    Since standalone shell option is not the default, it is less thoroughly
+    tested. If you think you see a bug in standalone shell's behavior,
+    first verify that the bug is indeed caused by this option: rebuild
+    Busybox with CONFIG_FEATURE_PREFER_APPLETS and CONFIG_FEATURE_SH_STANDALONE
+    turned off. If shell's behavior has changed, report the bug to the Busybox
+    mailing list.
+</p>
+
+<hr />
 <h1>Misc. questions</h1>
 
 <hr />