1 <!--#include file="header.html" -->
3 <h3>Frequently Asked Questions</h3>
5 This is a collection of some of the more frequently asked questions
6 about BusyBox. Some of the questions even have answers. If you
7 have additions to this FAQ document, we would love to add them,
9 <h2>General questions</h2>
11 <li><a href="#getting_started">How can I get started using BusyBox?</a></li>
12 <li><a href="#configure">How do I configure busybox?</a></li>
13 <li><a href="#build_system">How do I build a BusyBox-based system?</a></li>
14 <li><a href="#kernel">Which Linux kernel versions are supported?</a></li>
15 <li><a href="#arch">Which architectures does BusyBox run on?</a></li>
16 <li><a href="#libc">Which C libraries are supported?</a></li>
17 <li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li>
18 <li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li></li>
19 <li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li>
20 <li><a href="#helpme">I need help with BusyBox! What should I do?</a></li>
21 <li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li>
24 <h2>Troubleshooting</h2>
26 <li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li>
27 <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>
28 <li><a href="#init">Busybox init isn't working!</a></li>
29 <li><a href="#sed">I can't configure busybox on my system.</a></li>
30 <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>
33 <h2>Programming questions</h2>
35 <li><a href="#goals">What are the goals of busybox?</a></li>
36 <li><a href="#design">What is the design of busybox?</a></li>
37 <li><a href="#source">How is the source code organized?</a></li>
39 <li><a href="#source_applets">The applet directories.</a></li>
40 <li><a href="#source_libbb">The busybox shared library (libbb)</a></li>
42 <li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a></li>
43 <li><a href="#adding">Adding an applet to busybox</a></li>
44 <li><a href="#standards">What standards does busybox adhere to?</a></li>
45 <li><a href="#portability">Portability.</a></li>
46 <li><a href="#tips">Tips and tricks.</a></li>
48 <li><a href="#tips_encrypted_passwords">Encrypted Passwords</a></li>
49 <li><a href="#tips_vfork">Fork and vfork</a></li>
50 <li><a href="#tips_short_read">Short reads and writes</a></li>
51 <li><a href="#tips_memory">Memory used by relocatable code, PIC, and static linking.</a></li>
52 <li><a href="#tips_kernel_headers">Including Linux kernel headers.</a></li>
54 <li><a href="#who">Who are the BusyBox developers?</a></li>
60 <h1>General questions</h1>
64 <h2><a name="getting_started">How can I get started using BusyBox?</a></h2>
65 <p> If you just want to try out busybox without installing it, download the
66 tarball, extract it, run "make defconfig", and then run "make".
69 This will create a busybox binary with almost all features enabled. To try
70 out a busybox applet, type "./busybox [appletname] [options]", for
71 example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox"
72 to see a command list, and "busybox appletname --help" to see a brief
73 usage message for a given applet.
76 BusyBox uses the name it was invoked under to determine which applet is
77 being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing
78 busybox consists of creating symlinks (or hardlinks) to the busybox
79 binary for each applet in busybox, and making sure these links are in
80 the shell's command $PATH. The special applet name "busybox" (or with
81 any optional suffix, such as "busybox-static") uses the first argument
82 to determine which applet to run, as shown above.
85 BusyBox also has a feature called the "standalone shell", where the busybox
86 shell runs any built-in applets before checking the command path. This
87 feature is also enabled by "make allyesconfig", and to try it out run
88 the command line "PATH= ./busybox ash". This will blank your command path
89 and run busybox as your command shell, so the only commands it can find
90 (without an explicit path such as /bin/ls) are the built-in busybox ones.
91 This is another good way to see what's built into busybox. (Note that the
92 standalone shell is dependent on the existence of /proc/self/exe, so before
93 using it in a chroot environment you must mount /proc.)
98 <h2><a name="configure">How do I configure busybox?</a></h2>
99 <p> Busybox is configured similarly to the linux kernel. Create a default
100 configuration and then run "make menuconfig" to modify it. The end
101 result is a .config file that tells the busybox build process what features
102 to include. So instead of "./configure; make; make install" the equivalent
103 busybox build would be "make defconfig; make; make install".
106 <p> Busybox configured with all features enabled is a little under a megabyte
107 dynamically linked on x86. To create a smaller busybox, configure it with
108 fewer features. Individual busybox applets cost anywhere from a few
109 hundred bytes to tens of kilobytes. Disable unneeded applets to save,
110 space, using menuconfig.
113 <p>The most important busybox configurators are:</p>
116 <li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This
117 enables almost all features, minus things like debugging options and features
118 that require changes to the rest of the system to work (such as selinux or
119 devfs device names). Use this if you want to start from a full-featured
120 busybox and remove features until it's small enough.</p></li>
121 <li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version
122 of busybox that doesn't do anything. Start here if you know exactly what
123 you want and would like to select only those features.</p></li>
124 <li><p>make <b>menuconfig</b> - Interactively modify a .config file through a
125 multi-level menu interface. Use this after one of the previous two.</p></li>
128 <p>Some other configuration options are:</p>
130 <li><p>make <b>oldconfig</b> - Update an old .config file for a newer version
132 <li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates
133 a statically linked version of busybox full of debug code, with dependencies on
134 selinux, using devfs names... This makes sure everything compiles. Whether
135 or not the result would do anything useful is an open question.</p></li>
136 <li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features
137 within each applet. More build coverage testing.</p></li>
138 <li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li>
141 <p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable
142 busybox features, and get help about each feature.
147 To build a smaller busybox binary, run "make menuconfig" and disable the
148 features you don't need. (Or run "make allnoconfig" and then use
149 menuconfig to add just the features you need. Don't forget to recompile
150 with "make" once you've finished configuring.)
154 <h2><a name="build_system">How do I build a BusyBox-based system?</a></h2>
156 BusyBox is a package that replaces a dozen standard packages, but it is
157 not by itself a complete bootable system. Building an entire Linux
158 distribution from source is a bit beyond the scope of this FAQ, but it
159 understandably keeps cropping up on the mailing list, so here are some
163 Start by learning how to strip a working system down to the bare essentials
164 needed to run one or two commands, so you know what it is you actually
165 need. An excellent practical place to do
166 this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux
167 BootDisk Howto</a>, or for a more theoretical approach try
168 <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From
169 PowerUp to Bash Prompt</a>.
172 To learn how to build a working Linux system entirely from source code,
173 the place to go is the <a href="http://www.linuxfromscratch.org">Linux
174 From Scratch</a> project. They have an entire book of step-by-step
176 <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a>
178 <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>.
179 Be sure to check out the other sections of their main page, including
180 Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints
181 directory, and their LiveCD project. (They also have mailing lists which
182 are better sources of answers to Linux-system building questions than
186 If you want an automated yet customizable system builder which produces
187 a BusyBox and uClibc based system, try
188 <a href="http://buildroot.uclibc.org">buildroot</a>, which is
189 another project by the maintainer of the uClibc (Erik Andersen).
190 Download the tarball, extract it, unset CC, make.
191 For more instructions, see the website.
196 <h2><a name="kernel">Which Linux kernel versions are supported?</a></h2>
198 Full functionality requires Linux 2.4.x or better. (Earlier versions may
199 still work, but are no longer regularly tested.) A large fraction of the
200 code should run on just about anything. While the current code is fairly
201 Linux specific, it should be fairly easy to port the majority of the code
202 to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you
203 are into that sort of thing).
207 <h2><a name="arch">Which architectures does BusyBox run on?</a></h2>
209 BusyBox in general will build on any architecture supported by gcc.
210 Kernel module loading for 2.4 Linux kernels is currently
211 limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC,
212 S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels.
215 With 2.6.x kernels, module loading support should work on all architectures.
219 <h2><a name="libc">Which C libraries are supported?</a></h2>
221 On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and
222 glibc (2.2 or later). Both should provide full functionality with busybox,
223 and if you find a bug we want to hear about it.
226 Linux-libc5 is no longer maintained (and has no known advantages over
227 uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is
228 missing too many features to build BusyBox. If you require a small C
229 library for Linux, the busybox developers recommend uClibc.
232 Some BusyBox applets have been built and run under a combination
233 of newlib and libgloss (see
234 <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>).
235 This is still experimental, but may be supported in a future release.
240 <h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2>
244 Yes. As long as you <a href="http://busybox.net/license.html">fully comply
245 with the generous terms of the GPL BusyBox license</a> you can ship BusyBox
246 as part of the software on your device.
251 <h2><a name="external">where can i find other small utilities since busybox
252 does not include the features i want?</a></h2>
254 we maintain such a <a href="tinyutils.html">list</a> on this site!
259 <h2><a name="demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></h2>
262 You have not paid us a single cent and yet you still have the product of
263 many years of our work. We are not your slaves! We work on BusyBox
264 because we find it useful and interesting. If you go off flaming us, we
270 <h2><a name="helpme">I need help with BusyBox! What should I do?</a></h2>
273 If you find that you need help with BusyBox, you can ask for help on the
274 BusyBox mailing list at busybox@busybox.net.</p>
276 <p> In addition to the mailing list, Erik Andersen (andersee), Manuel Nova
277 (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), Bernhard Fischer
278 (blindvt), and other long-time BusyBox developers are known to hang out
279 on the uClibc IRC channel: #uclibc on irc.freenode.net. There is a
280 <a href="http://ibot.Rikers.org/%23uclibc/">web archive of
281 daily logs of the #uclibc IRC channel</a> going back to 2002.
285 <b>Please do not send private email to Rob, Erik, Manuel, or the other
286 BusyBox contributors asking for private help unless you are planning on
287 paying for consulting services.</b>
291 When we answer questions on the BusyBox mailing list, it helps everyone
292 since people with similar problems in the future will be able to get help
293 by searching the mailing list archives. Private help is reserved as a paid
294 service. If you need to use private communication, or if you are serious
295 about getting timely assistance with BusyBox, you should seriously consider
296 paying for consulting services.
301 <h2><a name="contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></h2>
305 Yes we are. The easy way to sponsor a new feature is to post an offer on
306 the mailing list to see who's interested. You can also email the project's
307 maintainer and ask them to recommend someone.
310 <p> If you prefer to deal with an organization rather than an individual, Rob
311 Landley (the current BusyBox maintainer) works for
312 <a http://www.timesys.com>TimeSys</a>, and Eric Andersen (the previous
313 busybox maintainer and current uClibc maintainer) owns
314 <a href="http://codepoet-consulting.com/">CodePoet Consulting</a>. Both
315 companies offer support contracts and handle new development, and there
316 are plenty of other companies that do the same.
322 <h1>Troubleshooting</h1>
326 <h2><a name="bugs">I think I found a bug in BusyBox! What should I do?</a></h2>
330 If you simply need help with using or configuring BusyBox, please submit a
331 detailed description of your problem to the BusyBox mailing list at <a
332 href="mailto:busybox@busybox.net"> busybox@busybox.net</a>.
333 Please do not send email to individual developers asking
334 for private help unless you are planning on paying for consulting services.
335 When we answer questions on the BusyBox mailing list, it helps everyone,
336 while private answers help only you...
340 Bug reports and new feature patches sometimes get lost when posted to the
341 mailing list, because the developers of BusyBox are busy people and have
342 only so much they can keep in their brains at a time. You can post a
343 polite reminder after 2-3 days without offending anybody. If that doesn't
344 result in a solution, please use the
345 <a href="http://bugs.busybox.net/">BusyBox Bug
346 and Patch Tracking System</a> to submit a detailed explanation and we'll
347 get to it as soon as we can.
351 Note that bugs entered into the bug system without being mentioned on the
352 mailing list first may languish there for months before anyone even notices
353 them. We generally go through the bug system when preparing for new
354 development releases, to see what fell through the cracks while we were
355 off writing new features. (It's a fast/unreliable vs slow/reliable thing.
356 Saves retransits, but the latency sucks.)
361 <h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</h2>
363 <p>Variants of this one get asked a lot.</p>
365 <p>The purpose of the BusyBox mailing list is to develop and improve BusyBox,
366 and we're happy to respond to our users' needs. But if you're coming to the
367 list for free tech support we're going to ask you to upgrade to a current
368 version before we try to diagnose your problem.</p>
370 <p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 0.9.26 there's a
371 fairly large chance that whatever problem you're seeing has already been fixed.
372 To get that fix, all you have to do is upgrade to a newer version. If you
373 don't at least _try_ that, you're wasting our time.</p>
375 <p>The volunteers are happy to fix any bugs you point out in the current
376 versions because doing so helps everybody and makes the project better. We
377 want to make the current version work for you. But diagnosing, debugging, and
378 backporting fixes to old versions isn't something we do for free, because it
379 doesn't help anybody but you. The cost of volunteer tech support is using a
380 reasonably current version of the project.</p>
382 <p>If you don't want to upgrade, you have the complete source code and thus
383 the ability to fix it yourself, or hire a consultant to do it for you. If you
384 got your version from a vendor who still supports the older version, they can
385 help you. But there are limits as to what the volunteers will feel obliged to
388 <p>As a rule of thumb, volunteers will generally answer polite questions about
389 a given version for about three years after its release before it's so old
390 we don't remember the answer off the top of our head. And if you want us to
391 put any _effort_ into tracking it down, we want you to put in a little effort
392 of your own by confirming it's still a problem with the current version. It's
393 also hard for us to fix a problem of yours if we can't reproduce it because
394 we don't have any systems running an environment that old.</p>
396 <p>A consultant will happily set up a special environment just to reproduce
397 your problem, and you can always ask on the list if any of the developers
398 have consulting rates.</p>
402 <h2><a name="init">Busybox init isn't working!</a></h2>
404 Init is the first program that runs, so it might be that no programs are
405 working on your new system because of a problem with your cross-compiler,
406 kernel, console settings, shared libraries, root filesystem... To rule all
407 that out, first build a statically linked version of the following "hello
408 world" program with your cross compiler toolchain:
411 #include <stdio.h>
413 int main(int argc, char *argv)
415 printf("Hello world!\n");
421 Now try to boot your device with an "init=" argument pointing to your
422 hello world program. Did you see the hello world message? Until you
423 do, don't bother messing with busybox init.
427 Once you've got it working statically linked, try getting it to work
428 dynamically linked. Then read the FAQ entry <a href="#build_system">How
429 do I build a BusyBox-based system?</a>, and the
430 <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox
436 <h2><a name="sed">I can't configure busybox on my system.</a></h2>
438 Configuring Busybox depends on a recent version of sed. Older
439 distributions (Red Hat 7.2, Debian 3.0) may not come with a
440 usable version. Luckily BusyBox can use its own sed to configure itself,
441 although this leads to a bit of a chicken and egg problem.
442 You can work around this by hand-configuring busybox to build with just
443 sed, then putting that sed in your path to configure the rest of busybox
448 tar xvjf sources/busybox-x.x.x.tar.bz2
451 make include/bb_config.h
452 echo "CONFIG_SED=y" >> .config
453 echo "#undef ENABLE_SED" >> include/bb_config.h
454 echo "#define ENABLE_SED 1" >> include/bb_config.h
457 export PATH=`pwd`:"$PATH"
460 <p>Then you can run "make defconfig" or "make menuconfig" normally.</p>
464 <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>
467 Job control will be turned off since your shell can not obtain a controlling
468 terminal. This typically happens when you run your shell on /dev/console.
469 The kernel will not provide a controlling terminal on the /dev/console
470 device. Your should run your shell on a normal tty such as tty1 or ttyS0
471 and everything will work perfectly. If you <em>REALLY</em> want your shell
472 to run on /dev/console, then you can hack your kernel (if you are into that
473 sortof thing) by changing drivers/char/tty_io.c to change the lines where
474 it sets "noctty = 1;" to instead set it to "0". I recommend you instead
475 run your shell on a real console...
480 <h2><b><a name="goals">What are the goals of busybox?</a></b></h2>
482 <p>Busybox aims to be the smallest and simplest correct implementation of the
483 standard Linux command line tools. First and foremost, this means the
484 smallest executable size we can manage. We also want to have the simplest
485 and cleanest implementation we can manage, be <a href="#standards">standards
486 compliant</a>, minimize run-time memory usage (heap and stack), run fast, and
487 take over the world.</p>
489 <h2><b><a name="design">What is the design of busybox?</a></b></h2>
491 <p>Busybox is like a swiss army knife: one thing with many functions.
492 The busybox executable can act like many different programs depending on
493 the name used to invoke it. Normal practice is to create a bunch of symlinks
494 pointing to the busybox binary, each of which triggers a different busybox
495 function. (See <a href="FAQ.html#getting_started">getting started</a> in the
496 FAQ for more information on usage, and <a href="BusyBox.html">the
497 busybox documentation</a> for a list of symlink names and what they do.)
499 <p>The "one binary to rule them all" approach is primarily for size reasons: a
500 single multi-purpose executable is smaller then many small files could be.
501 This way busybox only has one set of ELF headers, it can easily share code
502 between different apps even when statically linked, it has better packing
503 efficiency by avoding gaps between files or compression dictionary resets,
506 <p>Work is underway on new options such as "make standalone" to build separate
507 binaries for each applet, and a "libbb.so" to make the busybox common code
508 available as a shared library. Neither is ready yet at the time of this
511 <a name="source"></a>
513 <h2><a name="source_applets"><b>The applet directories</b></a></h2>
515 <p>The directory "applets" contains the busybox startup code (applets.c and
516 busybox.c), and several subdirectories containing the code for the individual
519 <p>Busybox execution starts with the main() function in applets/busybox.c,
520 which sets the global variable bb_applet_name to argv[0] and calls
521 run_applet_by_name() in applets/applets.c. That uses the applets[] array
522 (defined in include/busybox.h and filled out in include/applets.h) to
523 transfer control to the appropriate APPLET_main() function (such as
524 cat_main() or sed_main()). The individual applet takes it from there.</p>
526 <p>This is why calling busybox under a different name triggers different
527 functionality: main() looks up argv[0] in applets[] to get a function pointer
528 to APPLET_main().</p>
530 <p>Busybox applets may also be invoked through the multiplexor applet
531 "busybox" (see busybox_main() in applets/busybox.c), and through the
532 standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c).
533 See <a href="FAQ.html#getting_started">getting started</a> in the
534 FAQ for more information on these alternate usage mechanisms, which are
535 just different ways to reach the relevant APPLET_main() function.</p>
537 <p>The applet subdirectories (archival, console-tools, coreutils,
538 debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils,
539 modutils, networking, procps, shell, sysklogd, and util-linux) correspond
540 to the configuration sub-menus in menuconfig. Each subdirectory contains the
541 code to implement the applets in that sub-menu, as well as a Config.in
542 file defining that configuration sub-menu (with dependencies and help text
543 for each applet), and the makefile segment (Makefile.in) for that
546 <p>The run-time --help is stored in usage_messages[], which is initialized at
547 the start of applets/applets.c and gets its help text from usage.h. During the
548 build this help text is also used to generate the BusyBox documentation (in
549 html, txt, and man page formats) in the docs directory. See
550 <a href="#adding">adding an applet to busybox</a> for more
553 <h2><a name="source_libbb"><b>libbb</b></a></h2>
555 <p>Most non-setup code shared between busybox applets lives in the libbb
556 directory. It's a mess that evolved over the years without much auditing
557 or cleanup. For anybody looking for a great project to break into busybox
558 development with, documenting libbb would be both incredibly useful and good
561 <p>Common themes in libbb include allocation functions that test
562 for failure and abort the program with an error message so the caller doesn't
563 have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions
564 of open(), close(), read(), and write() that test for their own failures
565 and/or retry automatically, linked list management functions (llist.c),
566 command line argument parsing (getopt_ulflags.c), and a whole lot more.</p>
570 <h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2>
572 To conserve bytes it's good to know where they're being used, and the
573 size of the final executable isn't always a reliable indicator of
574 the size of the components (since various structures are rounded up,
575 so a small change may not even be visible by itself, but many small
579 <p> The busybox Makefile builds two versions of busybox, one of which
580 (busybox_unstripped) has extra information that various analysis tools
581 can use. (This has nothing to do with CONFIG_DEBUG, leave that off
582 when trying to optimize for size.)
585 <p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter
586 script to compare two versions of busybox (busybox_unstripped vs
587 busybox_old), and report which symbols changed size and by how much.
588 To use it, first build a base version with <b>"make baseline"</b>.
589 (This creates busybox_old, which should have the original sizes for
590 comparison purposes.) Then build the new version with your changes
591 and run "make bloatcheck" to see the size differences from the old
595 The first line of output has totals: how many symbols were added or
596 removed, how many symbols grew or shrank, the number of bytes added
597 and number of bytes removed by these changes, and finally the total
598 number of bytes difference between the two files. The remaining
599 lines show each individual symbol, the old and new sizes, and the
600 increase or decrease in size (which results are sorted by).
603 The <b>"make sizes"</b> option produces raw symbol size information for
604 busybox_unstripped. This is the output from the "nm --size-sort"
605 command (see "man nm" for more information), and is the information
606 bloat-o-meter parses to produce the comparison report above. For
607 defconfig, this is a good way to find the largest symbols in the tree
608 (which is a good place to start when trying to shrink the code). To
609 take a closer look at individual applets, configure busybox with just
610 one applet (run "make allnoconfig" and then switch on a single applet
611 with menuconfig), and then use "make sizes" to see the size of that
615 The "showasm" command (in the scripts directory) produces an assembly
616 dump of a function, providing a closer look at what changed. Try
617 "scripts/showasm busybox_unstripped" to list available symbols, and
618 "scripts/showasm busybox_unstripped symbolname" to see the assembly
619 for a sepecific symbol.
625 <h2><a name="adding"><b>Adding an applet to busybox</b></a></h2>
627 <p>To add a new applet to busybox, first pick a name for the applet and
628 a corresponding CONFIG_NAME. Then do this:</p>
631 <li>Figure out where in the busybox source tree your applet best fits,
632 and put your source code there. Be sure to use APPLET_main() instead
633 of main(), where APPLET is the name of your applet.</li>
635 <li>Add your applet to the relevant Config.in file (which file you add
636 it to determines where it shows up in "make menuconfig"). This uses
637 the same general format as the linux kernel's configuration system.</li>
639 <li>Add your applet to the relevant Makefile.in file (in the same
640 directory as the Config.in you chose), using the existing entries as a
641 template and the same CONFIG symbol as you used for Config.in. (Don't
642 forget "needlibm" or "needcrypt" if your applet needs libm or
645 <li>Add your applet to "include/applets.h", using one of the existing
646 entries as a template. (Note: this is in alphabetical order. Applets
647 are found via binary search, and if you add an applet out of order it
650 <li>Add your applet's runtime help text to "include/usage.h". You need
651 at least appname_trivial_usage (the minimal help text, always included
652 in the busybox binary when this applet is enabled) and appname_full_usage
653 (extra help text included in the busybox binary with
654 CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile.
655 The other two help entry types (appname_example_usage and
656 appname_notes_usage) are optional. They don't take up space in the binary,
657 but instead show up in the generated documentation (BusyBox.html,
658 BusyBox.txt, and the man page BusyBox.1).</li>
660 <li>Run menuconfig, switch your applet on, compile, test, and fix the
661 bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and
662 "allbareconfig" if relevant).</li>
666 <h2><a name="standards">What standards does busybox adhere to?</a></h2>
668 <p>The standard we're paying attention to is the "Shell and Utilities"
669 portion of the <a href="http://www.opengroup.org/onlinepubs/009695399/">Open
670 Group Base Standards</a> (also known as the Single Unix Specification version
671 3 or SUSv3). Note that paying attention isn't necessarily the same thing as
674 <p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor
675 commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is
676 driven by what real users actually need, not the fact the standard believes
677 we should implement ed or sccs. For size reasons, we're unlikely to include
678 much internationalization support beyond UTF-8, and on top of all that, our
679 configuration menu lets developers chop out features to produce smaller but
680 very non-standard utilities.</p>
682 <p>Also, Busybox is aimed primarily at Linux. Unix standards are interesting
683 because Linux tries to adhere to them, but portability to dozens of platforms
684 is only interesting in terms of offering a restricted feature set that works
685 everywhere, not growing dozens of platform-specific extensions. Busybox
686 should be portable to all hardware platforms Linux supports, and any other
687 similar operating systems that are easy to do and won't require much
690 <p>In practice, standards compliance tends to be a clean-up step once an
691 applet is otherwise finished. When polishing and testing a busybox applet,
692 we ensure we have at least the option of full standards compliance, or else
693 document where we (intentionally) fall short.</p>
695 <h2><a name="portability">Portability.</a></h2>
697 <p>Busybox is a Linux project, but that doesn't mean we don't have to worry
698 about portability. First of all, there are different hardware platforms,
699 different C library implementations, different versions of the kernel and
700 build toolchain... The file "include/platform.h" exists to centralize and
701 encapsulate various platform-specific things in one place, so most busybox
702 code doesn't have to care where it's running.</p>
704 <p>To start with, Linux runs on dozens of hardware platforms. We try to test
705 each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle
706 all of these, this isn't that hard.) This means we have to care about a number
707 of portability issues like endianness, word size, and alignment, all of which
708 belong in platform.h. That header handles conditional #includes and gives
709 us macros we can use in the rest of our code. At some point in the future
710 we might grow a platform.c, possibly even a platform subdirectory. As long
711 as the applets themselves don't have to care.</p>
713 <p>On a related note, we made the "default signedness of char varies" problem
714 go away by feeding the compiler -funsigned-char. This gives us consistent
715 behavior on all platforms, and defaults to 8-bit clean text processing (which
716 gets us halfway to UTF-8 support). NOMMU support is less easily separated
717 (see the tips section later in this document), but we're working on it.</p>
719 <p>Another type of portability is build environments: we unapologetically use
720 a number of gcc and glibc extensions (as does the Linux kernel), but these have
721 been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for
722 gcc, we take advantage of newer compiler optimizations to get the smallest
723 possible size, but we also regression test against an older build environment
724 using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a
725 2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest
726 build/deployment environment we still put any effort into maintaining. (If
727 anyone takes an interest in older kernels you're welcome to submit patches,
728 but the effort would probably be better spent
729 <a href="http://www.selenic.com/linux-tiny/">trimming
730 down the 2.6 kernel</a>.) Older gcc versions than that are uninteresting since
731 we now use c99 features, although
732 <a href="http://fabrice.bellard.free.fr/tcc/">tcc</a> might be worth a
735 <p>We also test busybox against the current release of uClibc. Older versions
736 of uClibc aren't very interesting (they were buggy, and uClibc wasn't really
737 usable as a general-purpose C library before version 0.9.26 anyway).</p>
739 <p>Other unix implementations are mostly uninteresting, since Linux binaries
740 have become the new standard for portable Unix programs. Specifically,
741 the ubiquity of Linux was cited as the main reason the Intel Binary
742 Compatability Standard 2 died, by the standards group organized to name a
743 successor to ibcs2: <a href="http://www.telly.org/86open/">the 86open
744 project</a>. That project disbanded in 1999 with the endorsement of an
745 existing standard: Linux ELF binaries. Since then, the major players at the
747 href=http://www-03.ibm.com/servers/aix/products/aixos/linux/index.html>AIX</a>, <a
748 href=http://www.sun.com/software/solaris/ds/linux_interop.jsp#3>Solaris</a>, and
749 <a href=http://www.onlamp.com/pub/a/bsd/2000/03/17/linuxapps.html>FreeBSD</a>)
750 have all either grown Linux support or folded.</p>
752 <p>The major exceptions are newcomer MacOS X, some embedded environments
753 (such as newlib+libgloss) which provide a posix environment but not a full
754 Linux environment, and environments like Cygwin that provide only partial Linux
755 emulation. Also, some embedded Linux systems run a Linux kernel but amputate
756 things like the /proc directory to save space.</p>
758 <p>Supporting these systems is largely a question of providing a clean subset
759 of BusyBox's functionality -- whichever applets can easily be made to
760 work in that environment. Annotating the configuration system to
761 indicate which applets require which prerequisites (such as procfs) is
762 also welcome. Other efforts to support these systems (swapping #include
763 files to build in different environments, adding adapter code to platform.h,
764 adding more extensive special-case supporting infrastructure such as mount's
765 legacy mtab support) are handled on a case-by-case basis. Support that can be
766 cleanly hidden in platform.h is reasonably attractive, and failing that
767 support that can be cleanly separated into a separate conditionally compiled
768 file is at least worth a look. Special-case code in the body of an applet is
769 something we're trying to avoid.</p>
771 <h2><a name="tips" />Programming tips and tricks.</a></h2>
773 <p>Various things busybox uses that aren't particularly well documented
776 <h2><a name="tips_encrypted_passwords">Encrypted Passwords</a></h2>
778 <p>Password fields in /etc/passwd and /etc/shadow are in a special format.
779 If the first character isn't '$', then it's an old DES style password. If
780 the first character is '$' then the password is actually three fields
781 separated by '$' characters:</p>
783 <b>$type$salt$encrypted_password</b>
786 <p>The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.</p>
788 <p>The "salt" is a bunch of ramdom characters (generally 8) the encryption
789 algorithm uses to perturb the password in a known and reproducible way (such
790 as by appending the random data to the unencrypted password, or combining
791 them with exclusive or). Salt is randomly generated when setting a password,
792 and then the same salt value is re-used when checking the password. (Salt is
793 thus stored unencrypted.)</p>
795 <p>The advantage of using salt is that the same cleartext password encrypted
796 with a different salt value produces a different encrypted value.
797 If each encrypted password uses a different salt value, an attacker is forced
798 to do the cryptographic math all over again for each password they want to
799 check. Without salt, they could simply produce a big dictionary of commonly
800 used passwords ahead of time, and look up each password in a stolen password
801 file to see if it's a known value. (Even if there are billions of possible
802 passwords in the dictionary, checking each one is just a binary search against
803 a file only a few gigabytes long.) With salt they can't even tell if two
804 different users share the same password without guessing what that password
805 is and decrypting it. They also can't precompute the attack dictionary for
806 a specific password until they know what the salt value is.</p>
808 <p>The third field is the encrypted password (plus the salt). For md5 this
811 <p>The busybox function to handle all this is pw_encrypt(clear, salt) in
812 "libbb/pw_encrypt.c". The first argument is the clear text password to be
813 encrypted, and the second is a string in "$type$salt$password" format, from
814 which the "type" and "salt" fields will be extracted to produce an encrypted
815 value. (Only the first two fields are needed, the third $ is equivalent to
816 the end of the string.) The return value is an encrypted password in
817 /etc/passwd format, with all three $ separated fields. It's stored in
818 a static buffer, 128 bytes long.</p>
820 <p>So when checking an existing password, if pw_encrypt(text,
821 old_encrypted_password) returns a string that compares identical to
822 old_encrypted_password, you've got the right password. When setting a new
823 password, generate a random 8 character salt string, put it in the right
824 format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the
825 second argument to pw_encrypt(text,buffer).</p>
827 <h2><a name="tips_vfork">Fork and vfork</a></h2>
829 <p>On systems that haven't got a Memory Management Unit, fork() is unreasonably
830 expensive to implement (and sometimes even impossible), so a less capable
831 function called vfork() is used instead. (Using vfork() on a system with an
832 MMU is like pounding a nail with a wrench. Not the best tool for the job, but
835 <p>Busybox hides the difference between fork() and vfork() in
836 libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec()
837 (which returns a pid and takes the same arguments as execve(), although in
838 this case envp can be NULL) and don't worry about it. This description is
839 here in case you want to know why that does what it does.</p>
841 <p>Implementing fork() depends on having a Memory Management Unit. With an
842 MMU then you can simply set up a second set of page tables and share the
843 physical memory via copy-on-write. So a fork() followed quickly by exec()
844 only copies a few pages of the parent's memory, just the ones it changes
845 before freeing them.</p>
847 <p>With a very primitive MMU (using a base pointer plus length instead of page
848 tables, which can provide virtual addresses and protect processes from each
849 other, but no copy on write) you can still implement fork. But it's
850 unreasonably expensive, because you have to copy all the parent process'
851 memory into the new process (which could easily be several megabytes per fork).
852 And you have to do this even though that memory gets freed again as soon as the
853 exec happens. (This is not just slow and a waste of space but causes memory
854 usage spikes that can easily cause the system to run out of memory.)</p>
856 <p>Without even a primitive MMU, you have no virtual addresses. Every process
857 can reach out and touch any other process' memory, because all pointers are to
858 physical addresses with no protection. Even if you copy a process' memory to
859 new physical addresses, all of its pointers point to the old objects in the
860 old process. (Searching through the new copy's memory for pointers and
861 redirect them to the new locations is not an easy problem.)</p>
863 <p>So with a primitive or missing MMU, fork() is just not a good idea.</p>
865 <p>In theory, vfork() is just a fork() that writeably shares the heap and stack
866 rather than copying it (so what one process writes the other one sees). In
867 practice, vfork() has to suspend the parent process until the child does exec,
868 at which point the parent wakes up and resumes by returning from the call to
869 vfork(). All modern kernel/libc combinations implement vfork() to put the
870 parent to sleep until the child does its exec. There's just no other way to
871 make it work: the parent has to know the child has done its exec() or exit()
872 before it's safe to return from the function it's in, so it has to block
873 until that happens. In fact without suspending the parent there's no way to
874 even store separate copies of the return value (the pid) from the vfork() call
875 itself: both assignments write into the same memory location.</p>
877 <p>One way to understand (and in fact implement) vfork() is this: imagine
878 the parent does a setjmp and then continues on (pretending to be the child)
879 until the exec() comes around, then the _exec_ does the actual fork, and the
880 parent does a longjmp back to the original vfork call and continues on from
881 there. (It thus becomes obvious why the child can't return, or modify
882 local variables it doesn't want the parent to see changed when it resumes.)
884 <p>Note a common mistake: the need for vfork doesn't mean you can't have two
885 processes running at the same time. It means you can't have two processes
886 sharing the same memory without stomping all over each other. As soon as
887 the child calls exec(), the parent resumes.</p>
889 <p>If the child's attempt to call exec() fails, the child should call _exit()
890 rather than a normal exit(). This avoids any atexit() code that might confuse
891 the parent. (The parent should never call _exit(), only a vforked child that
894 <p>(Now in theory, a nommu system could just copy the _stack_ when it forks
895 (which presumably is much shorter than the heap), and leave the heap shared.
896 Even with no MMU at all
897 In practice, you've just wound up in a multi-threaded situation and you can't
898 do a malloc() or free() on your heap without freeing the other process' memory
899 (and if you don't have the proper locking for being threaded, corrupting the
900 heap if both of you try to do it at the same time and wind up stomping on
901 each other while traversing the free memory lists). The thing about vfork is
902 that it's a big red flag warning "there be dragons here" rather than
903 something subtle and thus even more dangerous.)</p>
905 <h2><a name="tips_sort_read">Short reads and writes</a></h2>
907 <p>Busybox has special functions, bb_full_read() and bb_full_write(), to
908 check that all the data we asked for got read or written. Is this a real
909 world consideration? Try the following:</p>
911 <pre>while true; do echo hello; sleep 1; done | tee out.txt</pre>
913 <p>If tee is implemented with bb_full_read(), tee doesn't display output
914 in real time but blocks until its entire input buffer (generally a couple
915 kilobytes) is read, then displays it all at once. In that case, we _want_
916 the short read, for user interface reasons. (Note that read() should never
917 return 0 unless it has hit the end of input, and an attempt to write 0
918 bytes should be ignored by the OS.)</p>
920 <p>As for short writes, play around with two processes piping data to each
921 other on the command line (cat bigfile | gzip > out.gz) and suspend and
922 resume a few times (ctrl-z to suspend, "fg" to resume). The writer can
923 experience short writes, which are especially dangerous because if you don't
924 notice them you'll discard data. They can also happen when a system is under
925 load and a fast process is piping to a slower one. (Such as an xterm waiting
926 on x11 when the scheduler decides X is being a CPU hog with all that
927 text console scrolling...)</p>
929 <p>So will data always be read from the far end of a pipe at the
930 same chunk sizes it was written in? Nope. Don't rely on that. For one
931 counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896
932 for Nagle's algorithm</a>, which waits a fraction of a second or so before
933 sending out small amounts of data through a TCP/IP connection in case more
934 data comes in that can be merged into the same packet. (In case you were
935 wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency
936 on their their sockets, now you know.)</p>
938 <h2><a name="tips_memory">Memory used by relocatable code, PIC, and static linking.</a></h2>
940 <p>The downside of standard dynamic linking is that it results in self-modifying
941 code. Although each executable's pages are mmaped() into a process' address
942 space from the executable file and are thus naturally shared between processes
943 out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0)
944 writes to these pages to supply addresses for relocatable symbols. This
945 dirties the pages, triggering copy-on-write allocation of new memory for each
946 processes' dirtied pages.</p>
948 <p>One solution to this is Position Independent Code (PIC), a way of linking
949 a file so all the relocations are grouped together. This dirties fewer
950 pages (often just a single page) for each process' relocations. The down
951 side is this results in larger executables, which take up more space on disk
952 (and a correspondingly larger space in memory). But when many copies of the
953 same program are running, PIC dynamic linking trades a larger disk footprint
954 for a smaller memory footprint, by sharing more pages.</p>
956 <p>A third solution is static linking. A statically linked program has no
957 relocations, and thus the entire executable is shared between all running
958 instances. This tends to have a significantly larger disk footprint, but
959 on a system with only one or two executables, shared libraries aren't much
962 <p>You can tell the glibc linker to display debugging information about its
963 relocations with the environment variable "LD_DEBUG". Try
964 "LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret
965 "LD_DEBUG=statistics cat /proc/self/statm" could be interesting.</p>
967 <p>For more on this topic, here's Rich Felker:</p>
969 <p>Dynamic linking (without fixed load addresses) fundamentally requires
970 at least one dirty page per dso that uses symbols. Making calls (but
971 never taking the address explicitly) to functions within the same dso
972 does not require a dirty page by itself, but will with ELF unless you
973 use -Bsymbolic or hidden symbols when linking.</p>
975 <p>ELF uses significant additional stack space for the kernel to pass all
976 the ELF data structures to the newly created process image. These are
977 located above the argument list and environment. This normally adds 1
978 dirty page to the process size.</p>
980 <p>The ELF dynamic linker has its own data segment, adding one or more
981 dirty pages. I believe it also performs relocations on itself.</p>
983 <p>The ELF dynamic linker makes significant dynamic allocations to manage
984 the global symbol table and the loaded dso's. This data is never
985 freed. It will be needed again if libdl is used, so unconditionally
986 freeing it is not possible, but normal programs do not use libdl. Of
987 course with glibc all programs use libdl (due to nsswitch) so the
988 issue was never addressed.</p>
990 <p>ELF also has the issue that segments are not page-aligned on disk.
991 This saves up to 4k on disk, but at the expense of using an additional
992 dirty page in most cases, due to a large portion of the first data
993 page being filled with a duplicate copy of the last text page.</p>
995 <p>The above is just a partial list of the tiny memory penalties of ELF
996 dynamic linking, which eventually add up to quite a bit. The smallest
997 I've been able to get a process down to is 8 dirty pages, and the
998 above factors seem to mostly account for it (but some were difficult
1002 <h2><a name="tips_kernel_headers"></a>Including kernel headers</h2>
1004 <p>The "linux" or "asm" directories of /usr/include contain Linux kernel
1005 headers, so that the C library can talk directly to the Linux kernel. In
1006 a perfect world, applications shouldn't include these headers directly, but
1007 we don't live in a perfect world.</p>
1009 <p>For example, Busybox's losetup code wants linux/loop.c because nothing else
1010 #defines the structures to call the kernel's loopback device setup ioctls.
1011 Attempts to cut and paste the information into a local busybox header file
1012 proved incredibly painful, because portions of the loop_info structure vary by
1013 architecture, namely the type __kernel_dev_t has different sizes on alpha,
1014 arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or
1015 we hardwire #ifdefs to check what platform we're building on and define this
1016 type appropriately for every single hardware architecture supported by
1017 Linux, which is simply unworkable.</p>
1019 <p>This is aside from the fact that the relevant type defined in
1020 posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so
1021 to cut and paste the structure into our header we have to #include
1022 <linux/version.h> to figure out which name to use. (What we actually do is
1023 check if we're building on 2.6, and if so just use the new 64 bit structure
1024 instead to avoid the rename entirely.) But we still need the version
1025 check, since 2.4 didn't have the 64 bit structure.</p>
1027 <p>The BusyBox developers spent <u>two years</u> trying to figure
1028 out a clean way to do all this. There isn't one. The losetup in the
1029 util-linux package from kernel.org isn't doing it cleanly either, they just
1030 hide the ugliness by nesting #include files. Their mount/loop.h
1031 #includes "my_dev_t.h", which #includes <linux/posix_types.h> and
1032 <linux/version.h> just like we do. There simply is no alternative.</p>
1034 <p>Just because directly #including kernel headers is sometimes
1035 unavoidable doesn't me we should include them when there's a better
1036 way to do it. However, block copying information out of the kernel headers
1037 is not a better way.</p>
1039 <h2><a name="who">Who are the BusyBox developers?</a></h2>
1041 <p>The following login accounts currently exist on busybox.net. (I.E. these
1042 people can commit <a href="http://busybox.net/downloads/patches">patches</a>
1043 into subversion for the BusyBox, uClibc, and buildroot projects.)</p>
1046 aldot :Bernhard Fischer
1047 andersen :Erik Andersen <- uClibc and BuildRoot maintainer.
1049 davidm :David McCullough
1050 gkajmowi :Garrett Kajmowicz <- uClibc++ maintainer
1051 jbglaw :Jan-Benedict Glaw
1052 jocke :Joakim Tjernlund
1053 landley :Rob Landley <- BusyBox maintainer
1055 mjn3 :Manuel Novoa III
1058 pkj :Peter Kjellerstedt
1059 prpplague :David Anders
1060 psm :Peter S. Mazinger
1062 sandman :Robert Griebl
1063 sjhill :Steven J. Hill
1066 tobiasa :Tobias Anderberg
1067 vapier :Mike Frysinger
1070 <p>The following accounts used to exist on busybox.net, but don't anymore so
1071 I can't ask /etc/passwd for their names. (If anybody would like to make
1072 a stab at it...)</p>
1078 erik : Also Erik Andersen?
1087 vodz :Vladimir N. Oleynik
1095 <!--#include file="footer.html" -->