Shared libraries

Checking for compatibility

The following guidelines explain how to check for upwardly compatible shared libraries. However, upward compatibility may not always be an issue. Consider the case in which a shared library is one piece of a larger system and is not delivered as a separate product. In this restricted case, identify all a.out files that use a particular library. As long as all the a.out files are rebuilt every time the library changes, the a.out files will run successfully, even though versions of the library are not compatible.

Checking versions of shared libraries using chkshlib(CP)

a.out files will not execute properly if newer versions of a library are not compatible with the previous ones.

If you use shared libraries, you might need to find out if different versions of a shared library are compatible, or if executable files could have been built with a particular host shared library or can run with a particular target shared library. For example, you might have a new version of a target shared library, and you need to know if all the executable files that ran with the older version will run with the new one. You might need to find out if a particular target shared library can reference symbols in another shared library. chkshlib(CP) has been provided to allow you to do these and other comparisons.

chkshlib takes names of target shared libraries, host shared libraries, and executable files as input, and checks to see if those files satisfy the compatibility criteria. chkshlib checks to see if every library symbol in the first file that needs to be matched exists in the second file and has the same address.

The following table shows what types of files and how many of them chkshlib accepts as input. The rows listed down represent the first input given, and the columns listed across represent secondary input. For example, if the first input file you give chkshlib is a target shared library, you must give another input file that is a target or host shared library.

Nothing Executable Target Host

Executable OK No OK OK

Target No No OK OK

Host OK No OK OK

	Nothing	Executable	Target	Host
Executable	OK	No	OK	OK
Target	No	No	OK	OK
Host	OK	No	OK	OK

*: The executable file must be one that was built using a host shared library. A useful way to confirm this is to use dump -L to find out which target file(s) gets loaded when the program is run. See dump(CP).
**: You can also have executable target1...targetn and executable host1...hostn.

An example of a chkshlib command line is shown below:

   chkshlib /shlib/libc_s /lib/libc_s.a

In this example, /shlib/libc_s is a target shared library and /lib/libc_s.a is a host shared library. chkshlib will check to see if executable files built with /shlib/libc_s would be able to run with /lib/libc_s.a.

Depending on the input it receives, chkshlib checks to find out if the following is true:

an executable file will run with the given target shared library
an executable file could have been built using the given host shared library
an executable file produced with a given host shared library will run with a given target shared library
an executable file that ran with an old version of a target shared library will run with a new version
a new host shared library can replace the old host shared library; that is, executable files built with the new host shared library will run with the old target shared library
a target shared library can reference symbols in another target shared library

To determine if files are compatible, chkshlib has to determine which library symbols in the first file need to be matched in the second file.

For target shared libraries, the symbols of concern are all external, defined symbols with non-zero values, except for branch labels (branch labels always start with .bt), and the special symbols etext, edata, and end.
For host shared libraries, the symbols of concern are all external, absolute symbols with a non-zero value.
For executable files, the symbols of concern are all external, absolute symbols with a non-zero value, except for the special symbols etext, edata, and end.

For two files to be compatible, the target pathnames must be identical in both files (unless the chkshlib -i option has been specified).

The following table displays the output you will receive when you use chkshlib to check different combinations of files for compatibility. In this table file1 represents the name of the first file given, and file2,3,... represents the names of any more files given as input.

Input Output

file1 is executable file1 can [may not] execute using file2

file2,3,... (if any) are targets file1 can [may not] execute using file3

file1 is executable file1 may [may not] have been produced using file2

file2,3 are hosts file1 may [may not] have been produced using file3

file1 is host file1 can [may not] produce executables which

file2 (if any) is target will run with file2

file1 is target file2 can [may not] produce executables which

file2 is host will run with file1

both files are targets or file1 can [may not] replace file2

both files are hosts file2 can [may not] replace file1

both files are targets and file1 can [may not] include file2

-n option is specified

Input	Output
file1 is executable	file1 can [may not] execute using file2
file2,3,... (if any) are targets	file1 can [may not] execute using file3
file1 is executable	file1 may [may not] have been produced using file2
file2,3 are hosts	file1 may [may not] have been produced using file3
file1 is host	file1 can [may not] produce executables which
file2 (if any) is target	will run with file2
file1 is target	file2 can [may not] produce executables which
file2 is host	will run with file1
both files are targets or	file1 can [may not] replace file2
both files are hosts	file2 can [may not] replace file1
both files are targets and	file1 can [may not] include file2
-n option is specified

*: The -n option tells chkshlib that the two files are target shared libraries, the first of which can reference (include) symbols in the other. See ``Referencing symbols in a shared library from another shared library'' for details.

For more information on chkshlib, see chkshlib(CP).

NOTE: Symbols that have been hidden via the #hide directive cannot be referenced directly. chkshlib will ignore them in its check for compatibility.

Dealing with incompatible libraries

There are two methods of dealing with incompatible libraries. First, you can rebuild all the a.out files that use your library. If feasible, this is probably the best method. Unfortunately, you might not be able to find those a.out files, let alone force their owners to rebuild them with your new library.

The second method is to give a different target pathname to the new version of the library. The host and target pathnames are independent; you do not have to change the host library pathname. New a.out files will use your new target library, but old a.out files will continue to access the old library.

As the library developer, it is your responsibility to check for compatibility and, probably, to provide a new target library pathname for a new version of a library that is incompatible with older versions. If you fail to resolve compatibility problems, a.out files that use your library will not work properly.

NOTE: You should try to avoid multiple library versions. If too many copies of the same shared library exist, they might actually use more disk space and more memory than the equivalent relocatable version would have.