Simon Cowell auditions in front of Homer, Marge and Lisa.

Hear a 3-year-old describe “Star
Wars IV” in this Web favorite.

Dynamically Loaded (DL) Libraries

Dynamically loaded (DL) libraries are libraries that are loaded at times other than
during the startup of a program. They’re particularly useful for implementing
plugins or modules, because they permit waiting to load the plugin until it’s needed.
For example, the Pluggable Authentication Modules (PAM) system uses DL libraries
to permit administrators to configure and reconfigure authentication. They’re also useful
for implementing interpreters that wish to occasionally compile their code into machine
code and use the compiled version for efficiency purposes, all without stopping.
For example, this approach can be useful in implementing a just-in-time compiler
or multi-user dungeon (MUD).

In Linux, DL libraries aren’t actually special from the point-of-view of their format;
they are built as standard object files or standard shared libraries as discussed above.
The main difference is that the libraries aren’t automatically loaded at program link
time or start-up; instead, there is an API for opening a library, looking up symbols,
handling errors, and closing the library. C users will need to include the header
file <dlfcn.h> to use this API.

The interface used by Linux is essentially the same as that used in Solaris,
which I’ll call the “dlopen()” API. However, this same interface is not
supported by all platforms; HP-UX uses the different shl_load() mechanism,
and Windows platforms use DLLs with a completely different interface.
If your goal is wide portability, you probably ought to consider using some wrapping
library that hides differences between platforms. One approach is the glib
library with its support for Dynamic Loading of Modules; it uses the underlying
dynamic loading routines of the platform to implement a portable interface to
these functions. You can learn more about glib at
http://developer.gnome.org/doc/API/glib/glib-dynamic-loading-of-modules.html.
Since the glib interface is well-explained in its documentation, I won’t discuss it
further here. Another approach is to use libltdl, which is part of GNU libtool.
If you want much more functionality than this, you might want to look into a
CORBA Object Request Broker (ORB). If you’re still interested in directly using
the interface supported by Linux and Solaris, read on.

dlopen()

The dlopen(3) function opens a library and prepares it for use. In C its prototype is:

  void * dlopen(const char *filename, int flag);

If filename begins with “/” (i.e., it’s an absolute path), dlopen() will just try to use
it (it won’t search for a library). Otherwise, dlopen() will search for the library in the following order:

1. A colon-separated list of directories in the user’s LD_LIBRARY_PATH environment variable.
2. The list of libraries specified in /etc/ld.so.cache (which is generated from /etc/ld.so.conf).
3. /lib, followed by /usr/lib. Note the order here; this is the reverse of the order used by
   the old a.out loader. The old a.out loader, when loading a program, first searched /usr/lib,
   then /lib (see the man page ld.so(8)). This shouldn’t normally matter, since a library should
   only be in one or the other directory (never both), and different libraries with the same
   name are a disaster waiting to happen.

In dlopen(), the value of flag must be either RTLD_LAZY, meaning “resolve undefined
symbols as code from the dynamic library is executed”, or RTLD_NOW, meaning “resolve

all undefined symbols before dlopen() returns and fail if this cannot be done”. RTLD_GLOBAL

may be optionally or’ed with either value in flag, meaning that the external symbols defined

in the library will be made available to subsequently loaded libraries. While you’re debugging,

you’ll probably want to use RTLD_NOW; using RTLD_LAZY can create inscrutable errors

if there are unresolved references. Using RTLD_NOW makes opening the library take slightly

longer (but it speeds up lookups later); if this causes a user interface problem you can switch

to RTLD_LAZY later.

dlerror()

Errors can be reported by calling dlerror(), which returns a string describing the error from
the last call to dlopen(), dlsym(), or dlclose(). One oddity is that after calling dlerror(),
future calls to dlerror() will return NULL until another error has been encountered.

dlsym()

There’s no point in loading a DL library if you can’t use it. The main routine for using a DL library
is dlsym(3), which looks up the value of a symbol in a given (opened) library. This function is defined as:

 void * dlsym(void *handle, char *symbol);

the handle is the value returned from dlopen, and symbol is a NIL-terminated string. If you can
avoid it, don’t store the result of dlsym() into a void* pointer, because then you’ll have to cast it
each time you use it (and you’ll give less information to other people trying to maintain the program).

