Fun with weak dynamic linking

Dynamic linkers, at least in the UNIX world, usually allow to load libraries in a process address space at startup. On Linux systems, you load such a library with LD_PRELOAD. On OSX, with DYLD_INSERT_LIBRARIES.

On Linux systems, when using LD_PRELOAD, the dynamic linker will also use symbols from the (pre)loaded library instead of system libraries. For example, if a program calls the write function and a library exporting a write symbol is loaded with LD_PRELOAD, the write function from the loaded library will be used instead of that of the libc (even when the symbol version doesn't match).

On OSX, symbol resolution is usually done with a "two-level namespace": symbols are associated with library names, and when resolving symbols, both are used. More than that, the library name is used to find the library in the dyld search path. Libraries loaded with DYLD_INSERT_LIBRARIES won't be used with two-level namespace symbol resolution, which makes it less useful than LD_PRELOAD. Fortunately, it is also possible to use a "flat" namespace, in which case only the symbol name is considered during symbol resolution, and is searched in all loaded libraries, in the order in which they were loaded. Flat namespace can be triggered by setting the DYLD_FORCE_FLAT_NAMESPACE environment variable, linking the main program with -force_flat_namespace, or linking programs and libraries with the -flat_namespace argument. Note the latter only affects the programs and libraries built with that argument, while the former two force to use a flat namespace for all libraries, including those which, like system ones, were built with a two-level namespace. There are also cases where a single symbol may be resolved with the flat namespace, while others in the program or library are using two-level namespace.

Weak dynamic linking is another feature that can be used to tell the dynamic linker to ignore missing symbols. Consider the following source code:

extern void foo() __attribute__((weak)); // weak_import is preferred on OSX.
int main() {
  if (foo)
  return 0;

On Linux systems, this just works. Compile the program (you'll need to build it with -fPIC, though), start it, and it will do nothing, since foo is defined nowhere.

Combined with shared library (pre)loading, this can be used to provide simple hooks in your application. For example, with the following source code built as a shared library:

#include <stdio.h>
void foo() {

Running the program again with LD_PRELOAD set to load that shared library (note won't work, a path is needed, like LD_PRELOAD=./, it will print foo because the dynamic linker will have resolved the foo symbol to that of the shared library.

On OSX, unfortunately, things are not as easy. First, building the test program above fails:

Undefined symbols for architecture x86_64:
  "_foo", referenced from:
      _main in test-LIeVtB.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

There are linker options to force undefined symbols to be resolved at runtime:

  • -undefined dynamic_lookup, which will mark all undefined symbols as having to be looked up at runtime,
  • -Wl,-U,symbol_name, which only does so for the given symbol (note: you have to prepend an underscore to the symbol name)

With one of these options, the program works as on Linux: it does nothing when run alone, and prints foo when loading the library with DYLD_INSERT_LIBRARIES... if you build with XCode 4.5. Running the program built with XCode 4.3 fails when not loading the shared library, with the following error:

dyld: Symbol not found: _foo
  Referenced from: ./test
  Expected in: flat namespace
 in ./test
Trace/BPT trap: 5

And if at build time, you target OSX 10.5 (with MACOSX_DEPLOYMENT_TARGET or -mmacosx-version-min), the error is slightly different:

dyld: Symbol not found: _foo
  Referenced from: ./test
  Expected in: dynamic lookup

Trace/BPT trap: 5

Each error is due to a different bug:

  • Since OSX 10.6, the link edition rules in the __LINKEDIT segment are in a new, compressed, format: DYLD_INFO. The linker in Xcode < 4.5 forgets to flag weak imports as weak in the DYLD_INFO data. Compare the output for dyldinfo with a binary built with Xcode 4.5 vs. the output for a binary built with Xcode 4.3:
    $ dyldinfo -bind test-xcode4.5 | sed -n '2p;/foo/p'
    segment section          address        type    addend dylib            symbol
    __DATA  __got            0x100001038    pointer      0 flat-namespace   _foo (weak import)
    $ dyldinfo -bind test-xcode4.3 | sed -n '2p;/foo/p'
    segment section          address        type    addend dylib            symbol
    __DATA  __got            0x100001038    pointer      0 flat-namespace   _foo

    Notice the missing weak import. Manually setting the flag with a hexadecimal editor fixes it (in both bind and lazy_bind tables).

  • In older OSX releases, the link edition rules use a "classic" format. In that format, the symbol table is used for flags such as N_WEAK_REF (weak reference). In the new DYLD_INFO format, the N_WEAK_REF flag isn't used, which partly explains the previous bug. When using the old format and two-level namespaces, missing weak symbols are errors. With flat namespace, they aren't. This means the error we get with a program built for a 10.5 target goes away if building with -flat_namespace. Note this doesn't work at the symbol level: if the library is built for two-level namespace (and is marked as such in the Mach-O header), and the weak symbol is without a corresponding library name, making it resolved with a flat namespace, it doesn't work.

At this point, one could think weak dynamic linking is pretty much useless on OSX, at least, that it was before Xcode 4.5 was released. As it turns out, there are other use cases where it actually works. Consider the following code:

#include <malloc/malloc.h>
// The following is defined in malloc/malloc.h:
// extern size_t malloc_zone_pressure_relief(malloc_zone_t *zone, size_t goal) __attribute__((weak_import));
int main() {
  if (malloc_zone_pressure_relief)
    malloc_zone_pressure_relief(NULL, 0);
  return 0;

This program in itself is useless, but the point is, the malloc_zone_pressure_relief function is only available since OSX 10.7. Without the weak_import, the program would fail to start with an undefined symbol on OSX 10.6 and below. Without the if, it would crash because the symbol would resolve to NULL, and the program would jump there. But the program itself has to be built on OSX 10.7 at least, for the malloc_zone_pressure_relief function to be there when building.

And in that use-case, we end up with the right flags in DYLD_INFO:

$ dyldinfo -bind test | sed -n '2p;/malloc/p'
segment section          address        type    addend dylib            symbol
__DATA  __got            0x100001038    pointer      0 libSystem        _malloc_zone_pressure_relief (weak import)

This actually gives us a hint for a way out of our misery for our foo function on Xcode < 4.5: linking against a dummy library implementing the weak symbol. When doing so, we get the proper flag in DYLD_INFO, like with malloc_zone_pressure_relief:

$ dyldinfo -bind test | sed -n '2p;/foo/p'
segment section          address        type    addend dylib            symbol
__DATA  __got            0x100001038    pointer      0 libfoo           _foo (weak import)

And the linker additionally does something nice: when all symbols needed from a library are weak references, it marks the library import itself as weak:

$ otool -l test | grep -B 2 libfoo
          cmd LC_LOAD_WEAK_DYLIB
      cmdsize 40
         name libfoo.dylib (offset 24)

What this means is that even if the libfoo.dylib is missing, it will still work. The downside is that we are now using two-level namespace, which, as mentioned above, makes DYLD_INSERT_LIBRARIES useless. The program thus needs to be built with a flat namespace.

Update: It turns out some versions of XCode don't conveniently mark libraries with only weak imports as weakly linked, so the -Wl,-weak_library,libraryname.dylib flag is required instead of -Llibraryname.

In summary, if you want to add optional hooks that a library loaded through LD_PRELOAD/ DYLD_INSERT_LIBRARIES can implement:

  • on OSX < 10.6, use weak symbols and build with -flat_namespace,
  • on OSX >= 10.6, when building with Xcode < 4.5, use weak symbols, build with -flat_namespace and link against a dummy library implementing the hook functions with -Wl,-weak_library,libraryname.dylib,
  • on Linux systems and on OSX >= 10.6, when building with Xcode 4.5, simply use weak symbols,
  • on Windows, to the best of my knowledge, weak dynamic linking is not supported.

Stay tuned for the next post, which will describe what this will be used for in Firefox.

2012-11-05 21:49:26+0900


Responses are currently closed, but you can trackback from your own site.

8 Responses to “Fun with weak dynamic linking”

  1. Bob Pelerson Says:

    How does this work on FreeBSD? Is it the same as Linux or are there special considerations?

  2. njn Says:

    My guess is :)

  3. glandium Says:

    Bob Pelerson: I think it’s the same as Linux.
    njn: good guess :)

  4. Neil Rashbrook Says:

    On Win16, all references were weak, as long as the DLL itself existed. However any undefined references would get linked to KERNEL:120 instead of, say, NULL. This displayed a system message “Unrecoverable application error” “Call to undefined dynalink” and terminated the process. Theoretically you could explicitly link to KERNEL:120 and compare function pointers to detect an undefined reference, but nobody did this, so that programs that had incorrect minimum expected Windows versions simply crashed. For Win32 Microsoft decided to abolish all forms of weak reference apart from GetProcAddress. Note that delay loading is not a weak reference, for a start it’s a security vulnerability to delay load a DLL that’s not guaranteed to be present.

    See for example (and others linked from it).

  5. Till Schneidereit Says:

    You’ve probably seen it, but for completeness’ sake: I stumbled upon this, some time ago:

    However, that’s so undocumented and rarely used that relying on it probably isn’t a good idea.

  6. B2G Compilation error on Mac OS X | Shizen008's Blog Says:

    […]    LOCAL_MODULE := sqlite3   A good explanation of what’s going on can be found here:   Special thanks to : Pekka Nikander for posting the solution at : […]

  7. Mike Shal Says:

    I’m not sure if this would help in your specific case, but instead of using DYLD_FORCE_FLAT_NAMESPACE, you can use an “__interpose” section. Eg for intercepting write() calls:

    static int mywrite(int filedes, const void *buf, size_t nbyte)
    printf(“Writing %i bytes\n”, nbyte);
    return write(filedes, buf, nbyte);

    struct interpose {
    void *new_func;
    void *orig_func;

    static const struct interpose interposers[] __attribute__ ((section(“__DATA, __interpose”))) __attribute__((used)) = {
    {(void*)mywrite, (void*)write},

    I’ve found that DYLD_FORCE_FLAT_NAMESPACE can have some performance penalties (generally an extra startup cost) that aren’t present when using interpose. That only really matters if you’re starting up lots of processes with your library inserted, though.

  8. glandium Says:

    It’s been a long time, so I don’t remember the details, but __interpose didn’t work for what I wanted to do.