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