dlsym() will return a NULL result if the symbol wasn’t found. If you know that the symbol could
never have the value of NULL or zero, that may be fine, but there’s a potential ambiguity
otherwise: if you got a NULL, does that mean there is no such symbol, or that NULL is the value
of the symbol? The standard solution is to call dlerror() first (to clear any error condition that may
have existed), then call dlsym() to request a symbol, then call dlerror() again to see if an error
occurred. A code snippet would look like this:

 dlerror(); /* clear error code */

 s = (actual_type) dlsym(handle, symbol_being_searched_for);

 if ((err = dlerror()) != NULL) {

  /* handle error, the symbol wasn’t found */

 } else {

  /* symbol found, its value is in s */

 }

dlclose()

The converse of dlopen() is dlclose(), which closes a DL library. The dl library maintains link counts
for dynamic file handles, so a dynamic library is not actually deallocated until dlclose has been called
on it as many times as dlopen has succeeded on it. Thus, it’s not a problem for the same program to
load the same library multiple times. If a library is deallocated, its function _fini is called (if it exists) in
older libraries, but _fini is an obsolete mechanism and shouldn’t be relied on. Instead, libraries should
export routines using the __attribute__((constructor)) and __attribute__((destructor)) function attributes.
See Section 5.2 for more information. Note: dlclose() returns 0 on success, and non-zero on error;
some Linux manual pages don’t mention this.

DL Library Example

Here’s an example from the man page of dlopen(3). This example loads the math library and
prints the cosine of 2.0, and it checks for errors at every step (recommended):

    #include <stdlib.h>

    #include <stdio.h>

    #include <dlfcn.h>    int main(int argc, char **argv) {

        void *handle;

        double (*cosine)(double);

        char *error;

handle = dlopen ("/lib/libm.so.6", RTLD_LAZY);

        if (!handle) {

            fputs (dlerror(), stderr);

            exit(1);

        }

cosine = dlsym(handle, "cos");

        if ((error = dlerror()) != NULL)  {

            fputs(error, stderr);

            exit(1);

        }

printf ("%f\n", (*cosine)(2.0));

        dlclose(handle);

    }

If this program were in a file named “foo.c”, you would build the program with the following command:

    gcc -o foo foo.c -ldl

nm command

The nm(1) command can report the list of symbols in a given library. It works on both static
and shared libraries. For a given library nm(1) can list the symbol names defined, each symbol’s
value, and the symbol’s type. It can also identify where the symbol was defined in the source code
(by filename and line number), if that information is available in the library (see the -l option).

The symbol type requires a little more explanation. The type is displayed as a letter; lowercase
means that the symbol is local, while uppercase means that the symbol is global (external).
Typical symbol types include T (a normal definition in the code section), D (initialized data section),
B (uninitialized data section), U (undefined; the symbol is used by the library but not defined by the library),
and W (weak; if another library also defines this symbol, that definition overrides this one).

If you know the name of a function, but you truly can’t remember what library it was defined in,
you can use nm’s “-o” option (which prefixes the filename in each line) along with grep to find the
library name. From a Bourne shell, you can search all the libraries in /lib, /usr/lib,
direct subdirectories of /usr/lib, and /usr/local/lib for “cos” as follows:

