Chapter 1 Introducing the Binary Compatibility Packages

What the Binary Compatibility Packages Are

The Solaris 2.x and OpenWindows Binary Compatibility Packages are optional packages available with the Solaris 2.x release. They allow existing SunOS 4.x applications, including OpenWindows applications, to run on the Solaris 2.x release without modification or recompilation. It handles most binary interface discrepancies between the two releases transparently, providing an operating environment where SunOS 4.x applications can run properly.

Why the Binary Compatibility Packages Are Provided

These packages are only transition tools. They are intended for end-user environments, and allow existing SunOS 4.x binaries to run on the Solaris 2.x release. These packages are not provided as a development environment. All Solaris 2.x user application development should be done using the base Solaris 2.x environment.

Installing the Binary Compatibility Packages

These packages are optionally installable and require that the Source Compatibility Package also be installed. The SunOS Binary Compatibility Package is called SUNWbcp and the Open Windows Binary Compatibility Package is called SUNWowbcp.

See the Solaris Advanced Installation Guide or x86: Installing Solaris Software for details on installing optional packages and the Source Compatibility Guide for details on the Source Compatibility Package.

If you customize your software installation, and want to use the binary compatibility packages, you must make sure you install both compatibility packages.

Using the Binary Compatibility Package

The binary compatibility packages are invoked automatically and transparently when running a SunOS 4.x application. You do not need to alter your application.

All Solaris 2.x releases support SunOS 4.x dynamically linked executables. From Solaris 2.3 onwards, statically linked executables can also be run. From Solaris 2.5 onward mixed static and dynamically linked executables are supported.

Some of the many differences between the SunOS 4.x and Solaris 2.x releases involve the location of commands and other interfaces. Because of these differences, the definition of your PATH environment variable affects how your applications run with the binary compatibility packages. The following section explains this in detail.

Resolving Path Names

There are two problems in resolving path names. First, an object may reside in a different place in this release than it did in the SunOS 4.x release. For example, a command found in /usr/bin in the SunOS 4.x release may be in /usr/ucb in the Solaris 2.x release. The Source Compatibility Package resolves this difference by setting up symbolic links whenever possible so that the applications, using the old path names, can access the files.

Second, many commands in this release are not compatible with their SunOS 4.x counterparts. As part of the Source Compatibility Package, a set of SunOS 4.x-compatible command binaries is also installed. If applications specify only the command name to be executed (and not a path name), the Binary Compatibility Package reads the PATH environment variable to find the correct command. For this reason the PATH variable should be set correctly before running the application.

For example, to get the default SunOS 4.x behavior, specify /usr/ucb before /usr/bin in PATH; otherwise, the default Solaris 2.x behavior is provided.

When a full path name is given, the Binary Compatibility Package interprets the path name as given. When the path begins with /usr/5bin, the default Solaris 2.x version of the command is executed; otherwise, the Source Compatibility Package version is executed. A relative path name is interpreted as given.

Starting in Solaris 2.5, five commands are relocated from /usr/ucb to /usr/bin to accommodate shell scripts written with absolute paths. These commands are arch(1), hostid(1)), hostname(1), mach(1), and pagesize(1)).

Performance

Running SunOS 4.x binaries using the binary compatibility packages requires more memory than running the same binaries under SunOS 4.x, or than running the same application after it has been ported to Solaris 2.x. Similarly, it requires more disk storage space and disk accesses. Using the binary compatibility packages will reduce the performance of the application and of the overall system.

Well-Behaved Applications

The binary compatibility packages work with well-behaved user applications. Applications that are not well-behaved can produce unpredictable results, and it is not recommended that the binary compatibility packages be used with these applications. Well-behaved applications are either statically or dynamically linked and meet the following requirements:

• Do not make any traps directly to the kernel

• Do not write directly to any system files

• Do not use /dev/kmem, /dev/mem, or libkvm

• Do not use unpublished SunOS interfaces

• Do not rely on customer-supplied drivers

• Do not rely on knowledge of the SPARC architecture

/dev/kmem, /dev/mem and libkvm

The contents of /dev/kmem and /dev/mem are release specific. Programs using /dev/kmem and /dev/mem are tied to a specific version of the operating system. Maintaining compatibility is not possible. Using /dev/kmem, /dev/mem, or libkvm routines in an application makes it non-portable.

Installing SunOS 4.x Applications

SunOS 4.x applications must be available on a Solaris 2.x system to use the binary compatibility packages. SunOS 4.x applications can be installed or mounted onto the Solaris 2.x system.

To install these applications, copy the executables in their original a.out format to the corresponding locations on the Solaris 2.x system. Applications can be copied using cp(1), rcp(1), tar(1), cpio(1), and so on. See the man Pages(1): User Commands in the Solaris 7 Reference Manual Collection for information on these commands.

In most cases, you should be able to install a 4.x application from the original distribution medium. Install scripts may require that /usr/ucb precede /usr/bin in the PATH variable to perform correctly.

It is also possible to mount SunOS 4.x directories on a Solaris 2.x system and execute binaries contained in them using the Binary Compatibility Package.

If the corresponding location does not already exist, or if there is a conflict with Solaris 2.x files, you may have to create directories, rename files, or resolve name conflicts individually.

Shared Object Files

All a.out shared object libraries required on the SunOS 4.x release, except for the SunOS and the Open Windows libraries, must be moved to Solaris 2.x or mounted. These libraries can be copied to the /usr/4lib directory. These libraries must retain the same major and minor version numbers they had in the SunOS 4.x release.

The run-time linker searches the following paths (specified as colon-separated lists of directories) for the dependent libraries:

• Environment variable LD_LIBRARY_PATH

• Directories specified at link-time with the -L dir option to ld(1)ld(1)

• Default directories: /usr/4lib:/usr/lib:/usr/local/lib

The /usr/4lib directory did not exist in SunOS 4.x. It is provided as a location for SunOS 4.x a.out libraries. This directory has been added to the default search rules so that compatibility package users can store their SunOS 4.x libraries there and be assured that the run-time linker will find them.