Creating a New, Incompatible Version of the Library

When you create a new version of the library with incompatible changes, repeat the above steps except increment the number in the suffix of the shared library file name. That is, create libA.1 rather than libA.0, and set the symbolic link libA.so to point to libA.1. Applications linked with libA.0 continue to run with that library while new applications link and run with libA.1. Continue to increment the suffix number for subsequent incompatible versions, for example, libA.2, libA.3 and so forth.

Migrating an Existing Library to Use Library-Level Versioning

If you have an existing library, you can start using library-level versioning. First rename the existing library to have the extension .0. Then create the new version of the library with the extension .1 and an internal name using the .1 extension. Create a symbolic link with the extension .so to point to the .1 library. When you run a program that uses shared libraries and was linked before HP-UX 10.0, the dynamic loader first attempts to open the shared library ending in .0. If it cannot find that library, it attempts to open the library ending in .so.

The +h Option and Internal Names

The +h option gives a library an internal name for library-level versioning. Use +h to create versioned libraries:

+h internal_name

The internal_name is typically the same name as the library file itself, for example, libA.1 as in +h libA.1. When you link with a library that has an internal name, the linker puts the internal_name in the shared library dependency list of the executable or shared library being created. When running the resulting executable or shared library, it is the library named by this internal name that the dynamic loader loads. You can include a relative or absolute path with the internal name, but you must ensure that the dynamic loader can find the library from this name using its normal search process. For PA-32 compatibility mode (with +compat), if internal_name includes a relative path (that is, a path not starting with /), the internal name stored by the linker is the concatenation of the actual path where the library was found and internal_name, including the relative path. When you run the resulting program, if the dynamic loader cannot find the library at this location, the program does not run. If internal_name includes an absolute path (that is, a path starting with /), the internal name stored by the linker is simply the internal_name, including the absolute path. When the resulting program is run, if the dynamic loader cannot find the library at this location, the program will not run. See “Internal Name Processing” (page 125) for more information.

File System Links to Shared Libraries

This section discusses the situation where you have used the ln(1) command to create file system links to shared library files. For example:

$ ld

-b

-o /X/libapp.so *.o

Create shared library.

$ ln

-s

/X/libapp.so /tmp/libmine.so

Make the link.

Figure 10 Example for Creating File System Link to a Shared Library File

During a link, the linker records the file name of the opened library in the shared library list of the output file. However, if the shared library is a file system link to the actual library, the linker does not record the name of the library the file system link points to. Rather it records the name of the file system link. For example, if /tmp/libmine.so is a file system link to /X/libapp.so, the following command records /tmp/libmine.so in a.out, not /X/libapp.so as may be expected:

$ ld main.o -L /tmp -lmine -lc

112 Creating and Using Libraries