source: MondoRescue/branches/stable/mindi-busybox/docs/busybox.net/FAQ.html @ 1770

Last change on this file since 1770 was 1770, checked in by Bruno Cornec, 12 years ago
  • Better output for mindi-busybox revision
  • Remove dummy file created on NFS - report from Arnaud Tiger <arnaud.tiger_at_hp.com>
  • strace useful for debug
  • fix new versions for pb (2.0.0 for mindi and 1.7.2 for mindi-busybox)
  • fix build process for mindi-busybox + options used in that version (dd for label-partitions-as-necessary)
  • fix typo in label-partitions-as-necessary which doesn't seem to work
  • Update to busybox 1.7.2
  • perl is now required at restore time to support uuid swap partitions (and will be used for many other thigs

in the future for sure)

  • next mindi version will be 2.0.0 due to all the changes made in it (udev may break working distros)
  • small optimization in mindi on keyboard handling (one single find instead of multiple)
  • better interaction for USB device when launching mindi manually
  • attempt to automatically guess block disk size for ramdisk
  • fix typos in bkphw
  • Fix the remaining problem with UUID support for swap partitions
  • Updates mondoarchive man page for USB support
  • Adds preliminary Hardware support to mindi (Proliant SSSTK)
  • Tries to add udev support also for rhel4
  • Fix UUID support which was still broken.
  • Be conservative in test for the start-nfs script
  • Update config file for mindi-busybox for 1.7.2 migration
  • Try to run around a busybox bug (1.2.2 pb on inexistant links)
  • Add build content for mindi-busybox in pb
  • Remove distributions content for mindi-busybox
  • Fix a warning on inexistant raidtab
  • Solve problem on tmpfs in restore init (Problem of inexistant symlink and busybox)
  • Create MONDO_CACHE and use it everywhere + creation at start
  • Really never try to eject a USB device
  • Fix a issue with &> usage (replaced with 1> and 2>)
  • Adds magic file to depllist in order to have file working + ldd which helps for debugging issues
  • tty modes correct to avoid sh error messages
  • Use ext3 normally and not ext2 instead
  • USB device should be corrected after reading (take 1st part)
  • Adds a mount_USB_here function derived from mount_CDROM_here
  • usb detection place before /dev detection in device name at restore time
  • Fix when restoring from USB: media is asked in interactive mode
  • Adds USB support for mondorestore
  • mount_cdrom => mount_media
  • elilo.efi is now searched throughout /boot/efi and not in a fixed place as there is no standard
  • untar-and-softlink => untar (+ interface change)
  • suppress useless softlinks creation/removal in boot process
  • avoids udevd messages on groups
  • Increase # of disks to 99 as in mindi at restore time (should be a conf file parameter)
  • skip existing big file creation
  • seems to work correctly for USB mindi boot
  • Adds group and tty link to udev conf
  • Always load usb-torage (even 2.6) to initiate USB bus discovery
  • Better printing of messages
  • Attempt to fix a bug in supporting OpenSusE 10.3 kernel for initramfs (mindi may now use multiple regex for kernel initrd detection)
  • Links were not correctly done as non relative for modules in mindi
  • exclusion of modules denied now works
  • Also create modules in their ordinary place, so that classical modprobe works + copy modules.dep
  • Fix bugs for DENY_MODS handling
  • Add device /dev/console for udev
  • ide-generic should now really be excluded
  • Fix a bug in major number for tty
  • If udev then adds modprobe/insmod to rootfs
  • tty0 is also cretaed with udev
  • ide-generic put rather in DENY_MODS
  • udevd remove from deplist s handled in mindi directly
  • better default for mindi when using --usb
  • Handles dynamically linked busybox (in case we want to use it soon ;-)
  • Adds fixed devices to create for udev
  • ide-generic should not be part of the initrd when using libata v2
  • support a dynamically linked udev (case on Ubuntu 7.10 and Mandriva 2008.0 so should be quite generic) This will give incitation to move to dyn. linked binaries in the initrd which will help for other tasks (ia6 4)
  • Improvement in udev support (do not use cl options not available in busybox)
  • Udev in mindi
    • auto creation of the right links at boot time with udev-links.conf(from Mandriva 2008.0)
    • rework startup of udev as current makes kernel crash (from Mandriva 2008.0)
    • add support for 64 bits udev
  • Try to render MyInsmod? silent at boot time
  • Adds udev support (mandatory for newest distributions to avoid remapping of devices in a different way as on the original system)
  • We also need vaft format support for USB boot
  • Adds libusual support (Ubuntu 7.10 needs it for USB)
  • Improve Ubuntu/Debian? keyboard detection and support
  • pbinit adapted to new pb (0.8.10). Filtering of docs done in it
  • Suppress some mondo warnings and errors on USB again
  • Tries to fix lack of files in deb mindi package
  • Verify should now work for USB devices
  • More log/mesages improvement for USB support
  • - Supress g_erase_tmpdir_and_scratchdir
  • Improve some log messages for USB support
  • Try to improve install in mindi to avoid issues with isolinux.cfg not installed vene if in the pkg :-(
  • Improve mindi-busybox build
  • In conformity with pb 0.8.9
  • Add support for Ubuntu 7.10 in build process
  • Add USB Key button to Menu UI (CD streamer removed)
  • Attempt to fix error messages on tmp/scratch files at the end by removing those dir at the latest possible.
  • Fix a bug linked to the size of the -E param which could be used (Arnaud Tiger/René? Ribaud).
  • Integrate ~/.pbrc content into mondorescue.pb (required project-builder >= 0.8.7)
  • Put mondorescue in conformity with new pb filtering rules
  • Add USB support at restore time (no test done yet). New start-usb script PB varibale added where useful
  • Unmounting USB device before removal of temporary scratchdir
  • Stil refining USB copy back to mondo (one command was not executed)
  • No need to have the image subdor in the csratchdir when USB.
  • umount the USB partition before attempting to use it
  • Remove useless copy from mindi to mondo at end of USB handling

(risky merge, we are raising the limits of 2 diverging branches. The status of stable is not completely sure as such. Will need lots of tests, but it's not yet done :-()
(merge -r1692:1769 $SVN_M/branches/2.2.5)

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