nm -o /lib/* /usr/lib/* /usr/lib/*/* \

      /usr/local/lib/* 2> /dev/null | grep 'cos$'

Library constructor and destructor functions

Libraries should export initialization and cleanup routines using the gcc __attribute__((constructor))
and __attribute__((destructor)) function attributes. See the gcc info pages for information on these.
Constructor routines are executed before dlopen returns (or before main() is started if the library is
loaded at load time). Destructor routines are executed before dlclose returns (or after exit() or
completion of main() if the library is loaded at load time). The C prototypes for these functions are:

  void __attribute__ ((constructor)) my_init(void);

  void __attribute__ ((destructor)) my_fini(void);

Special functions _init and _fini (OBSOLETE/DANGEROUS)

Historically there have been two special functions, _init and _fini that can be used to control constructors
and destructors. However, they are obsolete, and their use can lead to unpredicatable results.
Your libraries should not use these; use the function attributes constructor and destructor above instead.

If you must work with old systems or code that used _init or _fini, here’s how they worked. Two special
functions were defined for initializing and finalizing a module: _init and _fini. If a function “_init” is exported
in a library, then it is called when the library is first opened (via dlopen() or simply as a shared library).
In a C program, this just means that you defined some function named _init. There is a corresponding function
called _fini, which is called whenever a client finishes using the library (via a call dlclose() that brings its
reference count to zero, or on normal exit of the program). The C prototypes for these functions are:

  void _init(void);

  void _fini(void);

read more on http://tldp.org/HOWTO/Program-Library-HOWTO/index.html

Ingredients

Directions

1. If you haven’t already, roast any whole spices (ie cumin, coriander, ajwain&/or fennel/aniseed) in a dry heavy bottomed pan for a minute or so until they give off a delicious aroma, then grind well.
2. Combine all ingredients, and store in an airtight container.

The code for the library

calc_mean.c

//#include <stdio.h>

##N(mean)
double mean(double a, double b) {
  return (a+b) / 2;
}

The header file

Of course, we need a header file.

calc_mean.h

double mean(double, double);

Creating the static library

A static library is basically a set of object files that were copied
into a single file. This single file is the static library. The static file
is created with the archiver (ar).

First, calc_mean.c is turned into an object file:

gcc -c calc_mean.c -o calc_mean.o

Then, the archiver (ar) is invoked to produce a static library
(named libmean.a) out of the object file calc_mean.o.

ar  rcs libmean.a      calc_mean.o

Note: the library must start with the three letters lib and have the suffix .a.

Creating the shared library

As with static libraries, an object file is created. The -fPIC option tells gcc to create position independant code which is necessary for shared libraries. Note also, that the object file created for the static library will be overwritten. That’s not bad, however, because we have a static library that already contains the needed object file.

gcc -c -fPIC calc_mean.c -o calc_mean.o

For some reason, gcc says:

cc1: warning: -fPIC ignored for target

(all code is position independent)

It looks like -fPIC is not necessary on x86, but all manuals say,
it’s needed, so I use it too.

Now, the shared library is created

gcc -shared -Wl,-soname,libmean.so.1 -o

libmean.so.1.0.1  calc_mean.o

Note: the library must start with the three letter lib.

The programm using the library

This is the program that uses the calc_mean library. Once, we
will link it against the static library and once against the shared library.

main.c

#include <stdio.h>
#include "calc_mean.h”

int main(int argc, char* argv[]) {

  double v1, v2, m;
  v1 = 5.2;
  v2 = 7.9;

  m  = mean(v1, v2);

  printf(”The mean of %3.2f and %3.2f
is %3.2f\n”, v1, v2, m);

  return 0;
}

Linking against static library

gcc -static main.c -L. -lmean -o statically_linked

Note: the first three letters (the lib) must not be specified,
as well as the suffix (.a)

Linking against shared library

gcc main.c -o dynamically_linked -L. -lmean

Note: the first three letters (the lib) must not be specified,
as well as the suffix (.so)

Executing the dynamically linked programm

LD_LIBRARY_PATH=.
./dynamically_linked

Interrogating libraries (`which library is sin() in?’)

nm libraryname should list all the symbols that libraryname has references to. It works on both static and shared libraries. Suppose that you want to know where tcgetattr() is defined: you might do

$ nm libncurses.so.1 |grep tcget
         U tcgetattr

The U stands for `undefined’ — it shows that the ncurses library uses but does not define it. You could also do

$ nm libc.so.5 | grep tcget
00010fe8 T __tcgetattr
00010fe8 W tcgetattr
00068718 T tcgetpgrp

The `W‘ stands for `weak’, which means that the symbol is defined, but in such a way that it can be overridden by another definition in a different library. A straightforward `normal’ definition (such as the one for tcgetpgrp) is marked by a `T‘

The short answer to the question in the title, by the way, is libm.(so|a). All the functions defined in <math.h> are kept in the maths library; thus you need to link with -lm when using any of them.

Finding files

ld: Output file requires shared library `libfoo.so.1`

The file search strategy of ld and friends varies according to version, but the only default you can reasonably assume is /usr/lib. If you want libraries elsewhere to be searched, specify their directories with the -L option to gcc or ld.

ELF shared libraries

To build libfoo.so as a shared library, the basic steps look like this:

$ gcc -fPIC -c *.c
$ gcc -shared -Wl,-soname,libfoo.so.1
-o libfoo.so.1.0 *.o
$ ln -s libfoo.so.1.0 libfoo.so.1
$ ln -s libfoo.so.1 libfoo.so
$ LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH ;
export LD_LIBRARY_PATH

Click to read