PREV_LEC NEXT_LEC

What You Will Learn

• Why embedded root filesystems avoid one binary per command
• How a multi-call binary decides which applet to run using argv[0]
• How to build a tiny multi-call binary yourself as a teaching example
• How to cross-compile and install BusyBox for a target board
• What ToyBox is, and when it is the better choice over BusyBox
• Common mistakes when wiring up applet symlinks

Prerequisites

• A working cross toolchain (see our free embedded linux course toolchain chapter)
• A staging root filesystem directory, as covered in earlier elch5 lectures
• Basic familiarity with argv, symbolic links, and Kconfig/Kbuild

The Problem: One Binary Per Command Does Not Scale

A desktop Linux distribution ships ls, cp, mv, grep, sed, and hundreds of other tools as separate ELF executables. Each of those binaries pulls in its own copy of the C runtime startup code, its own symbol table, its own ELF headers, and often duplicated logic for argument parsing. On a desktop with hundreds of gigabytes of storage this waste is invisible. On an embedded target with 8 MiB or 16 MiB of flash, it is not something you can ignore.

The insight that solves this is simple: most of these small utilities do not need their own separate program. They need their own separate entry point. If one binary can behave differently depending on how it was invoked, you only pay the ELF-header and startup-code cost once, and every applet after that is just a few hundred bytes of object code linked into the same executable.

How a Multi-Call Binary Decides What To Do

Every C program receives its own invocation name as argv[0]. Normally your code ignores this value entirely. A multi-call binary does the opposite: it inspects argv[0] first, strips off the directory portion, and uses the remaining basename as a lookup key into a table of function pointers. If the basename matches ls, it jumps straight into the internal ls implementation. If it matches grep, it jumps into the internal grep implementation. The trick that makes this useful in practice is that you never actually type the multi-call binary’s real name — you invoke it through a symbolic link named after the applet, and the kernel passes that symlink name through as argv[0] automatically.

Building a Minimal Multi-Call Binary Yourself

Before looking at BusyBox’s actual applet table, it helps enormously to build a toy version yourself. Below is an original, minimal multi-call program, ep_multicall, that implements just two applets, ep_hello and ep_uptime_words, purely to demonstrate the dispatch mechanism. It is intentionally simple and is not meant to replace real coreutils.

/* ep_multicall.c - minimal multi-call binary demo for EmbeddedPathashala */
#include <stdio.h>
#include <string.h>
#include <libgen.h>

static int applet_hello(int argc, char **argv)
{
    printf("ep_hello: hello from the multi-call binary!\n");
    return 0;
}

static int applet_uptime_words(int argc, char **argv)
{
    printf("ep_uptime_words: system has been up for a while.\n");
    return 0;
}

struct applet {
    const char *name;
    int (*func)(int, char **);
};

static const struct applet applet_table[] = {
    { "ep_hello",         applet_hello },
    { "ep_uptime_words",  applet_uptime_words },
    { NULL, NULL }
};

int main(int argc, char **argv)
{
    char argv0_copy[256];
    strncpy(argv0_copy, argv[0], sizeof(argv0_copy) - 1);
    argv0_copy[sizeof(argv0_copy) - 1] = '\0';

    const char *name = basename(argv0_copy);

    for (int i = 0; applet_table[i].name != NULL; i++) {
        if (strcmp(name, applet_table[i].name) == 0) {
            return applet_table[i].func(argc, argv);
        }
    }

    fprintf(stderr, "ep_multicall: unknown applet '%s'\n", name);
    return 1;
}

Build it, then create symlinks named after each applet, exactly the same way BusyBox does it under the hood:

$ gcc -o ep_multicall ep_multicall.c
$ ln -s ep_multicall ep_hello
$ ln -s ep_multicall ep_uptime_words
$ ./ep_hello
ep_hello: hello from the multi-call binary!
$ ./ep_uptime_words
ep_uptime_words: system has been up for a while.
$ ls -l ep_multicall ep_hello ep_uptime_words
-rwxr-xr-x 1 ravi ravi 16744 Aug 13 10:00 ep_multicall
lrwxrwxrwx 1 ravi ravi     11 Aug 13 10:00 ep_hello -> ep_multicall
lrwxrwxrwx 1 ravi ravi     11 Aug 13 10:00 ep_uptime_words -> ep_multicall

Notice that ep_hello and ep_uptime_words are not separate programs at all — they are the same inode, reached through different names. This is exactly the mechanism BusyBox and ToyBox use, just scaled up to hundreds of applets with a generated dispatch table instead of a hand-written one.

