19.2 Controlling the Exported Symbols of Shared Libraries

The lib-symbol-visibility module allows precise control of the symbols exported by a shared library. This is useful because

• It prevents abuse of undocumented APIs of your library. Symbols that are not exported from the library cannot be used. This eliminates the problem that when the maintainer of the library changes internals of the library, maintainers of other projects cry “breakage”. Instead, these maintainers are forced to negotiate the desired API from the maintainer of the library.
• It reduces the risk of symbol collision between your library and other libraries. For example, the symbol ‘readline’ is defined in several libraries, most of which don’t have the same semantics and the same calling convention as the GNU readline library.
• It reduces the startup time of programs linked to the library. This is because the dynamic loader has less symbols to process.
• It allows the compiler to generate better code. Within a shared library, a call to a function that is a global symbol costs a “call” instruction to a code location in the so-called PLT (procedure linkage table) which contains a “jump” instruction to the actual function’s code. (This is needed so that the function can be overridden, for example by a function with the same name in the executable or in a shared library interposed with LD_PRELOAD.) Whereas a call to a function for which the compiler can assume that it is in the same shared library is just a direct “call” instructions. Similarly for variables: A reference to a global variable fetches a pointer in the so-called GOT (global offset table); this is a pointer to the variable’s memory. So the code to access it is two memory load instructions. Whereas for a variable which is known to reside in the same shared library, it is just a direct memory access: one memory load instruction.

There are traditionally three ways to specify the exported symbols of a shared library.

• The programmer specifies the list of symbols to be exported when the shared library is created. Usually a command-line option is passed to the linker, with the name of a file containing the symbols.

  The upside of this approach is flexibility: it allows the same code to be used in different libraries with different export lists. The downsides are: 1. it’s a lot of maintenance overhead when the symbol list is platform dependent, 2. it doesn’t work well with C++, due to name mangling.

• The programmer specifies a “hidden” attribute for every variable and function that shall not be exported.

  The drawbacks of this approach are: Symbols are still exported from the library by default. It’s a lot of maintenance work to mark every non- exported variable and function. But usually the exported API is quite small, compared to the internal API of the library. And it’s the wrong paradigm: It doesn’t force thinking when introducing new exported API.

• The programmer specifies a “hidden” attribute for all files that make up the shared library, and an “exported” attribute for those symbols in these files that shall be exported.

  This is perfect: It burdens the maintainer only for exported API, not for library-internal API. And it keeps the annotations in the source code.

GNU libtool’s -export-symbols option implements the first approach. The script declared.sh from Gnulib can help to produce the list of symbols.

This gnulib module implements the third approach. For this it relies on GNU GCC 4.0 or newer, namely on its ‘-fvisibility=hidden’ command-line option and the “visibility” attribute. (The “visibility” attribute was already supported in GCC 3.4, but without the command line option, introduced in GCC 4.0, the third approach could not be used.)

More explanations on this subject can be found in https://gcc.gnu.org/wiki/Visibility, which contains more details on the GCC features and additional advice for C++ libraries, and in Ulrich Drepper’s paper https://www.akkadia.org/drepper/dsohowto.pdf, which also explains other tricks for reducing the startup time impact of shared libraries.

The gnulib autoconf macro gl_VISIBILITY tests for GCC 4.0 or newer. It defines a Makefile variable @CFLAG_VISIBILITY@ containing ‘-fvisibility=hidden’ or nothing. It also defines as a C macro and as a substituted variable: @HAVE_VISIBILITY@. Its value is 1 when symbol visibility control is supported, and 0 otherwise.

As of 2022, symbol visibility control is supported on

• ELF platforms (glibc, Linux, *BSD, Solaris) with GCC or clang,
• macOS,
• AIX with gcc or xlclang.

It is not supported on

• Other compilers on ELF platforms or AIX,
• Windows.

To use this module in a library, say libfoo, you will do these steps:

1. Add @CFLAG_VISIBILITY@ or (in a Makefile.am) $(CFLAG_VISIBILITY) to the CFLAGS for the compilation of the sources that make up the library.
2. Add a C macro definition, say ‘-DBUILDING_LIBFOO’, to the CPPFLAGS for the compilation of the sources that make up the library.
3. Define a macro specific to your library like this.

   #if HAVE_VISIBILITY && BUILDING_LIBFOO
   # define LIBFOO_SHLIB_EXPORTED __attribute__((__visibility__("default")))
   #else
   # define LIBFOO_SHLIB_EXPORTED
   #endif
   

   This macro should be enabled in all public header files of your library.

4. Annotate all variable, function and class declarations in all public header files of your library with ‘LIBFOO_SHLIB_EXPORTED’. This annotation can occur at different locations: between the ‘extern’ and the type or return type, or just before the entity being declared, or after the entire declarator. My preference is to put it right after ‘extern’, so that the declarations in the header files remain halfway readable.

Note that the precise control of the exported symbols will not work with other compilers than GCC >= 4.0, and will not work on systems where the assembler or linker lack the support of “hidden” visibility. Therefore, it’s good if, in order to reduce the risk of collisions with symbols in other libraries, you continue to use a prefix specific to your library for all non-static variables and functions and for all C++ classes in your library.

Note about other compilers: MSVC support can be added easily, by extending the definition of the macro mentioned above, to something like this:

#if HAVE_VISIBILITY && BUILDING_LIBFOO
# define LIBFOO_SHLIB_EXPORTED __attribute__((__visibility__("default")))
#elif (defined _WIN32 && !defined __CYGWIN__) && @BUILDING_SHARED@ && BUILDING_LIBFOO
# if defined DLL_EXPORT
#  define LIBFOO_SHLIB_EXPORTED __declspec(dllexport)
# else
#  define LIBFOO_SHLIB_EXPORTED
# endif
#elif (defined _WIN32 && !defined __CYGWIN__) && @BUILDING_SHARED@
# define LIBFOO_SHLIB_EXPORTED __declspec(dllimport)
#else
# define LIBFOO_SHLIB_EXPORTED
#endif

Here BUILDING_SHARED is an Autoconf variable that you have to define. It ought to evaluate to 1 in a build configured with ‘--enable-shared’, or to 0 in a build configured with ‘--disable-shared’. You may use the following ‘configure.ac’ snippet:

  if test "$enable_shared" = yes; then
    BUILDING_SHARED=1
  else
    BUILDING_SHARED=0
  fi
  AC_SUBST([BUILDING_SHARED])

And DLL_EXPORT is defined by Libtool, on Windows platforms, when compiling for a shared library (called DLL under Windows). It is not defined when Libtool compiles an object file meant to be linked statically into some executable.