What are the ELF shared lib symbol versioning best practices?

Adam Jackson ajax at redhat.com
Tue Oct 21 16:13:19 UTC 2014

On Tue, 2014-10-21 at 15:59 +0100, David Howells wrote:
> Is there a good description of ELF shared library symbol versioning best
> practices somewhere?
> In particular, under what conditions do you need to create a new section in
> the versioning file given to the linker's --version-script option when new
> symbols are added?

Every time you add _any_ new exported symbol to the API.

> And what do you do if you've done it wrong?
> For example, in libkeyutils, I added a couple of symbols to KEYUTILS_1.4 when
> I should perhaps have created KEYUTILS_1.5 and added them there:
> 	http://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/commit/?id=49249ce7d84a967fcdc06fbe6bf1d0cf89ac5215
> I have been given a patch to move these symbols to KEYUTILS_1.5, but checking
> the keyctl program with "readelf -s", I see:
>     47: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND recursive_session_key_sca at KEYUTILS_1.4 (7)
> so I would guess applying this patch would break anything that uses this.
> I assumed that adding them to KEYUTILS_1.4 would be okay because nothing
> would've tried to use them previously because they didn't exist in any
> version.

Since rpm emits dependencies based on imported symbol versions (and not
whole version/symbol tuples), the problem this introduces is that an app
using this new symbol will only require KEYUTILS_1.4, and some versions
of keyutils will provide that version but not all of the symbols _in_
that version.

But symbol versions are also permanent; now that there are apps in the
world that want foo at KEYUTILS_1.4, you can never remove that.  You could
add it to _1.5 too, but having made the error it's not really fixing
anything to do that.

- ajax

More information about the devel mailing list