Building BusyBox for Your Target

BusyBox reuses the kernel’s own Kconfig and Kbuild infrastructure, so if you have cross-compiled a kernel before, the workflow will feel familiar. Start by fetching a recent stable release and picking a starting configuration:

$ git clone https://github.com/mirror/busybox.git
$ cd busybox
$ git checkout 1_36_1
$ make distclean
$ make defconfig

The default configuration enables nearly every applet BusyBox supports, which is a good starting point but usually larger than you need. Run make menuconfig to trim applets you will never use on your target, and while you are in the configuration menu, set the install path under Busybox Settings → Installation Options (the CONFIG_PREFIX option) to point at your staging root filesystem directory rather than your host’s real /. Then cross-compile:

$ make -j$(nproc) ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- 
$ make install

make install copies the single BusyBox executable into your staging directory and, crucially, creates every applet symlink for you automatically, following the exact dispatch scheme demonstrated above. You can confirm the applet table with:

$ ./busybox --list | head
[
[[
acpid
addgroup
adduser
adjtimex
ar
arp
arping

ToyBox: A BSD-Licensed Alternative

ToyBox, started by Rob Landley, solves the exact same multi-call problem but makes different design tradeoffs worth knowing before you choose one for a project.

The license is usually the deciding factor. If your product’s userspace must stay free of GPL-licensed code for legal reasons — a common requirement in some Android-derived stacks — ToyBox is the natural fit. If you simply want the largest applet coverage and the most battle-tested defaults for a general-purpose embedded Linux image, BusyBox remains the default choice for most teams taking this free linux device drivers course path into full system integration.

Real-World Use Cases

• Minimal initramfs images that only need a shell and a handful of recovery tools
• Router and gateway firmware (OpenWrt and similar projects build on BusyBox)
• Android’s base userspace tools, historically built on a Toolbox/ToyBox lineage
• Container base images where every megabyte of image size has a real cost

Common Mistakes and Troubleshooting

• Forgetting to set CONFIG_PREFIX: running make install without pointing it at your staging directory will try to install into your host’s real /, which is dangerous and wrong.
• Missing PID 1 support: if you intend to use BusyBox’s init applet as your system’s init process, double-check it is enabled in your config — it is not always on by default.
• Broken symlinks after copying: use cp -a, not plain cp, when moving a BusyBox install tree, or the applet symlinks will be replaced with duplicate binaries and your size savings disappear.
• Static vs dynamic linking confusion: a statically linked BusyBox has no library dependencies to manage at all, at the cost of a larger single binary; weigh this against the shared-library approach covered in the next lecture.

Best Practices

• Start from defconfig, then prune applets you genuinely do not need rather than building minimal from scratch
• Keep a single source of truth for your BusyBox .config in version control alongside your board support package
• Prefer the mirror or the official BusyBox git tree pinned to a specific stable tag, never a floating branch, for reproducible builds
• Document which applets are relied upon by your init scripts so a future config change does not silently break boot

Performance Considerations

Because every applet shares one process image already resident in the page cache after first use, a multi-call binary can actually have a startup-latency advantage over many small binaries on flash-backed storage, since only one file needs to be paged in regardless of how many different commands your init scripts invoke.

Security Considerations

A single multi-call binary is also a single point of compromise: a vulnerability in the dispatch logic or in any one applet’s parsing code can potentially affect every applet reachable through it. Keep BusyBox or ToyBox updated to a current stable release, and only enable applets you actually ship, since unused code is unused attack surface.

Summary and Key Takeaways

• A multi-call binary uses argv[0] to decide which applet to run, avoiding duplicated startup code
• BusyBox and ToyBox both implement this pattern, differing mainly in license and standards focus
• BusyBox reuses Kconfig/Kbuild, making cross-compilation familiar to kernel builders
• make install with the right CONFIG_PREFIX creates all applet symlinks automatically

Conclusion

Understanding the multi-call binary pattern is one of those small pieces of knowledge that pays off across an entire embedded Linux career: once you have written your own tiny ep_multicall demo, BusyBox’s internals stop being a black box and become an obviously scaled-up version of something you already understand. Whether you end up choosing BusyBox for its breadth or ToyBox for its licensing, the mental model is identical, and that model is what actually matters for this free linux kernel development course track.

FAQ

PREV_LEC NEXT_LEC