Getting to know the Unix Compatibility Subsystem (kLIBC)

Wikis > ArcaOS > Compatibility Subsystems > Getting to know the Unix Compatibility Subsystem (kLIBC)

As mentioned here, ArcaOS includes a robust Unix Compatibility Subsystem provided by the kLIBC environment. Ported Linux and Unix applications run natively from the OS/2 command line, and new programs are being built continuously. This environment offers some of the best of the Unix world to ArcaOS users without the need to learn everything about Unix or Linux (or boot to another operating system) to take advantage of this software. This page should serve as an introduction to how this subsystem fits into ArcaOS and how to get the most from it.

Filesystem layout

The kLIBC environment in ArcaOS is installed under the root of a selected volume. For the single volume installation type, this will be the boot volume; for multi-volume installation types, this may either be the boot (system) volume or another, possibly dedicated, one. In the OS/2 environment, this volume is identified through the use of the %UNIXROOT% environment variable. So, for a single volume installation, where C: is the boot (or system) volume, %UNIXROOT% will be set to C:.

Note: While it is possible to designate a subdirectory as %UNIXROOT%, this is not recommended, and ArcaOS will only install the Unix subsystem to the root of the selected volume.

Under the root, the following directories constitute the basic layout of this subsystem:


This is a greatly reduced directory tree, but should provide some example as to the basic layout, which provides a subset of the Filesystem Hierarchy Standard (FHS), as discussed here. Note that there are other directories used in ArcaOS (\home, for example) which may also be discussed in the FHS, but as these directories are created outside the kLIBC installation process and used by ArcaOS instead of – or in addition to – the kLIBC environment, they have been omitted from the above images for brevity.

Optional directories

It is generally useful – and advisable – to create a local subdirectory tree under \usr (e.g., \usr\local\bin, \usr\local\lib, etc.) to use for applications and libraries which are not installed or managed by the package manager. Further, it is advisable to place \usr\local\lib ahead of \usr\lib in %LIBPATH% and \usr\local\bin ahead of \usr\bin in %PATH% to provide a preference for these manually-installed applications and libraries over any which may be installed by the package manager. The ArcaOS installer inserts these entries in CONFIG.SYS, leaving the creation of the local subdirectory tree to the user.

Note: If your %UNIXROOT% volume is JFS and was created with JFS version 1.09.07 or earlier and has not been updated to use os2boot 1.09.08 (shipped with ArcaOS 5.0.6) or later, do not simply create (or recreate) \usr\local directories and leave them empty, as this can cause a failure to boot. JFS volumes created with JFS version 1.09.08 or later do not have this problem. (For more details see the section entitled IPE when an empty directory is encountered during boot on the JFS wiki page.)

Some diagnostic utilities may warn about empty directories in %LIBPATH%. Generally, such warnings may be safely ignored for the \usr\local directories, subject to the note above.

For more on the local directory hierarchy, see here and here.

Filesystem features

Drive letters

OS/2 uses drive letters to identify disk or optical drives, partitions, or volumes. In contrast, Unix and Linux employ a unified filesystem, where different devices appear physically under the /dev directory tree and are then mounted (logically attached) to the filesystem anywhere the user has rights to add a directory (generally speaking). Ported applications running in the kLIBC environment generally do recognize drive letters (the “:”, which is used in Linux as a variable separator serves no such function in the kLIBC environment, and is free to be used for this purpose). For those applications which do not properly understand drive letters, s, ArcaOS includes the kLIBC Path Remapper, a graphical tool for mapping drive letters and paths into the kLIBC environment. For more information on this utility, access the program help. The kLIBC Path Remapper is located in the System Setup folder.

Path separator

Unix and Linux typically use a slash (/) as the path (directory) separator, whereas OS/2 (and ArcaOS, by extension) utilize the DOS-compliant backslash (\). Most ported Linux applications are able to utilize the backslash as a path separator, but not all. In some cases, an application which is itself perfectly capable of utilizing backslashes may itself require another application which is not. This can lead to unexpected results. Adding further confusion to the backslash issue is that most Unix and Linux applications (and shells) use the backslash as an escape character. This may require the use of slashes in pathnames in order to avoid confusion when needing to escape a special character in a command.

