Let’s consider what is entailed by shared library versioning. Typically, successive versions of a shared library are compatible with one another, meaning that the functions in each module present the same calling interface and are semantically equivalent (i.e., they achieve identical results). Such differing but compatible versions are referred to as minor versions of a shared library. Occasionally, however, it is necessary to create a new major version of a library—one that is incompatible with a previous version. (In Compatible Versus Incompatible Libraries, we’ll see more precisely what may cause such incompatibilities.) At the same time, it must still be possible to continue running programs that require the older version of the library.
To deal with these versioning requirements, a standard naming convention is employed for shared library real names and sonames.
Each incompatible version of a shared library is distinguished by a unique major version identifier, which forms part of its real name. By convention, the major version identifier takes the form of a number that is sequentially incremented with each incompatible release of the library. In addition to the major version identifier, the real name also includes a minor version identifier, which distinguishes compatible minor versions within the library major version. The real name employs the format convention libname.so.major-id.minor-id.
Like the major version identifier, the minor version identifier can be any string, but, by convention, it is either a number, or two numbers separated by a dot, with the first number identifying the minor version, and the second number indicating a patch level or revision number within the minor version. Some examples of real names of shared libraries are the following:
libdemo.so.1.0.1 libdemo.so.1.0.2 Minor version, compatible with version 1.0.1 libdemo.so.2.0.0 New major version, incompatible with version 1.* libreadline.so.5.0
The soname of the shared library includes the same major version identifier as its corresponding real library name, but excludes the minor version identifier. Thus, the soname has the form libname.so.major-id.
Usually, the soname is created as a relative symbolic link in the directory that contains the real name. The following are some examples of sonames, along with the real names to which they might be symbolically linked:
libdemo.so.1 -> libdemo.so.1.0.2 libdemo.so.2 -> libdemo.so.2.0.0 libreadline.so.5 -> libreadline.so.5.0
For a particular major version of a shared library, there may be several library files distinguished by different minor version identifiers. Normally, the soname corresponding to each major library version points to the most recent minor version within the major version (as shown in the above examples for libdemo.so). This setup allows for the correct versioning semantics during the run-time operation of shared libraries. Because the static-linking phase embeds a copy of the (minor version-independent) soname in the executable, and the soname symbolic link may subsequently be modified to point to a newer (minor) version of the shared library, it is possible to ensure that an executable loads the most up-to-date minor version of the library at run time. Furthermore, since different major versions of a library have different sonames, they can happily coexist and be accessed by the programs that require them.
In addition to the real name and soname, a third name is usually defined for each shared library: the linker name, which is used when linking an executable against the shared library. The linker name is a symbolic link containing just the library name without the major or minor version identifiers, and thus has the form libname.so. The linker name allows us to construct version-independent link commands that automatically operate with the correct (i.e., most up-to-date) version of the shared library.
Typically, the linker name is created in the same directory as the file to which it refers. It can be linked either to the real name or to the soname of the most recent major version of the library. Usually, a link to the soname is preferable, so that changes to the soname are automatically reflected in the linker name. (In Installing Shared Libraries, we’ll see that the ldconfig program automates the task of keeping sonames up to date, and thus implicitly maintains linker names if we use the convention just described.)
Note
If we want to link a program against an older major version of a shared library, we can’t use the linker name. Instead, as part of the link command, we would need to indicate the required (major) version by specifying a particular real name or soname.
The following are some examples of linker names:
libdemo.so -> libdemo.so.2 libreadline.so -> libreadline.so.5
Table 41-1 summarizes information about the shared library real name, soname, and linker name, and Figure 41-3 portrays the relationship between these names.
Table 41-1. Summary of shared library names
Name | Format | Description |
|---|---|---|
real name |
| File holding library code; one instance per major-plus-minor version of the library. |
soname |
| One instance per major version of library; embedded in executable at link time; used at run time to find library via a symbolic link with same name that points to corresponding (most up-to-date) real name. |
linker name |
| Symbolic link to latest real name or (more usually) latest soname; single instance; allows construction of version-independent link commands. |
Putting all of the above information together, we now show how to build our demonstration library following the standard conventions. First, we create the object files:
$ gcc -g -c -fPIC -Wall mod1.c mod2.c mod3.cThen we create the shared library with the real name libdemo.so.1.0.1 and the soname libdemo.so.1.
$gcc -g -shared -Wl,-soname,libdemo.so.1 -o libdemo.so.1.0.1 \mod1.o mod2.o mod3.o
Next, we create appropriate symbolic links for the soname and linker name:
$ln -s libdemo.so.1.0.1 libdemo.so.1$ln -s libdemo.so.1 libdemo.so
We can employ ls to verify the setup (with awk used to select the fields of interest):
$ ls -l libdemo.so* | awk '{print $1, $9, $10, $11}'
lrwxrwxrwx libdemo.so -> libdemo.so.1
lrwxrwxrwx libdemo.so.1 -> libdemo.so.1.0.1
-rwxr-xr-x libdemo.so.1.0.1Then we can build our executable using the linker name (note that the link command makes no mention of version numbers), and run the program as usual:
$gcc -g -Wall -o prog prog.c -L. -ldemo$LD_LIBRARY_PATH=. ./progCalled mod1-x1 Called mod2-x2