# Multi-call binaries

Like BusyBox, ToyBox, all of the rescue(8) utilities in FreeBSD and NetBSD, and many other tools for Linux-based operating systems and Unices; the programs in the nosh toolset are multi-call binaries whose behaviour is dictated by the command name (the "zeroth argument") they are invoked by. They are not, however, all one big single multi-call binary. Moreover, sometimes a binary is hard-linked to a particular command name, and sometimes it is a symbolic link.

## "Built-in" commands

As the `exec` manual page states, the chain loading tools can chain directly to each other, without going through the operating system. They are "built-in" commands that are always accessible. This ability is subject to two conditions. The chained-from and chained-to commands must be within a single multi-call binary, and the chained-to command must be invoked without any pathname prefix (neither relative nor absolute) to the command name.

Most of the commands that will be used in the construction of the `start`, `run`, `restart`, and `stop` scripts, are collected together into one single multi-call binary and in a regular service these scripts invoke the successive commands by their bare names. This results in a single script internally chaining from one command to the next without calling the operating system's `execve()` function to overlay a new process image file at every step in the chain. This is a benefit because the work done by most of the commands that affect process state is far outweighed by the runtime library re-initializing a fresh program image just to execute the handful of system calls that are the core of the command.

For example: The `umask` command only needs to make one system call to do its actual job, but will nonetheless do all of the runtime library's setup and teardown of the stack, heap, thread, and signal management in order to just make that one system call in the middle. Accessed as a "built-in" chain-loading command, it does none of the setup and teardown, but simply transfers internally from the previous and to the next "built-in" command in the chain.

### Special "built-in" commands

There are two special, undocumented, built-in commands that are not exposed directly as names in the filesystem one can simply invoke the programs by. The are `version` and `builtins`, reporting the (toolset) version information of the binary and what built-in commands it contains. As of version 1.41 of the toolset, you are encouraged to use the standard Unix `what` utility because a proper version identification string for that utility to recognize is now embedded into the binaries.

## Multiple binaries

Nonetheless, the commands in the toolset are not all collected into one single binary with every command.

The commands that use the ncurses library (principally `console-ncurses-realizer` are separated out into their own binary. This means that most commands will not dynamically load the ncurses shared library.

The `system-manager` is in its own executable, with the few commands that it invokes as direct sub-processes (e.g. `system-control`, `service-manager`, `cyclog`, and control groups commands) being "built-in" with it. Likewise, the `emergency-login` command is in its own executable. Both, as well, have copies installed into `/sbin` and `/bin`. See emergency startup mode for the reasons behind this.

## Links and symbolic links for commands

When built from source, slashpackage-style, everything in the `command/` directory is a normal (hard) link to a multi-call binary. No symbolic links are used. The `command/` directory has no concerns over possibly clashing with names from other toolsets, or with system programs. That is one of the fundamental aspects of the slashpackage design.

However, the binary packages, if one builds them, place files into places on the `PATH` such as `/usr/local/sbin`, `/usr/local/bin`, `/usr/pkg/sbin`, and `/usr/pkg/bin`; and thus are sensitive to clashes with names used by other packages and toolsets — especially the packages that explicitly install shim workalikes for other toolsets and for the system commands from various (usually foreign) operating systems. The shim workalike names are left out of the main binaries installation packages. To eliminate the need for the shim-providing packages to carry separate copies of the multi-call binaries, and because operating system package installation systems are not broadly good with hard linking to things outwith a package's own manifest, the shims packages install the shims as symbolic links to the multi-call binaries installed by the main packages where the commands exist, but unexposed as filenames.

Note: Operating systems may choose to package things differently. But out of the box, if one builds from source using the toolset-supplied package-building procedures, there are three main binaries packages (exec, system management, and terminal management), and several shim packages (for, amongst others, Debian, OpenRC, OpenBSD, FreeBSD, GNU coreutils, util-linux, Upstart, SunOS/Illumos SMF, and net-tools).

## Shared library mis-locations

The `system-manager` and `emergency-login` executables are statically linked on FreeBSD. This is because FreeBSD (up to and including version 14) puts the clang libc++ runtime library in `/usr/lib` (even though various parts of base are written in C++ and the C library is in `/lib`), and the clang libc++ runtime library still depends from the GNU C runtime library `libgcc_s.so` (instead of clang's own `libcxxrt.so` — a known bug filed in 2021 and mentioned for FreeBSD as long ago as 2018) which FreeBSD puts in `/usr/local/lib`.

Both of these need to be in `/lib` for `system-manager` and `emergency-login` to be dynamically linkable on a machine bootstrapped into emergency mode when the disc volume containing `/usr` may not be mounted. Although the standard configuration for root-on-ZFS has, since the time of PC-BSD, been to have `/usr/lib` and `/usr/local/lib` on the root ZFS filesystem, with no separate `/usr` mount point, bootstrapping from UFS does not have this convention ab initio (it having quite the opposite one, in fact) and one cannot assume that mounting (solely) the root volume always makes `/usr/lib` and `/usr/local/lib` available.