Case sensitivity vs case retention

Unix and Linux are case-sensitive operating systems. Thus, to a Linux system, the program names less and LESS are two entirely different applications, and both may exist in the same directory without conflicting. OS/2 (and ArcaOS, by extension) is case-retentive, but not case-sensitive. One may enter l-e-s-s (lower case) and whether the program executable is stored as less.exe or LESS.EXE, whichever is found first in %PATH% will be executed. less.exe and LESS.EXE may not coexist within the same directory, either, but copying less.exe from one directory to another as LESS.EXE will cause the uppercase name to be used for the copy (case retention).

Most ported Linux applications are case-insensitive when run in the kLIBC environment. We say “most” because some may have been compiled with earlier compiler applications or use libraries which are indeed case-sensitive. There is no way of knowing except to bear in mind that newer versions (recent additions to the software repositories) should be case-insensitive, whereas older applications, typically those installed manually (i.e., to the local directory hierarchy) may not be.


Unix and Linux are able to create aliases in one part of the filesystem which stand in for files or directories in another. Links are essentially just pointers. A link may be named identically to its target, or it may have a completely different name. It is not uncommon for a link to have a more generic name, pointing to a more specific target, e.g., /etc/alternatives/java may be a link whose target is really the executable /usr/lib/jvm/jre-1.6.0-openjdk/bin/java. A program update, creating a new directory for the updated binary and removing the original directory only requires an update to the link, and all applications configured to look there for the component will instantly be directed to the (new) target.

Links come in two basic varieties:

  • hard links
  • soft (symbolic) links

A hard link creates a link to the original file’s inode in the filesystem. This restricts hard links to the same physical filesystem (device) and disallows the creation of a hard link to a directory (hard links may only be used for targets which are files). Deleting the target file does not invalidate the hard link. Instead, the original file name is removed from its location. As the hard link points to the file’s inode and the data contained in the inode persists, the hard link is still a valid file.

A soft, or symbolic, link (commonly referred to as a symlink) creates a link to the target’s name in the filesystem. As such, symlinks may traverse physical filesystems (it is possible to create a symlink on the local hard drive pointing to a file on an inserted USB device). Symlinks may be used to point to directories as well as files. However, because the link is only to the target’s name, deleting the original file or directory invalidates the link.

In the kLIBC environment in ArcaOS, only soft links are possible. Thus, all links must be created using ln with the “-s” option. A symlink is implemented by creating a small text file in the directory where the link is located that contains the path to the target file, and then marking that file as a symlink file by creating a special extended attribute (EA) attached to that file. To any ordinary (non-kLIBC) OS/2 program, the symlink file looks just like an ordinary text file. In the kLIBC environment, however, it is a link to a different target file. It is important to remember not to strip the SYMLINK EA off of a symlink file or you will break the symlink functionality. Without the SYMLINK EA, the file will look like a regular text file even to kLIBC-compiled programs instead of linking to the target file.

Symlinks are particularly important in the kLIBC environment to applications which expect to call other binary files where those filenames do not include extensions. (Unix and Linux systems do not use filename extensions such as “.exe” or “.com” to denote executable files, and instead rely on filesystem attributes for this information. Thus, having no need for such extensions, many applications are hard-coded to load these other files simply by name, and by adding an extension – as would normally be the case for OS/2 executable files – these files would not be found, causing the calling application to fail.)

Symlinks may be used for user-created files, as well, however, it is important to note what has already been said: to any ordinary (non-kLIBC) OS/2 program, the symlink file looks just like an ordinary text file. Thus, a kLIBC-compiled word processor may be perfectly happy accessing a document which is the target of a symlink, but a different word processor may instead simply open the symlink file itself.

This entry last updated: by Lewis Rosenthal