How To Write Shared Libraries

Ulrich Drepper
Red Hat, Inc.
[email protected]

January 22, 2005

Abstract
Today, shared libraries are ubiquitous. Developers use them for multiple reasons and create
them just as they would create application code. This is a problem, though, since on many
platforms some additional techniques must be applied even to generate decent code. Even more
knowledge is needed to generate optimized code. This paper introduces the required rules and
techniques. In addition, it introduces the concept of ABI (Application Binary Interface) stability
and shows how to manage it.

1 Preface 1.1 A Little Bit of History

For a long time, programmers collected commonly used The binary format used initially for Linux was an a.out
code in libraries so that code could be reused. This saves variant. When introducing shared libraries certain design
development time and reduces errors since reused code decisions had to be made to work in the limitations of
only has to be debugged once. With systems running a.out. The main accepted limitation was that no reloca-
dozens or hundreds of processes at the same time reuse tions are performed at the time of loading and afterward.
of the code at link-time solves only part of the problem. The shared libraries have to exist in the form they are
Many processes will use the same pieces of code which used at run-time on disk. This imposes a major restric-
they import for libraries. With the memory management tion on the way shared libraries are built and used: every
systems in modern operating systems it is also possible shared library must have a fixed load address; otherwise it
to share the code at run-time. This is done by loading the would not be possible to generate shared libraries which
code into physical memory only once and reusing it in do not have to be relocated.
multiple processes via virtual memory. Libraries of this
kind are called shared libraries. The fixed load addresses had to be assigned and this has
to happen without overlaps and conflicts and with some
The concept is not very new. Operating system designers future safety by allowing growth of the shared library.
implemented extensions to their system using the infras- It is therefore necessary to have a central authority for
tructure they used before. The extension to the OS could the assignment of address ranges which in itself is a ma-
be done transparently for the user. But the parts the user jor problem. But it gets worse: given a Linux system
directly has to deal with created initially problems. of today with many hundred of DSOs (Dynamic Shared
Objects) the address space and the virtual memory avail-
The main aspect is the binary format. This is the for- able to the application gets severely fragmented. This
mat which is used to describe the application code. Long would limit the size of memory blocks which can be dy-
gone are the days that it was sufficient to provide a mem- namically allocated which would create unsurmountable
ory dump. Multi-process systems need to identify differ- problems for some applications. It would even have hap-
ent parts of the file containing the program such as the pened by today that the assignment authority ran out of
text, data, and debug information parts. For this, binary address ranges to assign, at least on 32-bit machines.
formats were introduced early on. Commonly used in the
early Unix-days were formats such as a.out or COFF. We still have not covered all the drawbacks of the a.out
These binary formats were not designed with shared li- shared libraries. Since the applications using shared li-
braries in mind and this clearly shows. braries should not have to be relinked after changing a
shared library it uses, the entry points, i.e., the function
and variable addresses, must not change. This can only
be guaranteed if the entry points are kept separate from
the actual code since otherwise limits on the size of a
Copyright c 2002, 2003, 2004, 2005 Ulrich Drepper function would be hard-coded. A table of function stubs
All rights reserved. No redistribution allowed. which call the actual implementation was used in solu-

1
tion used on Linux. The static linker got the address of followed to get any benefits, and some more rules have to
each function stub from a special file (with the filename be followed to get optimal results. Explaining these rules
extension .sa). At run-time a file ending in .so.X.Y.Z will be the topic of a large portion of this paper.
was used and it had to correspond to the used .sa file.
This in turn requires that an allocated entry in the stub Not all uses of DSOs are for the purpose of saving re-
table always had to be used for the same function. The sources. DSOs are today also often used as a way to
allocation of the table had to be carefully taken care of. structure programs. Different parts of the program are
Introducing a new interface meant appending to the ta- put into separate DSOs. This can be a very powerful tool,
ble. It was never possible to retire a table entry. To avoid especially in the development phase. Instead of relink-
using an old shared library with a program linked with a ing the entire program it is only necessary to relink the
newer version, some record had to be kept in the applica- DSO(s) which changed. This is often much faster.
tion: the X and Y parts of the name of the .so.X.Y.Z
suffix was recorded and the dynamic linker made sure Some projects decide to keep many separate DSOs even
minimum requirements were met. in the deployment phase even though the DSOs are not
reused in other programs. In many situations it is cer-
The benefits of the scheme are that the resulting program tainly a useful thing to do: DSOs can be updated indi-
runs very fast. Calling a function in such a shared li- vidually, reducing the amount of data which has to be
braries is very efficient even for the first call. It can transported. But the number of DSOs must be kept to a
be implemented with only two absolute jumps: the first reasonable level. Not all programs do this, though, and
from the user code to the stub, and the second from the we will see later on why this can be a problem.
stub to the actual code of the function. This is probably
faster than any other shared library implementation, but Before we can start discussing all this some understand-
its speed comes at too high a price: ing of ELF and its implementation is needed.

1.3 How Is ELF Implemented?

1. a central assignment of address ranges is needed;
2. collisions are possible (likely) with catastrophic re-
The handling of a statically linked application is very
sults;
simple. Such an application has a fixed load address
3. the address space gets severely fragmented. which the kernel knows. The load process consists sim-
ply of making the binary available in the appropriate ad-
dress space of a newly created process and transferring
For all these reasons and more, Linux converted early on control to the entry point of the application. Everything
to using ELF (Executable Linkage Format) as the binary else was done by the static linker when creating the exe-
format. The ELF format is defined by the generic spec- cutable.
ification (gABI) to which processor-specific extensions
(psABI) are added. As it turns out the amortized cost of Dynamically linked binaries, in contrast, are not com-
function calls is almost the same as for a.out but the plete when they are loaded from disk. It is therefore
restrictions are gone. not possible for the kernel to immediately transfer con-
trol to the application. Instead some other helper pro-
1.2 The Move To ELF gram, which obviously has to be complete, is loaded as
well. This helper program is the dynamic linker. The task
of the dynamic linker is it, to complete the dynamically
For programmers the main advantage of the switch to linked application by loading the DSOs it needs (the de-
ELF was that creating ELF shared libraries, or in ELF- pendencies) and to perform the relocations. Then finally
speak DSOs, becomes very easy. The only difference be- control can be transferred to the program.
tween generating an application and a DSO is in the final
link command line. One additional option (--shared in This is not the last task for the dynamic linker in most
the case of GNU ld) tells the linker to generate a DSO cases, though. ELF allows the relocations associated with
instead of an application, the latter being the default. In a symbol to be delayed until the symbol is needed. This
fact, DSOs are little more than a special kind of binary; lazy relocation scheme is optional, and optimizations dis-
the difference is that they have no fixed load address and cussed below for relocations performed at startup imme-
hence require the dynamic linker to actually become ex- diately effect the lazy relocations as well. So we ignore
ecutable. With Position Independent Executable (PIEs) in the following everything after the startup is finished.
the difference shrinks even more.
1.4 Startup: In The Kernel
This, together with the introduction of GNU Libtool which
will be described later, has led to the wide adoption of
DSOs by programmers. Proper use of DSOs can help Starting execution of a program begins in the kernel, nor-
save large amounts of resources. But some rules must be mally in the execve system call. The currently executed

2 Version 3.0 How To Write Shared Libraries

 typedef struct typedef struct
{ {
Elf32 Word p type; Elf64 Word p type;
Elf32 Off p offset; Elf64 Word p flags;
Elf32 Addr p vaddr; Elf64 Off p offset;
Elf32 Addr p paddr; Elf64 Addr p vaddr;
Elf32 Word p filesz; Elf64 Addr p paddr;
Elf32 Word p memsz; Elf64 Xword p filesz;
Elf32 Word p flags; Elf64 Xword p memsz;
Elf32 Word p align; Elf64 Xword p align;
} Elf32 Phdr; } Elf64 Phdr;

Figure 1: ELF Program Header C Data Structure

code is replaced with a new program. This means the ad- in the program header table and the e phentsize field
dress space content is replaced by the content of the file contains the size of each entry. This last value is useful
containing the program. This does not happen by sim- only as a run-time consistency check for the binary.
ply mapping (using mmap) the content of the file. ELF
files are structured and there are normally at least three The different segments are represented by the program
different kinds of regions in the file: header entries with the PT LOAD value in the p type field.
The p offset and p filesz fields specify where in the
file the segment starts and how long it is. The p vaddr
• Code which is executed; this region is normally not and p memsz fields specifies where the segment is located
writable; in the the process’ virtual address space and how large
the memory region is. The value of the the p vaddr field
• Data which is modified; this region is normally not
itself is not necessarily required to be the final load ad-
executable;
dress. DSOs can be loaded at arbitrary addresses in the
• Data which is not used at run-time; since not needed virtual address space. But the relative position of the seg-
it should not be loaded at startup. ments is important. For pre-linked DSOs the actual value
of the p vaddr field is meaningful: it specifies the ad-
dress for which the DSO was prelinked. But even this
Modern operating systems and processors can protect mem- does not mean the dynamic linker cannot ignore this in-
ory regions to allow and disallow reading, writing, and formation if necessary.
executing separately for each page of memory.1 It is
preferable to mark as many pages as possible not writable The size in the file can be smaller than the address space
since this means that the pages can be shared between it takes up in memory. The first p filesz bytes of the
processes which use the same application or DSO the memory region are initialized from the data of the seg-
page is from. Write protection also helps to detect and ment in the file, the difference is initialized with zero.
prevent unintentional or malignant modifications of data This can be used to handle BSS sections2 , sections for
or even code. uninitialized variables which are according to the C stan-
dard initialized with zero. Handling uninitialized vari-
For the kernel to find the different regions, or segments ables this way has the advantage that the file size can be
in ELF-speak, and their access permissions, the ELF file reduced since no initialization value has to be stored, no
format defines a table which contains just this informa- data has to be copied from dist to memory, and the mem-
tion, among other things. The ELF Program Header ta- ory provided by the OS via the mmap interface is already
ble, as it is called, must be present in every executable initialized with zero.
and DSO. It is represented by the C types Elf32 Phdr
and Elf64 Phdr which are defined as can be seen in fig- The p flags finally tells the kernel what permissions to
ure 1. use for the memory pages. This field is a bitmap with the
bits given in the following table being defined. The flags
To locate the program header data structure another data are directly mapped to the flags mmap understands.
structure is needed, the ELF Header. The ELF header is
the only data structure which has a fixed place in the file,
starting at offset zero. Its C data structure can be seen
in figure 2. The e phoff field specifies where, counting
from the beginning of the file, the program header table
starts. The e phnum field contains the number of entries 2 A BSS section contains only NUL bytes. Therefore they do not
1A memory page is the smallest entity the memory subsystem of have to be represented in the file on the storage medium. The loader
the OS operates on. The size of a page can vary between different just has to know the size so that it can allocate memory large enough
architectures and even within systems using the same architecture. and fill it with NUL

Ulrich Drepper Version 3.0 3

 typedef struct typedef struct
{ {
unsigned char e ident[EI NIDENT]; unsigned char e ident[EI NIDENT];
Elf32 Half e type; Elf64 Half e type;
Elf32 Half e machine; Elf64 Half e machine;
Elf32 Word e version; Elf64 Word e version;
Elf32 Addr e entry; Elf64 Addr e entry;
Elf32 Off e phoff; Elf64 Off e phoff;
Elf32 Off e shoff; Elf64 Off e shoff;
Elf32 Word e flags; Elf64 Word e flags;
Elf32 Half e ehsize; Elf64 Half e ehsize;
Elf32 Half e phentsize; Elf64 Half e phentsize;
Elf32 Half e phnum; Elf64 Half e phnum;
Elf32 Half e shentsize; Elf64 Half e shentsize;
Elf32 Half e shnum; Elf64 Half e shnum;
Elf32 Half e shstrndx; Elf64 Half e shstrndx;
} Elf32 Ehdr; } Elf64 Ehdr;

Figure 2: ELF Header C Data Structure

p flags Value mmap flag Description application is complete. For this a structured way exists.
PF X 1 PROT EXEC Execute Permission The kernel puts an array of tag-value pairs on the stack
PF W 2 PROT WRITE Write Permission of the new process. This auxiliary vector contains be-
PF R 4 PROT READ Read Permission side the two aforementioned values several more values
which allow the dynamic linker to avoid several system
calls. The elf.h header file defines a number of con-
stants with a AT prefix. These are the tags for the entries
After mapping all the PT LOAD segments using the ap- in the auxiliary vector.
propriate permissions and the specified address, or after
freely allocating an address for dynamic objects which After setting up the auxiliary vector the kernel is finally
have no fixed load address, the next phase can start. The ready to transfer control to the dynamic linker in user
virtual address space of the dynamically linked executable mode. The entry point is defined in e entry field of the
itself is set up. But the binary is not complete. The kernel ELF header of the dynamic linker.
has to get the dynamic linker to do the rest and for this
the dynamic linker has to be loaded in the same way as
the executable itself (i.e., look for the loadable segments 1.5 Startup in the Dynamic Linker
in the program header). The difference is that the dy-
namic linker itself must be complete and should be freely
relocatable. The second phase of the program startup happens in the
dynamic linker. Its tasks include:
Which binary implements the dynamic linker is not hard-
coded in the kernel. Instead the program header of the
application contains an entry with the tag PT INTERP.
• Determine and load dependencies;
The p offset field of this entry contains the offset of
a NUL-terminated string which specifies the file name of
this file. The only requirement on the named file is that • Relocate the application and all dependencies;
its load address does not conflict with the load address of
any possible executable it might be used with. In gen-
• Initialize the application and dependencies in the
eral this means that the dynamic linker has no fixed load
correct order.
address and can be loaded anywhere; this is just what dy-
namic binaries allow.

Once the dynamic linker has also been mapped into the In the following we will discuss in more detail only the
memory of the stillborn process we can start the dynamic relocation handling. For the other two points the way
linker. Note it is not the entry point of the application to for better performance is clear: have fewer dependencies.
which control is transfered to. Only the dynamic linker is Each participating object is initialized exactly once but
ready to run. Instead of calling the dynamic linker right some topological sorting has to happen. The identify and
away, one more step is performed. The dynamic linker load process also scales with the number dependencies;
somehow has to be told where the application can be in most (all?) implementations this is not only a linear
found and where control has to be transferred to once the growth.

4 Version 3.0 How To Write Shared Libraries

The relocation process is normally3 the most expensive The result of any relocation will be stored somewhere
part of the dynamic linker’s work. It is a process which is in the object with the reference. Ideally and generally
asymptotically at least O(R +nr) where R is the number the target location is in the data segment. If code is in-
of relative relocations, r is the number of named reloca- correctly generated by the user, compiler, or linker relo-
tions, and n is the number of participating DSOs (plus cations might modify text or read-only segments. The
the main executable). Deficiencies in the ELF hash ta- dynamic linker will handle this correctly if the object is
ble function and various ELF extensions modifying the marked, as required by the ELF specification, with the
symbol lookup functionality may well increase the factor DF TEXTREL set in the DT FLAGS entry of the dynamic
to O(R + rn log s) where s is the number of symbols. section (or the existence of the DT TEXTREL flag in old
This should make clear that for improved performance it binaries). But the result is that the modified page can-
is significant to reduce the number if relocations and sym- not be shared with other processes using the same object.
bols as much as possible. After explaining the relocation The modification process itself is also quite slow since
process we will do some estimates for actual numbers. the kernel has to reorganize the memory handling data
structures quite a bit.
1.5.1 The Relocation Process
1.5.2 Symbol Relocations
Relocation in this context means adjusting the application
and the DSOs, which are loaded as the dependencies, to
their own and all other load addresses. There are two The dynamic linker has to perform a relocation for all
kinds of dependencies: symbols which are used at run-time and which are not
known at link-time to be defined in the same object as the
reference. Due to the way code is generated on some ar-
• Dependencies to locations which are known to be chitectures it is possible to delay the processing of some
in the own object. These are not associated with a relocations until the references in question are actually
specific symbol since the linker knows the relative used. This is on many architectures the case for calls
position of the location in the object. to functions. All other kinds of relocations always have
to be processed before the object can be used. We will
Note that applications do not have relative reloca- ignore the lazy relocation processing since this is just a
tions since the load address of the code is known method to delay the work. It eventually has to be done
at link-time and therefore the static linker is able to and so we will include it in our cost analysis. To actu-
perform the relocation. ally perform all the relocations before using the object is
used by setting the environment variable LD BIND NOW to
• Dependencies based on symbols. The reference of a non-empty value. Lazy relocation can be disabled for
the definition is generally, but not necessarily, in a an individual object by adding the -z now option to the
different object than the definition. linker command line. The linker will set the DF BIND NOW
flag in the DT FLAGS entry of the dynamic section to
mark the DSO. This setting cannot be undone without
The implementation of relative relocations is easy. The
relinking the DSOs, though, so this option should only
linker can compute the offset of the target destination in
be used if it is really wanted.
the object file at link-time. To this value the dynamic
linker only has to add the load address of the object and
The actual lookup process is repeated from start for each
store the result in the place indicated by the relocation. At
symbol relocation in each loaded object. Note that there
runtime the dynamic linker has to spend only a very small
can be many references to the same symbol in different
and constant amount of time which does not increase if
objects. The result of the lookup can be different for each
more DSOs are used.
of the objects so there can be no short cuts except for
caching results for a symbol in each object in case more
The relocation based on a symbol is much more compli-
than one relocation references the symbol. The lookup
cated. The ELF symbol resolution process was designed
scope mentioned in the steps below is an ordered list of
very powerful so that it can handle many different prob-
most loaded objects which can be different for each ob-
lems. All this powerful functionality adds to the com-
ject itself. The way the scope is computed is quite com-
plexity and run-time costs, though. Readers of the fol-
plex and not really relevant here so we refer the inter-
lowing description might question the decisions which
ested reader to the ELF specification. Important is that
led to this process. We cannot argue about this here; read-
the length of the scope is normally directly dependent
ers are referred to discussions of ELF. Fact is that symbol
on the number of loaded objects. This is another factor
relocation is a costly process and the more DSOs partic-
where reducing the number of loaded objects is increas-
ipate or the more symbols are defined in the DSOs, the
ing performance.
longer the symbol lookup takes.
3 We ignore the pre-linking support here which in many cases can The lookup process for one symbol proceeds in the fol-
reduce significantly or even eliminate the relocation costs. lowing steps:

Ulrich Drepper Version 3.0 5

Histogram for bucket list length in section [ 2] ’.hash’ (total of 1023 buckets):
Addr: 0x42000114 Offset: 0x000114 Link to section: [ 3] ’.dynsym’
Length Number % of total Coverage
0 132 12.9%
1 310 30.3% 15.3%
2 256 25.0% 40.6%
3 172 16.8% 66.0%
4 92 9.0% 84.2%
5 46 4.5% 95.5%
6 14 1.4% 99.7%
7 1 0.1% 100.0%
Average number of tests: successful lookup: 1.994080
unsuccessful lookup: 1.981427

Figure 3: Example Output for eu-readelf -I libc.so

Histogram for bucket list length in section [ 2] ’.hash’ (total of 191 buckets):
Addr: 0x00000114 Offset: 0x000114 Link to section: [ 3] ’.dynsym’
Length Number % of total Coverage
0 103 53.9%
1 71 37.2% 67.0%
2 16 8.4% 97.2%
3 1 0.5% 100.0%
Average number of tests: successful lookup: 1.179245
unsuccessful lookup: 0.554974

Figure 4: Example Output for eu-readelf -I libnss files.so

1. Determine the hash value for the symbol name. Note that there is no problem if the scope contains more
than one definition of the same symbol. The symbol
2. In the first/next object in the lookup scope: lookup algorithm simply picks up the first definition it
finds. This has some perhaps surprising consequences.
2.a Determine the hash bucket for the symbol us-
Assume DSO ‘A’ defines and references an interface and
ing the hash value and the hash table size in
DSO ‘B’ defines the same interface. If now ‘B’ precedes
the object.
‘A’ in the scope, the reference in ‘A’ will be satisfied
2.b Get the name offset of the symbol and using by the definition in ‘B’. It is said that the definition in
it as the NUL-terminated name. ‘B’ interposes the definition in ‘A’. This concept is very
2.c Compare the symbol name with the reloca- powerful since it allows more specialized implementation
tion name. of an interface to be used without replacing the general
code. One example for this mechanism is the use of the
2.d If the names match, compare the version names LD PRELOAD functionality of the dynamic linker where
as well. This only has to happen if both, the additional DSOs which were not present at link-time are
reference and the definition, are versioned. It introduced in run-time. But interposition can also lead
requires a string comparison, too. If the ver- to severe problems in ill-designed code. More in this in
sion name matches or no such comparison section 1.5.3.
is performed, we found the definition we are
looking for. Looking at the algorithm it can be seen that the perfor-
2.e If the definition does not match, retry with the mance of each lookup depends, among other factors, on
next element in the chain for the hash bucket. the length of the hash chains and the number of objects
in the lookup scope. These are the two loops described
2.f If the chain does not contain any further ele-
above. The lengths of the hash chains depend on the
ment there is no definition in the current ob-
number of symbols and the choice of the hash table size.
ject and we proceed with the next object in
Since the hash function used in the initial step of the algo-
the lookup scope.
rithm must never change these are the only two remaining
3. If there is no further object in the lookup scope the variables. Many linkers do not put special emphasis on
lookup failed. selecting an appropriate table size. The GNU linker tries
to optimize the hash table size for minimal lengths of the

6 Version 3.0 How To Write Shared Libraries

chains if it gets passed the -O option (note: the linker, not structures. Strings are stored in the C-format; they are
the compiler, needs to get this option). terminated by a NUL byte and no initial length field is
used. This means string comparisons has to proceed until
A note on the current implementation of the hash table op- a non-matching character is found or until the end of the
timization. The GNU binutils linker has a simple minded
string. This approach is susceptible to long strings with
heuristic which often favors small table sizes over short
chain length. For large projects this might very well in-
common prefixes. Unfortunately this is not uncommon.
crease the startup costs. The overall memory consumption
will be sometimes significantly reduces which might com-
namespace some_namespace {
pensate sooner or later but it is still advised to check the
class some_longer_class_name {
effectiveness of the optimization. A new linker implemen-
int member_variable;
tation is going to be developed and it contains a better algo-
public:
rithm.
some_longer_class_name (int p);
int the_getter_function (void);
To measure the effectiveness of the hashing two numbers };
}
are important:

• The average chain length for a successful lookup.

The name mangling scheme used by the GNU C++ com-
• The average chain length for an unsuccessful lookup. piler before version 3.0 used a mangling scheme which
put the name of a class member first along with a descrip-
tion of the parameter list and following it the other parts
It might be surprising to talk about unsuccessful lookups of the name such as namespaces and nested class names.
here but in fact they are the rule. Note that “unsuccess- The result is a name which distinguishable in the begin-
ful” means only unsuccessful in the current objects. Only ning if the member names are different. For the example
for objects which implement almost everything they get above the mangled names for the two members functions
looked in for is the successful lookup number more im- look like this figure 5.
portant. In this category there are basically only two ob-
jects on a Linux system: the C library and the dynamic In the new mangling scheme used in today’s gcc versions
linker itself. and all other compilers which are compatible with the
common C++ ABI the names start with the namespaces
Some versions of the readelf program compute the value and class names and end with the member names. Fig-
directly and the output is similar to figures 3 and 4. The ure 6 shows the result for the little example. The mangled
data in these examples shows us a number of things. Based names for the two member functions differs only after the
on the number of symbols (2027 versus 106) the chosen 43rd character. This is really bad performance-wise if the
table size is radically different. For the smaller table the two symbols should fall into the same hash bucket.4
linker can afford to “waste” 53.9% of the hash table en-
tries which contain no data. That’s only 412 bytes on Ada has similar problems. The standard Ada library for
a gABI-compliant system. If the same amount of over- gcc has all symbols prefixed with ada , then the pack-
head would be allowed for the libc.so binary the table age and sub-package names, followed by function name.
would be 4 kilobytes or more larger. That is a big dif- Figure 7 shows a short excerpt of the list of symbols from
ference. The linker has a fixed cost function integrated the library. The first 23 character are the same for all the
which takes the table size into account. names.

The increased relative table size means we have signifi- The length of the strings in both mangling schemes is
cantly shorter hash chains. This is especially true for the worrisome since each string has to be compared com-
average chain length for an unsuccessful lookup. The av- pletely when the symbol itself is searched for. The names
erage for the small table is only 28% of that of the large in the example are not extra ordinarily long either. Look-
table. ing through the standard C++ library one can find many
names longer than 120 characters and even this is not the
What these numbers should show is the effect of reduc- longest. Other system libraries feature names longer than
ing the number of symbols in the dynamic symbol ta- 200 characters and complicated, “well designed” C++
ble. With significantly fewer symbols the linker has a projects with many namespaces, templates, and nested
much better chance to counter the effects of the subopti- classes can feature names with more than 1,000 charac-
mal hashing function. ters. One plus point for design, but minus 100 points for
performance.
Another factor in the cost of the lookup algorithm is con- 4 Some people suggested “Why not search from the back?”. Think
nected with the strings themselves. Simple string com- about it, these are C strings, not PASCAL strings. We do not know the
parison is used on the symbol names which are stored length and therefore would have to read every single character of the
in a string table associated with the symbol table data string to determine the length. The result would be worse.

Ulrich Drepper Version 3.0 7

__Q214some_namespace22some_longer_class_namei
the_getter_function__Q214some_namespace22some_longer_class_name

Figure 5: Mangled names using pre-gcc 3 scheme

_ZN14some_namespace22some_longer_class_nameC1Ei
_ZN14some_namespace22some_longer_class_name19the_getter_functionEv

Figure 6: Mangled names using the common C++ ABI scheme

ada__calendar__delays___elabb
ada__calendar__delays__timed_delay_nt
ada__calendar__delays__to_duration

Figure 7: Names from the standard Ada library

With the knowledge of the hashing function and the de- bols’, ‘length of the symbol strings’, ‘number and length
tails of the string lookup let us look at a real-world exam- of common prefixes’,‘number of DSOs’, and ‘hash table
ple: OpenOffice.org. The package contains 144 separate size optimization’ can reduce the costs dramatically. In
DSOs. During startup about 20,000 relocations are per- general the percentage spent on relocations of the time
formed. The number of string comparisons needed dur- the dynamic linker uses during startup is around 50-70%
ing the symbol resolution can be used as a fair value for if the binary is already in the file system cache, and about
the startup overhead. We compute an approximation of 20-30% if the file has to be loaded from disk.5 It is there-
this value now. fore worth spending time on these issues and in the re-
mainder of the text we will introduce methods to do just
The average chain length for unsuccessful lookup in all that. So far to remember: pass -O1 to the linker to gener-
DSOs of the OpenOffice.org 1.0 release on IA-32 is 1.1931. ate the final product.
This means for each symbol lookup the dynamic linker
has to perform on average 72 × 1.1931 = 85.9032 string 1.5.3 Lookup Scope
comparisons. For 20,000 symbols the total is 1,718,064
string comparisons. The average length of an exported
symbol defined in the DSOs of OpenOffice.org is 54.13. The lookup scope has so far been described as an ordered
Even if we are assuming that only 20% of the string is list of most loaded object. While this is correct it has also
searched before finding a mismatch (which is an opti- been intentionally vague. It is now time to explain the
mistic guess since every symbol name is compared com- lookup scope in more detail.
pletely at least once to match itself) this would mean a to-
tal of more then 18.5 million characters have to be loaded The lookup scope consists in fact of up to three parts.
from memory and compared. No wonder that the startup The main part is the global lookup scope. It initially
is so slow, especially since we ignored other costs. consists of the executable itself and all its dependencies.
The dependencies are added in breadth-first order. That
To compute number of lookups the dynamic linker per- means first the dependencies of the executable are added
forms one can use the help of the dynamic linker. If the in the order of their DT NEEDED entries in the executable’s
environment variable LD DEBUG is set to symbols one dynamic section. Then the dependencies of the first de-
only has to count the number of lines which start with pendency are added in the same fashion. DSOs already
symbol=. It is best to redirect the dynamic linker’s out- loaded are skipped; they do not appear more than once
put into a file with LD DEBUG OUTPUT. The number of on the list. The process continues recursively and it will
string comparisons can then be estimate by multiplying stop at some point since there are only a limited number
the count with the average hash chain length. Since the of DSOs available. The exact number of DSOs loaded
collected output contains the name of the file which is this way can vary widely. Some executables depend on
looked at it would even be possible to get more accurate only two DSOs, others on 200.
results by multiplying with the exact hash chain length
for the object. If an executable has the DF SYMBOLIC flag set (see sec-
tion 2.2.7) the object with the reference is added in front
Changing any of the factors ‘number of exported sym- 5 These numbers assume pre-linking is not used.

8 Version 3.0 How To Write Shared Libraries

of the global lookup scope. Note, only the object with global scope like this:
the reference itself is added in front, not its dependen-
cies. The effects and reasons for this will be explained
app → libone.so → libdl.so → libc.so
later.

A more complicated modification of the lookup scope If now libtwo.so is loaded, the additional local scope
happens when DSOs are loaded dynamic using dlopen. could be like this:
If a DSO is dynamically loaded it brings in its own set
of dependencies which might have to be searched. These
objects, starting with the one which was requested in the libdynamic.so → libtwo.so → libc.so
dlopen call, are appended to the lookup scope if the
object with the reference is among those objects which This local scope is searched after the global scope, pos-
have been loaded by dlopen. That means, those objects sibly with the exception of libdynamic.so which is
are not added to the global lookup scope and they are searched first for lookups in this very same DSO if the
not searched for normal lookups. This third part of the DF DYNAMIC flag is used. But what happens if the sym-
lookup scope, we will call it local lookup scope, is there- bol duplicate is required in libdynamic.so? After
fore dependent on the object which has the reference. all we said so far the result is always: the definition in
libone.so is found since libtwo.so is only in the lo-
The behavior of dlopen can be changed, though. If the cal scope which is searched after the global scope. If the
function gets passed the RTLD GLOBAL flag, the loaded two definitions are incompatible the program is in trou-
object and all the dependencies are added to the global ble.
scope. This is usually a very bad idea. The dynami-
cally added objects can be removed and when this hap- This can be changed with a recent enough GNU C library
pens the lookups of all other objects is influenced. The by ORing RTLD DEEPBIND to the flag word passed as the
entire global lookup scope is searched before the dynam- second parameter to dlopen. If this happens, the dy-
ically loaded object and its dependencies so that defini- namic linker will search the local scope before the global
tions would be found first in the global lookup scope ob- scope for all objects which have been loaded by the call
ject before definitions in the local lookup scope. If the to dlopen. For our example this means the search or-
dynamic linker does the lookup as part of a relocation der changes for all lookups in the newly loaded DSOs
this additional dependency is usually taken care of auto- libdynamic.so and libtwo.so, but not for libc.so
matically, but this cannot be arranged if the user looks up since this DSO has already been loaded. For the two af-
symbols in the lookup scope with dlsym. fected DSOs a reference to duplicate will now find the
definition in libtwo.so. In all other DSOs the definition
And usually there is no reason to use RTLD GLOBAL. For in libone.so would be found.
reasons explained later it is always highly advised to cre-
ate dependencies with all the DSOs necessary to resolve While this might sound like a good solution for handling
all references. RTLD GLOBAL is often used to provide im- compatibility problems this feature should only be used
plementations which are not available at link time of a if it cannot be avoided. There are several reasonse for
DSO. Since this should be avoided the need for this flag this:
should be minimal. Even if the programmer has to jump
through some hoops to work around the issues which are
solved by RTLD GLOBAL it is worth it. The pain of debug- • The change in the scope affects all symbols and all
ging and working around problems introduced by adding the DSOs which are loaded. Some symbols might
objects to the global lookup scope is much bigger. have to be interposed by definitions in the global
scope which now will not happen.
The dynamic linker in the GNU C library knows since
• Already loaded DSOs are not affected which could
September 2004 one more extension. This extension helps
cause unconsistent results depending on whether
to deal with situations where multiple definitions of sym-
the DSO is already loaded (it might be dynamically
bols with the same name are not compatible and there-
loaded, so there is even a race condition).
fore cannot be interposed and expected to work. This is
usally a sign of design failures on the side of the peo- • LD PRELOAD is ineffective for lookups in the dy-
ple who wrote the DSOs with the conflicting definitions namically loaded objects since the preloaded ob-
and also failure on the side of the application writer who jects are part of the global scope, having been added
depends on these incompatible DSOs. We assume here right after the executable. Therefore they are looked
that an application app is linked with a DSO libone.so at only after the local scope.
which defines a symbol duplicate and that it dynami-
cally loads a DSO libdynamic.so which depends on • Applications might expect that local definitions are
another DSO libtwo.so which also defines a symbol always preferred over other definitions. This (and
duplicate. When the application starts it might have a the previous point) is already partly already a prob-
lem with the use of DF SYMBOLIC but since this

Ulrich Drepper Version 3.0 9

 flag should not be used either, the arguments are of the location in the GOT relative to the PIC register
still valid. value (%ebx) is known at link-time. Therefore the text
segment does not have to be changed, only the GOT.6
• If any of the implicitly loaded DSOs is loaded ex-
plicitly afterward, its lookup scope will change. The situation for the function call is similar. The function
• Lastly, the flag is not portable. bar is not called directly. Instead control is transferred
to a stub for bar in the PLT (indicated by bar@PLT). For
IA-32 the PLT itself does not have to be modified and can
The RTLD DEEPBIND flag should really only be used as be placed in a read-only segment, each entry is 16 bytes
a last resort. Fixing the application to not depend on the in size. Only the GOT is modified and each entry consists
flag’s functionality is the much better solution. of 4 bytes. The structure of the PLT in an IA-32 DSO
looks like this:
1.5.4 GOT and PLT
.PLT0:pushl 4(%ebx)
The Global Offset Table (GOT) and Procedure Linkage jmp *8(%ebx)
Table (PLT) are the two data structures central to the ELF nop; nop
nop; nop
run-time. We will introduce now the reasons why they
.PLT1:jmp *name1@GOT(%ebx)
are used and what consequences arise from that. pushl $offset1
jmp .PLT0@PC
Relocations are created for source constructs like .PLT2:jmp *name2@GOT(%ebx)
pushl $offset2
jmp .PLT0@PC
extern int foo;
extern int bar (int);
int call_bar (void) {
return bar (foo);
This shows three entries, there are as many as needed,
}
all having the same size. The first entry, labeled with
.PLT0, is special. It is used internally as we will see.
All the following entries belong to exactly one function
The call to bar requires two relocations: one to load the symbol. The first instruction is an indirect jump where
value of foo and another one to find the address of bar. the address is taken from a slot in the GOT. Each PLT en-
If the code would be generated knowing the addresses of try has one GOT slot. At startup time the dynamic linker
the variable and the function the assembler instructions fills the GOT slot with the address pointing to the sec-
would directly load from or jump to the address. For IA- ond instruction of the appropriate PLT entry. I.e., when
32 the code would look like this: the PLT entry is used for the first time the jump ends at
the following pushl instruction. The value pushed on
the stack is also specific to the PLT slot and it is the off-
pushl foo set of the relocation entry for the function which should
call bar be called. Then control is transferred to the special first
PLT entry which pushes some more values on the stack
and finally jumps into the dynamic linker. The dynamic
linker has do make sure that the third GOT slot (offset
This would encode the addresses of foo and bar as part 8) contains the address of the entry point in the dynamic
of the instruction in the text segment. If the address is linker. Once the dynamic linker has determined the ad-
only known to the dynamic linker the text segment would dress of the function it stores the result in the GOT entry
have to be modified at run-time. According to what we which was used in the jmp instruction at the beginning of
learned above this must be avoided. the PLT entry before jumping to the found function. This
has the effect that all future uses of the PLT entry will not
Therefore the code generated for DSOs, i.e., when using go through the dynamic linker, but will instead directly
-fpic or -fPIC, looks like this:
transfer to the function. The overhead for all but the first
call is therefore “only” one indirect jump.
movl foo@GOT(%ebx), %eax
pushl (%eax) The PLT stub is always used if the function is not guaran-
call bar@PLT teed to be defined in the object which references it. Please
note that a simple definition in the object with the refer-
6 There is one more advantage of using this scheme. If the instruc-

tion would be modified we would need one relocation per load/store

The address of the variable foo is now not part of the in- instruction. By storing the address in the GOT only one relocation is
struction. Instead it is loaded from the GOT. The address needed.

10 Version 3.0 How To Write Shared Libraries

ence is not enough to avoid the PLT entry. Looking at linear process. Like all sorting algorithms the run-time is
the symbol lookup process it should be clear that the def- at least O(n log n) and since this is actually a topological
inition could be found in another object (interposition) sort the value is even higher. And what is more: since
in which case the PLT is needed. We will later explain the order at startup need not be the same as the order
exactly when and how to avoid PLT entries. at shutdown (when finalizers have to be run) the whole
process has to be repeated.
How exactly the GOT and PLT is structured is architecture-
specific, specified in the respective psABI. What was said So we have again a cost factor which is directly depend-
here about IA-32 is in some form applicable to some ing on the number of objects involved. Reducing the
other architectures but not for all. For instance, while the number helps a bit even though the actual costs are nor-
PLT on IA-32 is read-only it must be writable for other mally much less than that of the relocation process.
architectures since instead of indirect jumps using GOT
values the PLT entries are modified directly. A reader At this point it is useful to look at the way to correctly
might think that the designers of the IA-32 ABI made a write constructors and destructors for DSOs. Some sys-
mistake by requiring a indirect, and therefore slower, call tems had the convention that exported functions named
instead of a direct call. This is no mistake, though. Hav- init and fini are automatically picked as constructor
ing a writable and executable segment is a huge security and destructor respectively. This convention is still fol-
problem since attackers can simply write arbitrary code lowed by GNU ld and using functions with these names
into the PLT and take over the program. We can anyhow on a Linux system will indeed cause the functions used
summarize the costs of using GOT and PLT like this: in these capacities. But this is totally, 100% wrong!

By using these functions the programmer overwrites what-

• every use of a global variable which is exported
ever initialization and destruction functionality the sys-
uses a GOT entry and loads the variable values in-
tem itself is using. The result is a DSO which is not
directly;
fully initialized and this sooner or later leads to a catas-
• each function which is called (as opposed to refer- trophy. The correct way of adding constructors and de-
enced as a variable) which is not guaranteed to be structors is by marking functions with the constructor
defined in the calling object requires a PLT entry. and destructor function attribute respectively.
The function call is performed indirectly by trans-
ferring control first to the code in the PLT entry
void
which in turn calls the function.
__attribute ((constructor))
• for some architectures each PLT entry requires at init_function (void)
least one GOT entry. {
...
}
Avoiding a jump through the PLT therefore removes on
IA-32 16 bytes of text and 4 bytes of data. Avoiding the void
GOT when accessing a global variable saves 4 bytes of __attribute ((destructor))
data and one load instruction (i.e., at least 3 bytes of code fini_function (void)
and cycles during the execution). In addition each GOT {
entry has a relocation associated with the costs described ...
}
above.

1.5.5 Running the Constructors

These functions should not be exported either (see sec-
tions 2.2.2 and 2.2.3) but this is just an optimization.
Once the relocations are performed the DSOs and the ap-
With the functions defined like this the runtime will ar-
plication code can actually be used. But there is one more
range that they are called at the right time, after perform-
thing to do: optionally the DSOs and the application must
ing whatever initialization is necessary before.
be initialized. The author of the code can define for each
object a number of initialization functions which are run
1.6 Summary of the Costs of ELF
before the DSO is used by other code. To perform the ini-
tialization the functions can use code from the own object
and all the dependencies. To make this work the dynamic We have now discussed the startup process and how it is
linker must make sure the objects are initialized in the affected by the form of the binaries. We will now summa-
correct order, i.e., the dependencies of an object must be rize the various factors so that we later on can determine
initialized before the object. the benefits of an optimization more easily.
To guarantee that the dynamic linker has to perform a
topological sort in the list of objects. This sorting is no Code Size As everywhere, a reduced size for code with

Ulrich Drepper Version 3.0 11

$ env LD_DEBUG=statistics /bin/echo ’+++ some text +++’
...:
...: run-time linker statistics:
...: total startup time in dynamic loader: 748696 clock cycles
...: time needed for relocation: 378004 clock cycles (50.4%)
...: number of relocations: 133
...: number of relocations from cache: 5
...: time needed to load objects: 193372 clock cycles (25.8%)
+++ some text +++
...:
...: run-time linker statistics:
...: final number of relocations: 188
...: final number of relocations from cache: 5

Figure 8: Gather Startup Statistics

the same semantics often means higher efficiency Number of Symbols The number of exported and unde-
and performance. Smaller ELF binaries need less fined symbols determines the size of the dynamic
memory at run-time. symbol table, the hash table, and the average hash
In general the programmer will always generate the table chain length. The normal symbol table is not
best code possible and we do not cover this further. used at run-time and it is therefore not necessary
But it must be known that every DSO includes a to strip a binary of it. It has no impact on perfor-
certain overhead in data and code. Therefore fewer mance.
DSOs means smaller text. Additionally, fewer exported symbols means fewer
Number of Objects The fact that a smaller number of chances for conflicts when using pre-linking (not
objects containing the same functionality is bene- covered further).
ficial has been mentioned in several places:
Length of Symbol Strings Long symbol lengths cause
• Fewer objects are loaded at run-time. This often unnecessary costs. A successful lookup of a
directly translates to fewer system call. In the symbol must match the whole string and compar-
GNU dynamic linker implementation loading ing dozens or hundreds of characters takes time.
a DSO requires 8 system calls, all of them can Unsuccessful lookups suffer if common prefixes
be potentially quite expensive. are long as in the new C++ mangling scheme. In
• Related, the application and the dependencies any case do long symbol names cause large string
with additional dependencies must record the tables which must be present at run-time and thereby
names of the dependencies. This is not a ter- is adding costs in load time and in use of address
ribly high cost but certainly can sum up if space which is an issue for 32-bit machines.
there are many dozens of dependencies.
• The lookup scope grows. This is one of the Number of Relocations Processing relocations constitute
dominating factors in cost equation for the re- the majority of work during start and therefore any
locations. reduction is directly noticeable.
• More objects means more symbol tables which
Kind of Relocations The kind of relocations which are
in turn normally means more duplication. Un-
needed is important, too, since processing a rela-
defined references are not collapsed into one
tive relocation is much less expensive than a nor-
and handling of multiple definitions have to
mal relocation. Also, relocations against text seg-
be sorted out by the dynamic linker.
ments must be avoided.
Moreover, symbols are often exported from a
DSO to be used in another one. This would Placement of Code and Data All executable code should
not have to happen if the DSOs would be merged. be placed in read-only memory and the compiler
• The sorting of initializers/finalizers is more normally makes sure this is done correctly. When
complicated. creating data objects it is mostly up to the user
• In general does the dynamic linker have some to make sure it is placed in the correct segment.
overhead for each loaded DSO per process. Ideally data is also read-only but this works only
Every time a new DSO is requested the list of for constants. The second best choice is a zero-
already loaded DSOs must be searched which initialized variable which does not have to be ini-
can be quite time consuming since DSOs can tialized from file content. The rest has to go into
have many aliases. the data segment.

12 Version 3.0 How To Write Shared Libraries

In the following we will not cover the first two points across successive runs of the program. The time mea-
given here. It is up to the developer of the DSO to de- surements not. Even in a single-user mode with no other
cide about this. There are no small additional changes to programs running there would be differences since the
make the DSO behave better, these are fundamental de- cache and main memory has to be accessed. It is there-
sign decisions. We have voiced an opinion here, whether fore necessary to average the run-time over multiple runs.
it is has any effect remains to be seen.
It is obviously also possible to count the relocations with-
1.7 Measuring ld.so Performance out running the program. Running readelf -d on the
binary shows the dynamic section in which the DT RELSZ,
DT RELENT, DT RELCOUNT, and DT PLTRELSZ entries are
To perform the optimizations it is useful to quantify the interesting. They allow computing the number of normal
effect of the optimizations. Fortunately it is very easy to and relative relocations as well as the number of PLT en-
do this with glibc’s dynamic linker. Using the LD DEBUG tries. If one does not want to do this by hand the relinfo
environment variable it can be instructed to dump in- script in appendix A can be used.
formation related to the startup performance. Figure 8
shows an example invocation, of the echo program in
this case. 2 Optimizations for DSOs
The output of the dynamic linker is divided in two parts.
The part before the program’s output is printed right be- In this section we describe various optimizations based
fore the dynamic linker turns over control to the appli- on C or C++ variables or functions. The choice of vari-
cation after having performed all the work we described able or function, unless explicitly said, is made deliber-
in this section. The second part, a summary, is printed ately since many of the implementations apply to the one
after the application terminated (normally). The actual or the other. But there are some architectures where func-
format might vary for different architectures. It includes tions are handled like variables. This is mainly the case
the timing information only on architectures which pro- for embedded RISC architectures like SH-3 and SH-4
vide easy access to a CPU cycle counter register (modern which have limitations in the addressing modes they pro-
IA-32, IA-64, x86-64, Alpha in the moment). For other vide which make it impossible to implement the function
architectures these lines are simply missing. handling as for other architectures. In most cases it is
no problem to apply the optimizations for variables and
The timing information provides absolute values for the functions at the same time. This is what in fact should be
total time spend during startup in the dynamic linker, the done all the time to achieve best performance across all
time needed to perform relocations, and the time spend architectures.
in the kernel to load/map binaries. In this example the
relocation processing dominates the startup costs with The most important recommendation is to always use
more than 50%. There is a lot of potential for optimiza- -fpic or -fPIC when generating code which ends up in
tions here. The unit used to measure the time is CPU DSOs. This applies to data as well as code. Code which
cycles. This means that the values cannot even be com- is not compiled this way almost certainly will contain text
pared across different implementations of the same ar- relocations. For these there is no excuse. Text relocations
chitecture. E.g., the measurement for a PentiumRM III and requires extra work to apply in the dynamic linker. And
a PentiumRM 4 machine will be quite different. But the argumentation saying that the code is not shared because
measurements are perfectly suitable to measure improve- no other process uses the DSO is invalid. In this case it is
ments on one machine which is what we are interested not useful to use a DSO in the first place; the code should
here. just be added to the application code.

Since relocations play such a vital part of the startup per- Some people try to argue that the use of -fpic/-fPIC
formance some information on the number of relocations on some architectures has too many disadvantages. This
is printed. In the example a total of 133 relocations are is mainly brought forward in argumentations about IA-
performed, from the dynamic linker, the C library, and the 32. Here the use of %ebx as the PIC register deprives
executable itself. Of these 5 relocations could be served the compiler of one of the precious registers it could use
from the relocation cache. This is an optimization imple- for optimization. But this is really not that much of a
mented in the dynamic linker to handle the case of mul- problem. First, not having %ebx available was never a
tiple relocations against the same symbol more efficient. big penalty. Second, in modern compilers (e.g., gcc after
After the program itself terminated the same information release 3.1) the handling of the PIC register is much more
is printed again. The total number of relocations here is flexible. It is not always necessary to use %ebx which
higher since the execution of the application code caused can help eliminating unnecessary copy operations. And
a number, 55 to be exact, of run-time relocations to be third, by providing the compiler with more information as
performed. explained later in this section a lot of the overhead in PIC
can be removed. This all combined will lead to overhead
The number of relocations which are processed is stable which is in most situations not noticeable.

Ulrich Drepper Version 3.0 13

When gcc is used, the options -fpic/-fPIC also tell the used at all times unless it is absolutely necessary to use
compiler that a number of optimizations which are pos- -fPIC. The linker will fail and write out a message when
sible for the executable cannot be performed. This has to this point is reached and one only has to recompile the
do with symbol lookups and cutting it short. Since the code.
compiler can assume the executable to be the first object
in the lookup scope it knows that all references of global When writing assembler code by hand it is easy to miss
symbols known to be defined in the executable are re- cases where position independent code sequences must
solved locally. Access to locally defined variable could be used. The non-PIC sequences look and actually are
be done directly, without using indirect access through simpler and more natural. Therefore it is extremely im-
the GOT. This is not true for DSOs: the DSOs can be portant to in these case to check whether the DSO is
later in the lookup scope and earlier objects might be in- marked to contain text relocations. This is easy enough
terposed. It is therefore mandatory to compile all code to do:
which can potentially end up in a DSO with -fpic/-fPIC
since otherwise the DSO might not work correctly. There readelf -d binary | grep TEXTREL
is no compiler option to separate this optimization from
the generation of position-independent code. If this produces any output text relocations are present
and one better starts looking what causes them.
Which of the two options, -fpic or -fPIC, have to be
used must be decided on a case-by-case basis. For some 2.1 Data Definitions
architectures there is no difference at all and people tend
to be careless about the use. For most RISC there is a big
difference. As an example, this is the code gcc generates Variables can be defined in C and C++ in several different
for SPARC to read a global variable global when using ways. Basically there are three kinds of definitions:
-fpic:

Common Common variables are more widely used FOR-

sethi %hi(_GLOBAL_OFFSET_TABLE_-4),%l7 TRAN but they got used in C and C++ as well to
call .LLGETPC0
work around mistakes of programmers. Since in
add %l7,%lo(_GLOBAL_OFFSET_TABLE_+4),%l7
the early days people used to drop the extern key-
ld [%l7+global],%g1
ld [%g1],%g1 word from variable definitions, in the same way it
is possible to drop it from function declaration, the
compiler often has multiple definitions of the same
variable in different files. To help the poor and
And this is the code sequence if -fPIC is used: clueless programmer the C/C++ compiler normally
generates common variables for uninitialized defi-
nitions such as
sethi %hi(_GLOBAL_OFFSET_TABLE_-4),%l7 int foo;
call .LLGETPC0
add %l7,%lo(_GLOBAL_OFFSET_TABLE_+4),%l7 For common variables there can be more than one
sethi %hi(global),%g1 definition and they all get unified into one location
or %g1,%lo(global),%g1 in the output file. Common variables are always
ld [%l7+%g1],%g1 initialized with zero. This means their value does
ld [%g1],%g1 not have to be stored in an ELF file. Instead the
file size of a segment is chosen smaller than the
memory size as described in 1.4.

In both cases %l7 is loaded with the address of the GOT Uninitialized If the programmer uses the compiler com-
first. Then the GOT is accessed to get the address of mand line option -fno-common the generated code
global. While in the -fpic case one instruction is suf- will contain uninitialized variables instead of com-
ficient, three instructions are needed in the -fPIC case. mon variables if a variable definition has no ini-
The -fpic option tells the compiler that the size of the tializer. Alternatively, individual variables can be
GOT does not exceed an architecture-specific value (8kB marked like this:
in case of SPARC). If only that many GOT entries can
int foo attribute ((nocommon));
be present the offset from the base of the GOT can be
encoded in the instruction itself, i.e., in the ld instruc- The result at run-time is the same as for common
tion of the first code sequence above. If -fPIC is used variable, no value is stored in the file. But the rep-
no such limit exists and so the compiler has to be pes- resentation in the object file is different and it al-
simistic and generate code which can deal with offsets of lows the linker to find multiple definitions and flag
any size. The difference in the number of instructions in them as errors. Another difference is that it is pos-
this example correctly suggests that the -fpic should be sible to define aliases, i.e., alternative names, for

14 Version 3.0 How To Write Shared Libraries

 uninitialized variables while this is not possible for numeric value zero. The test in the function get s has
common variables. to be changed as well but the resulting code is not less or
With recent gcc versions there is another method to more efficient than the old code.
create uninitialized variables. Variables initialized
with zero are stored this way. Earlier gcc versions By simple transformations like that it is often possible
stored them as initialized variables which took up to avoid creating initialized variables and instead using
space in the file. This is a bit cumbersome for vari- common or uninitialized variables. This saves disk space
ables with structured types. So, sticking with the and eventually improves startup times. The transforma-
per-variable attribute is probably the best way. tion is not limited to boolean values. It is sometimes pos-
sible to do it for variables which can take on more than
Initialized The variable is defined and initialized to a two values, especially enumeration values. When defin-
programmer-defined value. In C: ing enums one should always put the value, which is most
int foo = 42; often used as initializer, first in the enum definition. I.e.
In this case the initialization value is stored in the enum { val1, val2, val3 };
file. As described in the previous case initializa-
tions with zero are treated special by some compil- should be rewritten as
ers.
enum { val3, val1, val2 };
Normally there is not much the user has to do to create
if val3 is the value most often used for initializations.
optimal ELF files. The compiler will take care of avoid-
To summarize, it is always preferable to add variables
ing the initializers. To achieve the best results even with
as uninitialized or initialized with zero as opposed to as
old compilers it is desirable to avoid explicit initializa-
initialized with a value other than zero.
tions with zero if possible. This creates normally com-
mon variables but if combined with gcc’s -fno-common
flag the same reports about multiple definitions one would 2.2 Export Control
get for initialized variables can be seen.

There is one thing the programmer is responsible for. As When creating a DSO from a collection of object files the
an example look at the following code: dynamic symbol table will by default contain all the sym-
bols which are globally visible in the object files. In most
cases this set is far too large. Only the symbols which are
bool is_empty = true; actually part of the ABI should be exported. Failing to
char s[10]; restrict the set of exported symbols are numerous draw-
backs:
const char *get_s (void) {
return is_empty ? NULL : s;
} • Users of the DSO could use interfaces which they
are not supposed to. This is problematic in revi-
sions of the DSO which are meant to be binary
compatible. The correct assumption of the DSO
The function get s uses the boolean variable is empty
developer is that interfaces, which are not part of
to decide what to do. If the variable has its initial value
the ABI, can be changed arbitrarily. But there are
the variable s is not used. The initialization value of
always users who claim to know better or do not
is empty is stored in the file since the initialize is non-
care about rules.
zero. But the semantics of is empty is chosen arbitrar-
ily. There is no requirement for that. The code could • According to the ELF lookup rules all symbols in
instead be rewritten as: the dynamic symbol table can be interposed (un-
less the visibility of the symbol is restricted). I.e.,
bool not_empty = false;
definitions from other objects can be used. This
char s[10]; means that local references cannot be bound at link
time. If it is known or intended that the local defi-
const char *get_s (void) { nition should always be used the symbol in the ref-
return not_empty ? s : NULL; erence must not be exported or the visibility must
} be restricted.

• The dynamic symbol table and its string table are

available at run-time and therefore must be loaded.
Now the semantics of the control variable is reversed. It This can require a significant amount of memory,
is initialized with false which is guaranteed to have the even though it is read-only. One might think that

Ulrich Drepper Version 3.0 15

 the size is not much of an issue but if one exam- done by defining it with static. This is for many peo-
ines the length of the mangled names of C++ vari- ple obvious but unfortunately not for all. Many consider
ables or functions, it becomes obvious that this is adding static as optional. This is true when consider-
not the case. In addition we have the run-time costs ing only the C semantics of the code.
of larger symbol tables which we discussed in the
previous section. If in our example neither last or next are needed out-
side the file we can change the source to:
We will now present a number of possible solutions for
the problem of exported interfaces. Some of them solve static int last;
the same problem in slightly different ways. We will say
which method should be preferred. The programmer has static int next (void) {
to make sure that whatever is used is available on the tar- return ++last;
get system. }

In the discussions of the various methods we will use one int index (int scale) {
example: return next () << scale;
}

int last;

int next (void) { Compiled in the same way as before we see that all the re-
return ++last; locations introduced by our example code vanished. I.e.,
}
we are left with six relocations and three PLT entries. The
int index (int scale) {
code to access last now looks like this:
return next () << scale;
}
movl last@GOTOFF(%ebx), %eax
incl %eax
movl %eax, last@GOTOFF(%ebx)
Compiled on a IA-32 Linux machine a DSO with only
this code (plus startup code etc) contains seven reloca-
tions, two of which are relative, and four PLT entries (use
the relinfo script). We will see how we can improve on The code improved by avoiding the step which loads the
this. Four of the normal and both relative relocations as address of the variable from the GOT. Instead, both mem-
well as three PLT entries are introduced by the additional ory accesses directly address the variable in memory. At
code used by the linker to create the DSO. The actual ex- link-time the variable location has a fixed offset from the
ample code creates only one normal relocation for last PIC register, indicated symbolically by last@GOTOFF.
and one PLT entry for next. To increment and read the By adding the value to the PIC register value we get the
variable last in next the compiler generates code like address of last. Since the value is known at link-time
this construct does not need a relocation at run-time.
movl last@GOT(%ebx), %edx The situation is similar for the call to next. The IA-32 ar-
movl (%edx), %eax
chitecture, like many others, know a PC-relative address-
incl %eax
movl %eax, (%edx)
ing mode for jumps and calls. Therefore the compiler can
generate a simple jump instruction

and the call of next is compiled to call next

call next@PLT
and the assembler generates a PC-relative call. The dif-
ference between the address of the instruction following
These code fragments were explained in section 1.5.4. the call and the address of next is constant at link-time
and therefore also does not need any relocation. Another
advantage is that, in the case of IA-32, the PIC register
2.2.1 Use static
does not have to be set up before the jump. If the com-
piler wouldn’t know the jump target is in the same DSO
The easiest way to not export a variable or function is to the PIC register would have to be set up. Other architec-
the define it file file-local scope. In C and C++ this is tures have similar requirements.

16 Version 3.0 How To Write Shared Libraries

The generated code is optimal. The compiler might even symbol can accidentally be exported because an appro-
consider inlining some code if it finds that this is bene- priate declaration etc is missing. In some situations this
ficial. It is always advised that the programmer places can prevent bad surprises.7
the various variable and function definitions in the same
file as the references and then define the referenced ob- 2.2.3 Define Per-Symbol Visibility
jects as static. When generating the production bina-
ries it might even be desirable to merge as many input
files as possible together to mark as many objects as pos- Instead of changing the default visibility the programmer
sible static. Unless one is comfortable with one giant can choose to define to hide individual symbols. Or, if
file there is a limit on how many functions can be grouped the default visibility is hidden, make specific symbols ex-
together. It is not necessary to continue the process ad in- portable by setting the visibility to default.
finitum since there are other ways to achieve the same
result (minus inlining). Since the C language does not provide mechanisms to
define the visibility of a function or variable gcc resorts
once more to using attributes:
2.2.2 Define Global Visibility

int last
The next best thing to using static is to explicitly de- __attribute__ ((visibility ("hidden")));
fine the visibility of objects in the DSO. The generic ELF
ABI defines visibility of symbols. The specification de- int
fines four classes of which here only two are of interest. __attribute__ ((visibility ("hidden")))
STV DEFAULT denotes the normal visibility. The symbol next (void) {
is exported and can be interposed. The other interesting return ++last;
class is denoted by STV HIDDEN. Symbols marked like }
this are not exported from the DSO and therefore can-
not be used from other objects. There are a number of int index (int scale) {
return next () << scale;
different methods to define visibility.
}
Starting with version 4.0, gcc knows about a the com-
mand line option -fvisibility. It takes a parameter
and the valid forms are these: This defines the variable last and the function next
as hidden. All the object files which make up the DSO
which contains this definition can use these symbols. I.e.,
-fvisibility=default
while static restricts the visibility of a symbol to the
-fvisibility=hidden
-fvisibility=internal file it is defined in, the hidden attribute limits the visibil-
-fvisibility=protected ity to the DSO the definition ends up in. In the example
above the definitions are marked. This does not cause any
harm but it is in any case necessary to mark the declara-
tion. In fact it is more important that the declarations are
Only the first two should ever be used. The default is marked appropriately since it is mainly the code gener-
unsurprisingly default since this is the behavior of the ated for in a reference that is influenced by the attribute.
compiler before the introduction of this option. When
-fvisibility=hidden is specified gcc changes the de- Instead of adding an visibility attribute to each declara-
fault visibility of all defined symbols which have no ex- tion or definition, it is possible to change the default tem-
plicit assignment of visibility: all symbols are defined porarily for all definitions and declarations the compiler
with STV HIDDEN unless specified otherwise. This op- sees at this time. This is mainly useful in header files
tion has to be used with caution since unless the DSO since it reduces changes to a minimum but can also be
is prepared by having all APIs marked as having default useful for definitions. This compiler feature was also in-
visibility, the generated DSO will not have a single ex- troduced in gcc 4.0 and is implemented using a pragma:8
ported symbol. This is usually not what is wanted.
#pragma GCC visibility push(hidden)
In general it is the preference of the author which decides int last;
whether -fvisibility=hidden should be used. If it
is not used, symbols which are not to be exported need int
to be marked in one way or another. The next section
7 Accidentally exporting symbol can mean that programs can use
will go into details. In case the option is used all ex-
and get dependent on them. Then it is hard to remove the symbol again
ported functions need to be declared as having visibility for binary compatibility reasons.
default which usually means the header files are sig- 8 Note: ISO C99 introduced Pragma which allows using pragmas

nificantly uglified. On the other hand it means that no in macros.

Ulrich Drepper Version 3.0 17

next (void) { compared for equality. This rule would be violated with a
return ++last; fast and simple-minded implementation of the protected
} visibility. Assume an application which references a pro-
#pragma GCC visibility pop tected function in a DSO. Also in the DSO is another
function which references said function. The pointer in
int index (int scale) { the application points to the PLT entry for the function
return next () << scale; in the application’s PLT. If a protected symbol lookup
}
would simply return the address of the function inside
the DSO the addresses would differ.

In programming environments without this requirement

As in the example using the attributes, last and next on function pointers the use of the protected visibility
are both defined with hidden visibility while index is would be useful and fast. But since there usually is only
defined with default visibility (assuming this is the de- one implementation of the dynamic linker on the sys-
fault currently in use). As the pragma syntax suggests, it tem and this implementation has to handle C programs
is possible to nest the pragmas with the expected result. as well, the use of protected is highly discouraged.

In case the -fvisibility=hidden command line op- There are some exceptions to these rules. It is possible
tion is used, individual symbols can be marked as ex- to create ELF binaries with non-standard lookup scopes.
portable by using the same syntax as presented in this The simplest example is the use of DF SYMBOLIC (or of
section, except with default in place of hidden. In DT SYMBOLIC in old-style ELF binaries, see page 24).
fact, the names of all four visibilities are allowed in the In these cases the programmer decided to create a non-
attribute or pragma. standard binary and therefore accepts the fact that the
rules of the ISO C standard do not apply.
Beside telling the backend of the compiler to emit code to
flag the symbol as hidden, changing the visibility has an-
2.2.4 Define Visibility for C++ Classes
other purpose: it allows the compiler to assume the defi-
nition is local. This means the addressing of variables and
function can happen as if the definitions would be locally For C++ code we can use the attributes as well but they
defined in the file as static. Therefore the same code have to be used very carefully. Normal function or vari-
sequences we have seen in the previous section can be able definitions can be handled as in C. The extra name
generated. Using the hidden visibility attribute is there- mangling performed has no influence on the visibility.
fore almost completely equivalent to using static; the The story is different when it comes to classes. The sym-
only difference is that the compiler cannot automatically bols and code created for class definitions are member
inline the function since it need not see the definition. functions and static data or function members. These
variables and functions can easily be declared as hidden
We can now refine the rule for using static: merge but one has to be careful. First an example of the syntax.
source files and mark as many functions static as far as
one feels comfortable. In any case merge the files which
contain functions which potentially can be inlined. In all class foo {
static int u __attribute__
other cases mark functions (the declarations) which are
((visibility ("hidden")));
not to be exported from the DSO as hidden.
int a;
public:
Note that the linker will not add hidden symbols to the foo (int b = 1);
dynamic symbol table. I.e., even though the symbol ta- void offset (int n);
bles of the object files contain hidden symbols they will int val () const __attribute__
disappear automatically. By maximizing the number of ((visibility ("hidden")));
hidden declarations we therefore reduce the size of the };
symbol table to the minimum.
int foo::u __attribute__
The generic ELF ABI defines another visibility mode: ((visibility ("hidden")));
foo::foo (int b) : a (b) { }
protected. In this scheme references to symbols defined
void foo::offset (int n) { u = n; }
in the same object are always satisfied locally. But the
int
symbols are still available outside the DSO. This sounds __attribute__ ((visibility ("hidden")))
like an ideal mechanism to optimize DSO by avoiding the foo::val () const { return a + u; }
use of exported symbols (see section 2.2.7) but it isn’t.
Processing references to protected symbols is even more
expensive than normal lookup. The problem is a require-
ment in the ISO C standard. The standard requires that In this example code the static data member u and the
function pointers, pointing to the same function, can be member function val are defined as hidden. The sym-

18 Version 3.0 How To Write Shared Libraries

bols cannot be accessed outside the DSO the definitions foo (int b = 1);
appear in. Please note that this is an additional restriction int val () const __attribute__
on top of the C++ access rules. For the member functions ((visibility ("hidden")));
one way around the problem is to instantiate the class in void offset (int n);
more than one DSO. This is usually causing no problems };
and “only” adds to code bloat.
class foo_ext : protected foo {
public:
Things are getting more interesting when static data mem-
foo_ext (int b = 1) : foo (b) { }
bers or static local variables in member functions are used.
void offset (int n)
In this case there must be exactly one definition used { return foo::offset (n); }
(please note: “used”, not “present”). To obey this rule };
it is either necessary to not restrict the export of the static
data member of member function from the DSO or to
make sure all accesses of the data or function are made
in the DSO with the definitions. If multiple definitions The class foo is regarded as a private class, not to be
are present it is very easy to make mistakes when hiding used outside the DSO with the instantiation. The public
static data members or the member functions with static interface would be the class foo ext. It provides access
variables since the generated code has no way of knowing to the two public interfaces of the underlying class. As
that there are multiple definitions of the variables. This long as the users of the DSO containing the definitions
leads to very hard to debug bugs. respect the requirement that only foo ext can be used
there is no way for the compiler not noticing accesses to
In the example code above the static data member u is de- foo::u and foo::val outside the DSO containing the
clared hidden. All users of the member must be defined definitions.
in the same DSO. C++ access rules restrict access only to
member functions, regardless of where they are defined. Template class and functions are not different. The syn-
To make sure all users are defined in the DSO with the tax is the same. Non-inline function definitions get yet
definition of u it is usually necessary to avoid inline func- again less readable but that is something which can be
tions which access the hidden data since the inline gener- mostly hidden with a few macros.
ated code can be placed in any DSO which contains code
using the class definition. The member function offset template<class T>
is a prime example of a function which should be inlined class a {
but since it accesses u it cannot be done. Instead offset T u;
is exported as an interface from the DSO which contains public:
the definition of u. a (T a = 0);
T r () const __attribute__
If a member function is marked as hidden, as val is in ((visibility ("hidden")));
the example, it cannot be called from outside the DSO. };
Note that in the example the compiler allows global ac-
template<class T> a<T>::a (T a)
cess to the member function since it is defined as a public { u = a; }
member. The linker, not the compiler, will complain if template<class T> T
this member function is used outside the DSO with the __attribute__ ((visibility ("hidden")))
instantiation. Inexperienced or not fully informed users a<T>::r () const { return u; }
might interpret this problem as a lack of instantiation
which then leads to problems due to multiple definitions.

Because these problems are so hard to debug it is essen- For templatized classes the problems of making sure that
tial to get the compiler involved in making sure the user if necessary only one definition is used is even harder to
follows the necessary rules. The C++ type system is rich fix due to the various approaches to instantiation.
enough to help if the implementor puts some additional
effort in it. The key is to mimic the actual symbol access One sort of function which can safely be kept local and
as closely as possible with the class definition. For this not exported are inline function, either defined in the class
reason the class definitions of the example above should definition or separately. Each compilation unit must have
actually look like this: its own set of all the used inline functions. And all the
functions from all the DSOs and the executable better be
the same and are therefore interchangeable. It is possible
class foo { to mark all inline functions explicitly as hidden but this is
static int u __attribute__ a lot of work. Since version 4.0 gcc knows about the op-
((visibility ("hidden"))); tion -fvisibility-inlines-hidden which does just
int a; what is wanted. If this option is used a referenced in-
public: line function is assumed to be hidden and an out-of-line

Ulrich Drepper Version 3.0 19

copy of the function is marked with STV HIDDEN. I.e., if new declaration is not meant to be affected. Both, the
the function is not inlined the separate function created is pragma and the class attribute, should only be used in
not exported. This is a quite frequent situation at times internal headers. In the headers which are used to ex-
since not all functions the programmer thinks should be pose the API of the DSO it makes no sense to have them
inlined are eligible according to the compiler’s analysis. since the whole point is to hide the implementation de-
This option is usable in almost all situations. Only if the tails. This means it is always a good idea to differentiate
functions in the different DSOs can be different or if the between internal and external header files.
code depends on exactly one copy of the function ever
being used (e.g., if the function address is expected to be Defining entire classes with hidden visibility has some
the same) should this option be avoided. problems which cannot be modeled with sophisticated
class layout or moving the definition in private headers.
If a C++ class is used only for the implementation and For exception handling the compiler generates data struc-
not used in any interface of a DSO using the code, then tures (typeinfo symbols) which are also marked ac-
it would be possible to mark each member function and cording to the visibility attribute used. If an object of
static data element as hidden. This is cumbersome, error- this type is thrown the catch operation has to look for
prone, and incomplete, though. There is perhaps a large the typeinfo information. If that information is in a
number of members which need to be marked and when a different DSO the search will be unsuccessful and the
new member is added it is easy to forget about adding the program will terminate. All classes which are used in
necessary attributes. The incompleteness stems from the exception handling and where the throw and catch are
fact that the C++ compiler automatically generates a few not both guaranteed to reside in the DSO with the defi-
members functions such are constructors and destructors. nition must be declared with default visibility. Individual
These member functions would not be affected by the members can still be marked with an visibility attribute
attributes. but since the typeinfo data is synthesized by the com-
piler on command there is no way for the programmer to
The solution to these problems is to explicitly determine overwrite a hidden visibility attribute associated with the
the visibility of the entire class. Since version 4.0 does class.
gcc have support for this. There are two ways to achieve
the goal. First, the already mentioned pragma can be The use of the most restrictive visibility possible can be
used. of big benefit for C++ code. Each inline function which
is (also) available as a stand-alone function, every syn-
thesized function are variable has a symbol associated
#pragma GCC visibility push(hidden) which is by default exported. For templatized classes this
class foo { is even worse, since each instantiated class can bring is
...
many more symbols. It is best to design the code right
};
away so that the visibility attributes can be applied when-
#pragma GCC visibility pop
ever possible. Compatibility with older compilers can
easily be achieved by using macros.

All member functions and static data members of foo 2.2.5 Use Export Maps
are automatically defined as hidden. This extends even to
implicitly generated functions and operators if necessary. If for one reason or another none of the previous two so-
lutions are applicable the next best possibility is to in-
The second possibility is to use yet another extension in struct the linker to do something. Only the GNU and
gcc 4.0. It is possible to mark a function as hidden when Solaris linker are known to support this, at least with the
it is defined. The syntax is this: syntax presented here. Using export maps is not only
useful for the purpose discussed here. When discussing
class __attribute ((visibility ("hidden")))
maintenance of APIs and ABIs in chapter 3 the same kind
foo { of input file is used. This does not mean the previous two
... methods should not be preferred. Instead, export (and
}; symbol) maps can and should always be used in addition
to the other methods described.

The concept of export maps is to tell the linker explicitly

Just as with the pragma, all defined functions are defined which symbols to export from the generated object. Ev-
as hidden symbols. Explicitly using attributes should be ery symbol can belong to one of two classes: exported or
preferred since the effect of the pragmas is not always not exported. Symbols can be listed individually, glob-
obvious. If the push and pop lines are far enough from expressions can be used, or the special * catch-all glob
each other a programmer might accidentally add a new expression can be used. The latter only once. The sym-
declaration in the range even though the visibility of this bol map file for our example code could look like this:

20 Version 3.0 How To Write Shared Libraries

{ {
global: index; global:
local: *; extern "C++" {
}; foo*;
baz::baz*;
baz::s*
};
This tells the linker that the symbol index is to be ex- local: *;
ported and all others (matched by *) are local. We could };
have listed last and next explicitly in the local: list
but it is generally advised to always use the catch-all case
to mark all not explicitly mentioned symbols as local.
This avoids surprises by allowing access only to the sym- The use of extern "C" tells the linker to match the fol-
bols explicitly mentions. Otherwise there would also be lowing patterns with demangled C++ names. The first
the problem with symbols which are matched neither by entry foo* matches the first global function in the ex-
the global: nor by the local:, resulting in unspecified ample. The second entry matches the constructor(s) of
behavior. Another unspecified behavior is if a name ap- baz and the third entry matches the function baz::s.
pears in both lists or is matched using globbing in both Note that patterns are used in all cases. This is necessary
lists. since foo, baz::baz, and baz::s are not the complete
names. The function parameter are also encoded in the
To generate a DSO with this method the user has to pass mangled name and must be matched. It is not possible to
the name of the map file with the --version-script match complete demangled C++ names since the current
option of the linker. The name of the option suggests that linker implementation refuses to allow non-alphanumeric
the scripts can be used for more. We will get back to this characters. Using pattern might have unwanted effects.
when we discuss ABIs in the next chapter. If there is another member function in baz starting with
the letter ‘s’ it will also be exported. And one last odd-
ity should be mentioned: currently the linker requires that
$ gcc -shared -o foo.so foo.c -fPIC \ there is no semicolon after the last entry in the C++ block.
-Wl,--version-script=foo.map
Using export maps seems like a very desirable solution.
The sources do not have to be made less readable us-
ing attribute declarations or eventually pragmas. All the
The file foo.map is supposed to contain text like the one
knowledge of the ABI is kept locally in the export map
shown above.
file. But this process has one fundamental problem: ex-
actly because the sources are not modified the final code
It is of course also possible to use export maps with C++
is not optimal. The linker is used only after the compiler
code. One has two options in this case: explicitly name
already did its work and the once generated code cannot
the symbols using their mangled names, or rely on pat-
be optimized significantly.
tern matching for the mangled names. Using the man-
gled names is straight-forwarded. Just use the identifiers
In our running example the compiler must generate the
as in the C examples. Using the demangled names re-
code for the next function under the worst case sce-
quire support in the linker. Assume a file defining the
nario assumption that the variable last is exported. This
following functions:
means the code sequence using @GOTOFF which was men-
tioned before cannot be generated. Instead the normal
int foo (int a) { ... }
two instruction sequence using @GOT must be generated.
int bar (int a) { ... }
struct baz { This is what the linker will see when it gets instructed to
baz (int); hide the symbol last. The linker will not touch the ac-
int r () const; tual code. Code relaxation here would require substantial
int s (int); analysis of the following code which is in theory possi-
}; ble but not implemented. But the linker will not generate
the normal R 386 GLOB DAT relocation either. Since the
symbol is not exported no interposition is allowed. The
position of the local definition relative to the start of the
A DSO containing definitions for all these functions and DSO is known and so the linker will generate a relative
members should only export the function foo and the de- relocation.
structor(s) of baz and baz::s. An export map to achieve
this could look like this: For function calls the result is often as good as it gets.
The code generated by the compiler for a PC-relative

Ulrich Drepper Version 3.0 21

jump and a jump through the PLT is identical. It is just linker, nor have any normal relocations been converted
the code which is called (the target function versus the into relative relocations.
code in the PLT) which makes the difference. The code
is only not optimal in one case: if the function call is the The only reason this method is mentioned here is that
only reason the PIC register is loaded. For a call to a local there is hope libtool will learn about converting the
function this is not necessary and loading the PIC is just export lists into the anonymous version maps we have
a waste of time and code. seen in the previous section when the GNU linker is used.
At that point libtool will become useful. Until then
To summarize, for variables the use of symbol maps cre- relying on its -export-symbols option is misleading
ates larger and less efficient code, adds an entry in the at best.
GOT, and adds a relative relocation. For functions the
generated code sometimes contains unnecessary loads of 2.2.7 Avoid Using Exported Symbols
the PIC. One normal relocation is converted into a rel-
ative relocation and one PLT entry is removed. This is
one relative relocation worse than the previous methods. In some situations it might not be desirable to avoid ex-
These deficiencies are the reason why it is much prefer- porting a symbol but at the same time all local references
able to tell the compiler what is going on since after the should use the local definition. This also means that the
compiler finished its work certain decisions cannot be re- uses of the symbols is cheaper since the less general code
verted anymore. sequences can be used. This is a subset of the problem
discussed so far. A solution needs a different approach
since so far we achieved the better code by not exporting
2.2.6 Libtool’s -export-symbols only.

The fourth method to restrict symbol export is the least Since a symbol cannot be exported and not-exported at
desirable of them. It is the one used by the GNU Libtool the same time the basic approach is to use two names for
program when the -export-symbols option is used. the same variable or function. The two names then can
This option is used to pass to Libtool the name of a file be treated differently. There are multiple possibilities to
which contains the names of all the symbols which should create two names, varying in efficiency and effort.
be exported, one per line. The Libtool command line
might look like this: At this point it is necessary to add a warning. By per-
forming this optimization the semantics of the program
changes since the optimization interferes with the sym-
$ libtool --mode=link gcc -o libfoo.la \ bol lookup rules. It is now possible to use more than one
foo.lo -export-symbols=foo.sym symbol with a given name in the program. Code out-
side the DSO might find a definition of a symbol some-
where else while the code in the DSO always uses the
local definition. This might lead to funny results. Of-
The file foo.sym would contain the list of exported sym- ten it is acceptable since multiple definitions are not al-
bols. foo.lo is the special kind of object files Libtool lowed. A related issue is that one rule of ISO C can be
generates. For more information on this and other strange violated by this. ISO C says that functions are identified
details from the command line consult the Libtool man- by their names (identifiers) and that comparing the func-
ual. tion pointers one can test for equality. The ELF imple-
mentation works hard to make sure this rule is normally
Interesting for us here is the code the linker produces us- obeyed. When forcing the use of local symbols code in-
ing this method. For the GNU linker Libtool converts the side and outside the DSO might find different definitions
-export-symbols option into the completely useless for a given name and therefore the pointers do not match.
-retain-symbols-file option. This option instructs It is important to always consider these side effects before
the linker to prune the normal symbol tables, not the dy- performing the optimization.
namic symbol table. The normal symbol table will con-
tain only the symbols named in the export list file plus the
special STT SECTION symbols which might be needed in Wrapper Functions Only applicable to functions, us-
relocations. All local symbols are gone. The problem is ing wrappers (i.e. alternative entry points) is the most
that the dynamic symbol table is not touched at all and portable but also most costly way to solve the problem.
this is the table which is actually used at runtime. If in our example code we would want to export index
as well as next we could use code like this:
The effect of the using libtool this way is that pro-
grams reading the normal symbol table (for instance nm)
do not find any symbols but those listed in the export static int last;
list. And that is it. There are no runtime effects. Neither
have any symbols been made unavailable for the dynamic static int next_int (void) {

22 Version 3.0 How To Write Shared Libraries

 return ++last; This is quite a collection of non-standard gcc extensions
} to the C language so it might need some explanation. The
actual definitions of all three objects are the same as in the
int next (void) { original code. All these objects are exported. The differ-
return next_int (); ence in the definitions is that next is using the internal
} alias last int instead of last and similarly for index
and next. What looks like two declarations is the mech-
int index (int scale) {
anism by which gcc is told about the aliases. It is basi-
return next_int () << scale;
}
cally an extern declaration of an object with the same
type (we use here typeof to ensure that) which has an
alias added. The alias attribute names the object this
is an alias of.
The function next is now a simple wrapper around next int.To achieve the results we want, namely that the aliases are
All calls to next int are recognized by the compiler as not exported and that gcc gets told about this, we have
calls to a local function since next int, unlike next, is to add the hidden visibility attribute. Looking back at
defined with static. Therefore no PLT entries is used sections 2.2.2 and 2.2.3 it should be easy to see that the
for the call in index. use of this attribute is equivalent.
The drawback of this method is that additional code is re- If the visibility attributes cannot be used for some reason
quired (the code for the new next function) and that call- almost the same code should be used, only leaving out
ing next also minimally slower than necessary at run-
time. As a fallback solution, in case no other method , visibility ("hidden")
works, this is better than nothing.
This will create a normal alias with the same scope as the
original symbol. Using export maps the alias can then
be hidden. The resulting binary will not use the efficient
Using Aliases Introducing two names without adding code sequences (see section 2.2.5) but the local definition
code can be achieved by creating aliases for existing ob- will always be used.
jects. Support for this is included in gcc; this does not
only include the creation of the alias, gcc also knows the An attentive reader might suggest that it is possible to
type for the alias and can perform appropriate tests when avoid some of the complications by writing the code for
the alias is used. The here goal is therefore to create an next like this:
alias and tell gcc and/or the linker to not export the sym-
bol. I.e., we apply the same techniques described in the
previous sections now to an alias. The only difference is static int next_int (void) {
that defining an alias as static will not work. The best return ++last_int;
method therefore is to use visibility attributes. The other }
extern __typeof (next_int) next
previously discussed methods will also work but we do
__attribute ((alias ("next_int")));
not go into the details for them here.

If in our example we want to export both last and next

we can rewrite the example like this: As a static definition, next int is not exported and el-
igible for inlining, while next is defined as extern and
therefore exported. Even though this sometimes works
int last; there is no guarantee it does all the time. The compiler
extern __typeof (last) last_int is allowed to use arbitrary symbol names for static
__attribute ((alias ("last"), functions and variables since the names are not part of
visibility ("hidden"))); the ABI of the object file. This is necessary in some
situations to avoid name clashes. The result is that the
int next (void) {
alias("next int") part might fail to provide the cor-
return ++last_int;
rect symbol name and therefore the alias definition will
}
extern __typeof (next) next_int fail. For this reason it is mandatory to create alias only of
__attribute ((alias ("next"), non-static functions and variables.
visibility ("hidden")));
For C++ programs defining aliases we also are also chal-
int index (int scale) { lenged by names. The problem is that the alias attribute
return next_int () << scale; requires the assembler name of the defined symbol as a
} string parameter. For C++ code this means the mangled
name. For simple C++ function we manage to get along

Ulrich Drepper Version 3.0 23

with the same trick used in the C example. The advice here is to never use DF SYMBOLIC. It does
not improve the code, forces all symbols to be treated the
same, and can cause problems in symbol lookup. It is
int mentioned here only for completeness and as a warning.
add (int a, int b)
{ 2.3 Shortening Symbol Names
return a + b;
}
extern __typeof (add) add_int The description of the ELF symbol lookup algorithm shows
__attribute ((alias ("_Z3addii"), that one of the cost factors for the lookup is length of
visibility ("hidden")));
the symbols involved. For successful lookups the entire
string has to be matched and unsuccessful lookups re-
quire matching the common prefix of the involved strings.
There are only two tricky parts. The first is finding the
The flat namespace of the C programming environment
correct mangled name. For the locally used compiler it is
makes following the guideline to use short names easy.
quite easy to determine the name, just compile the code
The names the programmer uses are directly mapped to
without the alias definition and look at the symbol table
names in the ELF file. The same is true for some other
of the generated file. Name mangling is unfortunately
programming environments such as traditional Pascal and
traditionally not well standardized. There exist several
FORTRAN.
different name mangling schemes which means the alias
string would have to be adjusted to the compiler which is
Programming environments with more sophisticated sym-
used for the compilation.
bol handling use name mangling. The most prominent
programming language in this class is C++. The sym-
The second problem is the use of typeof if the func-
bol string of a function consists beside the function name
tion name is overloaded. In this case the compiler does
also of a description of the parameter list, the classes the
not know which of the potentially many versions of the
function is a member of and the namespaces the class
function is meant and it bails out.
or function is defined in. This can lead to enormously
long symbol names. Names of more than 1,000 charac-
ters have been sighted in the wild. Ada names tend to get
DF SYMBOLIC The original designers of the ELF for- very long because of the package namespace.
mat considered the possibility that preferring local def-
initions might be useful. They have included a mecha- The object and namespace model in C++ is used to man-
nism which can enforce this. If the DF SYMBOLIC flag age the complexity of large projects and to facilitate code
is set in the DT FLAGS entry of the dynamic section (or reuse. Therefore it is desirable keep symbol names un-
in older ELF binaries: if the dynamic section contains modified during the development process. But once a
an DT SYMBOLIC entry) the dynamic linker has to prefer program is to be deployed the long names become a nui-
local definitions. sance. This is when a person can step in and shorten the
names.
This approach has numerous disadvantages. First, all in-
terfaces are affected. The other approaches discussed In C++ the most critical classes are those with templates
here have a per-interface granularity. Treating all inter- and/or deeply nested namespaces and class definitions. If
faces like this is normally not the right way. The second such classes are part of the interface of a DSO the pro-
disadvantage is that the compiler does not get told about grammer should make a change. A shorter name for a
the use of local symbols and therefore cannot optimize class can be introduced by deriving publically a new class
the uses, just as if export maps would be used. And what from the class with the long name. The definition could
is even worse, calls to local functions still use the PLT en- be in the global scope to avoid the namespace part of the
tries. The PLT and GOT entries are still created and the mangled name. The symbols associated with this new
jump is indirect. This might be useful in some situations class can be exported, the original class’ names are not.
(e.g., when using LD PROFILE) but usually means a big, This does not remove the names of the original class from
missed opportunity for optimization. the non-dynamic symbol table but this table does not play
any role at run-time.
Finally the third problem is that the lookup scope is changed
in a way which can lead to using unexpected dependen- The wrapper class will have to redefine all non-virtual
cies. DF SYMBOLIC effectively puts the own object in member functions of the class it is helping to export. This
the first spot of its own lookup scope so that there are requires some work and it might add run-time costs by
a number of other DSO which are seen before the depen- an additional function call, the one to the wrapper func-
dencies. This is nothing new but the fact that the DSO tion. Note that defining those functions inline will not
marked with DF SYMBOLIC is in an unusual place can help since then the reference to the original, long name
cause unexpected versions from being picked up. is reintroduced. The only way to avoid the extra call is

24 Version 3.0 How To Write Shared Libraries

to define appropriate aliases, which might prove cumber- If this is the case the code above is not optimal and wastes
some. resources. All that would be needed is the string itself. A
better definition would therefore be:
Shortening symbol names can be considered a micro-
optimization and certainly should not be performed pre-
char str[] = "some string";
maturely. When keeping this optimization in mind dur-
ing the development it might be easy to implement and
the possible benefits can be big. Memory operations are
slow and if the number of bytes which have to be loaded This is something completely different than the code be-
can be reduced this definitely has measurable results. fore. Here str is a name for a sequence of bytes which
contains initially the sequence "some string". By rewrit-
2.4 Choosing the Right Type ing code in this way whenever it is possible we save one
pointer variable in the non-sharable data segment, and
one relative relocation to initialize the variable with a
The selection of the right type can have significant im- pointer to the string. Eventually the compiler is able to
pact on the performs, startup time, and size of a program. generate better code since it is known that the value of
Most of the time it seems obvious what the right type str can never change (the bytes pointed to by str can
is but alternatives are sometimes available and in other change).
cases it might be preferable to rearrange code slightly.
This section will provide a few concrete examples which
2.4.2 Forever const
by no means are meant to be a complete representation of
all the cases which can be optimized.
One nit still exists with the result in the last section: the
2.4.1 Pointers vs. Arrays string is modifiable. Very often the string will never be
modified. In such a case the unsharable data segment is
unnecessarily big.
In some situations there is little or no difference between
pointers and arrays in C. The prototypes
const char str[] = "some string";

void scale (int arr[10], int factor)

After adding the const keyword the compiler is able

to move the string in sharable read-only memory. This
and not only improves the program’s resource use and startup
speed, it also allows to catch mistakes like writing into
this string.
void scale (int *arr, int factor)
But that is not all. Modern gcc and linker versions can
work together to perform cross-object optimizations. I.e.,
strings which appear in more than one object file appear
are in fact mostly equivalent. So people got the impres- only once in the final output. And even more: some link-
sion that there is never a difference and one often finds ers perform suffix optimizations, something which is pos-
code like this: sible with the string representation used in C. For this it
is necessary to realize that a string, which is the back-
char *str = "some string";
part of a longer string (including the NUL byte), can be
represented by the bytes from the longer string.

const char s1[] = "some string";

This is correct and meaningful in some situations. A vari- const char s2[] = "string";
able is str is created with an initial value being a pointer
to a string. This specific piece of code compiles fine with
some compilers but will generate a warning when com-
piled with gcc. More on that in the next section. In this case only the string "some string" has to be
stored in the read-only data segment. The symbol s2 can
The point to be made here is that the use of a variable be a reference to the fifth character of the longer string.
in this situation is often unnecessary. There might not be
an assignment to str (note: not the string, the pointer To make this possible the compiler has to emit the string
variable). The value could be used only in I/O, string data in specially marked section. The sections are marked
generation, string comparison or whatever. with the flags SHF MERGE and SHF STRINGS.

Ulrich Drepper Version 3.0 25

Not all strings can be handled, though. If a string con-
tains an explicit NUL byte, as opposed to the implicit static const char msgs[][17] = {
one at the end of the string, the string cannot be placed [ERR1] = "message for err1",
in mergeable section. Since the linker’s algorithms use [ERR2] = "message for err2",
the NUL byte to find the end of the string the rest of the [ERR3] = "message for err3"
input string would be discarded. It is therefore desirable };
to avoid strings with explicit NUL bytes.

The result of this code is optimal. The array msgs is

2.4.3 Arrays of Data Pointers
placed entirely in read-only memory since it contains no
pointer. The C code does not have to be rewritten. The
Some data structure designs which work perfectly well drawback of this solution is that it is not always applica-
in application code add significant costs when used in ble. If the strings have different lengths it would mean
DSOs. This is especially true for arrays of pointers. One wasting quite a bit of memory since the second dimen-
example which shows the dilemma can be met frequently sion of the array has to be that of the length of the longest
in well-designed library interface. A set of interfaces re- string plus one. The waste gets even bigger if the values
turns error number which can be converted using another ERR0, ERR1, and ERR2 are not consecutive and/or do not
function into strings. The code might look like this: start with zero. Every missing entry would mean, in this
case, 17 unused bytes.

There are other methods available for case which cannot

static const char *msgs[] = {
[ERR1] = "message for err1",
be handled as the example above but none without major
[ERR2] = "message for err2", code rewrite.9 One possible solution for the problem is
[ERR3] = "message for err3" the following. This code is not as elegant as the original
}; code but it is still maintainable. Ideally there should be a
tool which generates from a description of the strings the
const char *errstr (int nr) { appropriate data structures. This can be done with a few
return msgs[nr]; lines
}

static const char msgstr[] =

"message for err1\0"
The problematic piece is the definition of msgs. msgs is "message for err2\0"
"message for err3";
as defined here a variable placed in non-sharable, writable
memory. It is initialized to point to three strings in read- static const size_t msgidx[] = {
only memory (that part is fine). Even if the definition 0,
would be written as sizeof ("message for err1"),
sizeof ("message for err1")
static const char *const msgs[] = { + sizeof ("message for err2")
};
(note the addition const) this would not change this (but
it opens up some other opportunities, see 2.6). The com- const char *errstr (int nr) {
piler still would have the place the variable in writable return msgstr + msgidx[nr];
memory. The reason are three relative relocation which }
modify the content of the array after loading. The total
cost for this code is three words of data in writable mem-
ory and three relocations modifying this data in addition
to the memory for the strings themselves. The content of both arrays in this code is constant at
compile time. The references to msgstr and msgidx
Whenever a variable, array, structure, or union, contains in errstr also do not need relocations since the defini-
a pointer, the definition of an initialized variable requires tions are known to be local. The cost of this code include
relocations which in turn requires the variable to be placed three size t words in read-only memory in addition to
in writable memory. This along with the increased startup the memory for the strings. I.e., we lost all the reloca-
time due to processing of the relocations is not acceptable tions (and therefore startup costs) and moved the array
for code which is used only in error cases. from writable to read-only memory. In this respect the
code above is optimal.
For a simple case as the example above a solution entirely 9 If we would write assembler code we could store offsets relative to
within C can be used by rewriting the array definition like a point in the DSO and add the absolute address of the reference point
this: when using the array elements. This is unfortunately not possible in C.

26 Version 3.0 How To Write Shared Libraries

For a more elaborate and less error-prone method of con- larger. Compilers do not have problems with large func-
structing such tables is appendix B. The presented code tions and might even be able to optimize better. The
does not require the programmer to duplicate strings which problem is only the programmer. The original code was
must be kept in sync. clean and intentionally written using function pointers.
The transformed code might be much less readable. This
2.4.4 Arrays of Function Pointers makes this kind of optimization one which is not per-
formed until the code is tested and does not need much
maintenance anymore.
The situation for function pointers is very similar to that
of data pointers. If a pointer to a function is used in the A similar problem, though it (unfortunately) is rather rare
initialization of a global variable the variable the result today, arises for the use of computed gotos, a gcc ex-
gets written to must be writable and non-sharable. For tension for C. Computed gotos can be very useful in
locally defined functions we get a relative relocation and computer-generated code and in highly optimized code.10
for functions undefined in the DSO a normal relocation The previous example using computed gotos might look
which is not lazily performed. The question is how to like this:
avoid the writable variable and the relocations. Unfortu-
nately there is no generally accepted single answer. All
be can do here is to propose a few solution. Our example int add (int a, int b) {
code for this section is this: static const void *labels[] = {
&&a0, &&a1, &&a2
};
static int a0 (int a) { return a + 0; } goto *labels[b];
static int a1 (int a) { return a + 1; } a0:
static int a2 (int a) { return a + 2; } return a + 0;
a1:
static int (*fps[]) (int) = { return a + 1;
[0] = a0, a2:
[1] = a1, return a + 2;
[2] = a2 }
};

int add (int a, int b) {

return fps[b] (a);
How the code works should be obvious. The array labels
}
contains pointers to the places in the function where the
labels are placed and the gotos jumps to the place picked
out of the array. The problem with this code is that the ar-
A solution for this problem must inevitably be differ- ray contains absolute address which require relative relo-
ent from what we did for strings where we combined all cations in a DSO and which require that the array labels
strings into one. We can do this for functions as well but is writable and placed in non-sharable memory.
it will look different:
The above code in principal is an implementation of a
switch statement. The difference is that the compiler
int add (int a, int b) { never stores absolute addresses which would need relo-
switch (b) { cations of position-independent code is generated. In-
case 0: stead the addresses are computed relative to the PIC ad-
return a + 0; dress, producing a constant offset. This offset then has
case 1:
to be added to the PIC register value which is a minimal
return a + 1;
case 2:
amount of extra work. To optimize the code above a sim-
return a + 2; ilar scheme but be used.
}
}
int add (int a, int b) {
static const int offsets[] = {
&&a0-&&a0, &&a1-&&a0, &&a2-&&a0
Inlining the code as in the code above should certainly be };
the preferred solution. The compiler never generates re- goto *(&&a0 + offsets[b]);
a0:
locations for the implementation of a switch statement
return a + 0;
and therefore the whole code does not need any reloca-
a1:
tion.
10 Interested readers might want to look at the vfprintf implemen-

Inlining makes sense even if the inlined function are much tation in the GNU libc.

Ulrich Drepper Version 3.0 27

 return a + 1; lookups have to be used. Using the visibility attributes
a2: was mentioned as a possibility to get relative relocations.
return a + 2; But since the virtual function table and the instantiated
} member functions are generated by the compiler adding
an attribute cannot be done without some dirty tricks. So
using linker version scripts is really the only possibility.

Since we do not have direct access to the PIC register at But even this is often not possible. The virtual functions
compile-time and cannot express the computations of the can be called not only through the virtual function table
offsets we have to find another base address. In the code but also directly if the compiler can determine the exact
above it is simply one of the target addresses, a0. The type of an C++ object. Therefore virtual function in most
array offsets is in this case really constant and placed cases have to be exported from the DSO. For instance,
in read-only memory since all the offsets are known once the virtual function in the following example is called di-
the compiler finished generating code for the function. rectly.
We now have relative addresses, no relocations are nec-
essary. The type used for offsets might have to be ad-
justed. If the differences are too large (only really pos- struct foo {
sible for 64-bit architectures, and then only for tremen- virtual int virfunc () const;
dously large functions) the type might have to be changed };
to ssize t or something equivalent. In the other direc- foo var;
tion, if it is known that the offsets would fit in a variable int bar () { return var.virfunc (); }
of type short or signed char, these types might be
used to save some memory.

The reason is that var is known to have type foo and

2.4.5 C++ Virtual Function Tables
not a derived type from which the virtual function table
is used. If the class foo is instantiated in another DSO
Virtual function tables, generated for C++ classes with not only the virtual function table has to be exported by
member functions tagged with virtual, are a special that DSO, but also the virtual function virfunc.
case. The tables normally involve function pointer which
cause, as seen above, the linker to create relocations. It If a tiny runtime overhead is acceptable the virtual func-
is also worthwhile looking at the runtime costs of virtual tion and the externally usable function interface should
functions compared to intra- and inter-DSO calls. But be separated. Something like this:
first the relocation issues.

Usually the virtual function table consists of an array of /* In the header. */

function pointers or function descriptors. These represen- struct foo {
virtual int virfunc () const;
tations have in common that for every slot in the virtual
int virfunc_do () const;
function table there must be one relocation and all the
};
relocations have to be resolved at startup-time. There-
fore having larger a number of virtual function tables or /* In the source code file. */
virtual function tables with many entries impact startup virtual int foo::virfunc () const
time. { return virfunc_do (); }
int foo::virfunc_do () const
One other implication is noteworthy. Even though at run- { ...do something... }
time normally only one virtual function table is used (since
the name is the same the first is in the lookup scope is
used) all tables must be initialized. The dynamic linker
has no possibility to determine whether the table will be In this case the real implementation of the function is in
used at some point or not and therefore cannot avoid ini- virfunc do and the virtual function just calls it. There
tializing it. Having exactly one virtual function table def- is no need for the user to call the virtual function di-
inition in all the participating DSOs is therefore not only rectly as in the function bar above since virfunc do
useful for space conservation reasons. can be called instead. Therefore the linker version script
could hide the symbol for the virtual function and export
The cost of each relocation depends on whether the func- virfunc do to be called from other DSOs. If the user
tion being referenced is defined locally and whether it still calls the virtual function the linker will not be able to
is exported or not. Only for functions which are explic- find a definition and the programmer has to know that this
itly hidden by using the visibility attributes or a version means she has to rewrite the code to use virfunc do.
script can the linker use relative relocations which can This makes using the class and the DSO a bit more com-
be processed quickly. Otherwise relocations with symbol plex.

28 Version 3.0 How To Write Shared Libraries

The consequence of hiding the virtual function is that the is called very often? Even worse: what if the function
virtual function table slot for virfunc can be handled getfoo would be defined static or hidden and no pointer
with a relative relocation. This is a big gain not only be- to it are ever available? In this case the caller might al-
cause this relocation type is much faster to handle. Since ready have computed the GOT address; at least on IA-32
virtual function tables contain data references the relo- the GOT address is the same for all functions in the DSO
cation of the virtual function table slots must happen at or executable. The computation of the GOT address in
startup time. foobar would be unnecessary. The key word in this sce-
nario description is “might”. The IA-32 ABI does not
The improved example above assumes that direct calls require that the caller loads the PIC register. Only if a
are more frequent than calls through the virtual func- function calls uses the PLT do we know that %ebx con-
tion table since there is additional overhead (one extra tains the GOT address and in this case the call could come
function call) involved when calling virfunc. If this as- from any other loaded DSO or the executable. I.e., we re-
sumption is wrong and calls through the virtual function ally always have to load the GOT address.
table are more frequent, then the implementations of the
two functions can be swapped. On platforms with better-designed instruction sets the gen-
erated code is not bad at all. For example, the x86-64
In summary, the number and size of virtual function ta- version could look like this:
bles should be kept down since it directly impacts startup
time behavior. If virtual functions cannot be avoided the
getfoo:
implementations of the functions should not be exported.
movl foo(%rip),%eax
ret
2.5 Improving Generated Code

On most platforms the code generated for DSOs differs The x86-64 architecture provides a PC-relative data ad-
from code generated for applications. The code in DSOs dressing mode which is extremely helpful in situations
needs to be relocatable while application code can usu- like this.
ally assume a fixed load address. This inevitably means
that the code in DSOs is slightly slower and probably Another possible optimization is to require the caller to
larger than application code. Sometimes this additional load the PIC register. On IA-64 the gp register is used
overhead can be measured. Small, often called functions for this purpose. Each function pointer consist of a pair
fall into this category. This section shows some problem function address and gp value. The gp value has to be
cases of code in DSOs and ways to avoid them. loaded before making the call. The result is that for our
running example the generated code might look like this:
In the preceding text we have seen that for IA-32 a func-
tion accessing a global variable has to load determine the getfoo:
address of the GOT to use the @GOTOFF operation. As- addl r14=@gprel(foo),gp;;
suming this C code ld4 r8=[r14]
br.ret.sptk.many b0

static int foo;

int getfoo (void)
{ return foo; } If the caller knows that the called function uses the same
gp value, it can avoid the loading of gp. IA-32 is really a
special case, but still a very common one. So it is appro-
priate to look for a solution.
the compiler might end up creating code like this:
Any solution must avoid the PIC register entirely. We
propose two possible ways to improve the situation. First,
getfoo:
do not use position-independent code. This will generate
call 1f
1: popl %ecx code like
addl _GLOBAL_OFFSET_TABLE_[.-1b],%ecx
movl foo@GOTOFF(%ecx),%eax getfoo:
ret movl foo,%eax
ret

The actual variable access is overshadowed by the over-

head to do so. Loading the GOT address into the %ecx The drawback is that the resulting binary will have text
register takes three instructions. What if this function relocations. The page on which this code resides will

Ulrich Drepper Version 3.0 29

not be sharable, the memory subsystem is more stressed be pure overhead since we can access global variables
because of this, a runtime relocation is needed, program without the GOT value. On IA-64 marking getfoo as
startup is slower because of both these points, and secu- hidden would allow to avoid the PLT and therefore the gp
rity of the program is impacted. Overall, there is a mea- register is not reloaded during the call to getfoo. Again,
surable cost associated with not using PIC. This possibil- the parameter is pure overhead. For this reason it is ques-
ity should be avoided whenever possible. If the DSO is tionable whether this IA-32 specific optimization should
question is only used once at the same time (i.e., there are ever be performed. If IA-32 is the by far most important
no additional copies of the same program or other pro- platform it might be an option.
grams using the DSO) the overhead of the copied page is
not that bad. Only in case the page has to be evacuated 2.6 Increasing Security
from memory we would see measurable deficits since the
page cannot simply be discarded, it must be stored in the
disk swap storage. The explanation of ELF so far have shown the critical im-
portance of the GOT and PLT data structures used at run-
The second proposed solution has a bigger impact on the time by the dynamic linker. Since these data structures
whole code. Assume this extended example: are used to direct memory access and function calls they
are also a security liability. If a program error provides
an attacker with the possibility to overwrite a single word
static int foo; in the address space with a value of his choosing, then
static int bar; targetting a specific GOT entry is a worthwhile goal. For
int getfoo (void) some architectures, a changed GOT value might redirect
{ return foo; } a call to a function, which is called through the PLT, to
int getboth (void)
an arbitrary other place. Similarly, if the PLT is modified
{ return bar+getfoo(); }
in relocations and therefore writable, that memory could
be modified.

If this code gets translated as is, both functions will load An example with security relevance could be a call to
the GOT address to access the global variables. This can setuid to drop a process’ privileges which is redirected
be avoided by putting all variables in a struct and passing to perhaps getpid. The attacker could therefore keep
the address of the struct to the functions which can use it. the raised priviledges and later cause greater harm.
For instance, the above code could be rewritten as:
This kind of attack would not be possible if the data GOT
and PLT could not be modified by the user program. For
static struct globals { some platforms, like IA-32, the PLT is already read-only.
int foo; But the GOT must be modifiable at runtime. The dy-
int bar; namic linker is an ordinary part of the program and it
} globals; is therefore not possible to require the GOT in a mem-
static int intfoo (struct globals *g) ory region which is writable by the dynamic linker but
{ return g->foo; }
not the rest of the application. Another possibility would
int getfoo (void)
{ return intfoo(&globals); }
be to have the dynamic linker change the access permis-
int getboth (void) sions for the memory pages containing the GOT and PLT
{ return globals.bar+intfoo(&globals); } whenever it has to change a value. The required calls to
mprotect are prohibitively expensive, ruling out this so-
lution for any system which aims to be performing well.

The code generated for this example does not compute At this point we should remember how the dynamic linker
the GOT address twice for each call to getboth. The works and how the GOT is used. Each GOT entry be-
function intfoo uses the provided pointer and does not longs to a certain symbol and depending on how the sym-
need the GOT address. To preserve the semantics of the bol is used, the dynamic linker will perform the relo-
first code this additional function had to be introduced; cation at startup time or on demand when the symbol
it is now merely a wrapper around intfoo. If it is pos- is used. Of interest here are the relocations of the first
sible to write the sources for a DSO to have all global group. We know exactly when all non-lazy relocation
variables in a structure and pass the additional parameter are performed. So we could change the access permis-
to all internal functions, then the benefit on IA-32 can be sion of the part of the GOT which is modified at startup
big. time to forbid write access after the relocations are done.
Creating objects this way is enabled by the -z relro
But it must be kept in mind that the code generated for the linker option. The linker is instructed to move the sec-
changed example is worse than what would be created for tions, which are only modified by relocations, onto sep-
the original on most other architectures. As can be seen, arate memory page and emit a new program header en-
in the x86-64 case the extra parameter to intfoo would try PT GNU RELRO to point the dynamic linker to these

30 Version 3.0 How To Write Shared Libraries

special pages. At runtime the dynamic linker can then since there is no other thread available which could per-
remove the write access to these pages after it is done. form the attack while the pages are writable. The same is
not true if later, when the program already executes nor-
This is only a partial solution but already very useful. mal code and might have start threads, some DSOs are
By using the -z now linker option it is possible to dis- loaded dynamically with dlopen. For this reason cre-
able all lazy relocation at the expense of increased startup ating DSOs with text relocation means unnecessarily in-
costs and make all relocations eligible for this special creasing the security problems of the system.
treatment. For long-running applications which are secu-
rity relevant this is definitely attractive: the startup costs Much more critical is that with Security Enhanced Linux
should not weigh in as much as the gained security. Also, (SELinux) text relocations become a big liability. By de-
if the application and DSOs are written well, they avoid fault, the SELinux extensions prevent making executable
relocations. For instance, the DSOs in the GNU C library data pages writable. Since the kernel cannot distinguish
are all build with -z relro and -z now. between the dynamic linker doing this and the program
or an attacker making the change, the abilities of the dy-
The GOT and PLT are not the only parts of the applica- namic linker are also restricted. The only ways out are
tion which benefit from this feature. In section 2.4.2 we to grant the program permission to change the protection
have seen that adding as many const to a data object def- (and therefore give attackers the ability to do the same) or
inition as possible has benefits when accessing the data. to remove text relocations from all DSOs and PIEs. The
But there is more. Consider the following code: former option should only be used as a last resort.

2.7 Simple Profiling of Interface Usage

const char *msgs1[] = {
"one", "two", "three"
}; The dynamic linker in the GNU C library allows easy
const char *const msgs2[] = {
profiling of the way a DSO is used without recompiling
"one", "two", "three"
};
any code. By setting the value of the environment vari-
able LD PROFILE to the shared object name (SONAME)
of a DSO, all uses of interfaces defined in this DSO which
go through a PLT are recorded. In addition time-based
It has been explained that neither array can be moved sampling happens as well and all samples which happen
into the read-only, and therefore shared, data section if in the profiled DSO are recorded. This is all similar to the
the file is linked into a DSO. The addresses of the strings gprof-based profiling which is available on Unix sys-
pointed to by the elements are known only at runtime. tems for a long time.
Once the addresses are filled in, though, the elements of
msgs2 must never be modified again since the array it- The LD PROFILE variable can be set for arbitrarily many
self is defined as const. Therefore gcc stores the array applications running at the same time. All profiling activ-
msgs1 in the .data section while msgs2 is stored into ity is recorded in real-time in the same output file which is
a section called .data.rel. This .data.rel section is usually stored in /var/tmp. Without having to stop any
just like .data but the dynamic linker could take away or all applications currently profiled, the current status
write access after the relocations are done. The previ- can be examined by running the sprof program. The op-
ously described handling of the GOT is just a special case tions this program understands are similar to those gprof
of exactly this feature. Adding as many const as possi- understand. There are basically three report types, call
ble together with the -z relro linker option therefore pairs, flat profiles, and graph profiles which can all be
protects even program data. This might even catch bugs requested at once.
where code incorrectly modifies data declared as const.
How to use these profile results is specific to the applica-
A completely different issue, but still worth mentioning tion. It is easy to locate often called functions and, given
in the context of security, are text relocations. Generat- sufficient runtime, functions inside the DSO which run
ing DSOs so that text relocations are necessary (see sec- for a long time. Everybody who used gprof should feel
tion 2) means that the dynamic linker has to make mem- right at home although DSO profiling has its limitations.
ory pages, which are otherwise read-only, temporarily
writable. The period in which the pages are writable is The call data is accumulated by intercepting the calls
usually brief, only until all non-lazy relocations for the made through the PLT. The dynamic linker can do this
object are handled. But even this brief period could be without the application noticing it. But if the PLT is not
exploited by an attacker. In a malicious attack code re- used, data is not recorded. This is the case if an appli-
gions could be overwritten with code of the attacker’s cation looks a symbol up using dlsym and then calls it
choice and the program will execute the code blindly if it directly. This might make the profiling data useless.
reaches those addresses.
The solution for this problem is to use the DL CALL FCT
During the program startup period this is not possible macro the GNU C library’s <dlfcn.h> header defines.

Ulrich Drepper Version 3.0 31

If a looked-up function pointer fctp has been used like time of the DSO. Maintaining ABI compatibility means
this that no definition, also called interface, gets lost. This is
only the easy part, though.
foo = fctp (arg1, arg2);
For variable definitions it also means that the size and
or if you prefer structure of the variable does not change in a way the
application cannot handle. What this actually means de-
foo = (*fctp) (arg1, arg2); pends on the situation. If any code outside the DSO di-
rectly accesses the variable, the accessed part of the struc-
the code should be rewritten to look like this: ture of the variable must not change. On platforms which
require copy relocations to handle accesses to variables
foo = DL CALL FCT (fctp, (arg1, arg2)); defined in DSOs in the main application (such as IA-32)
the size of the variable must not change at all. Otherwise
The DL CALL FCT macro contains the necessary magic variables might increase in size.
to record the calling of the function pointed to by fctp.
If the DSO which contains the symbol is not profiled The requirements on function definitions are even harder
nothing happens. It is therefore safe to always use this to check. The documented semantic of a function must
macro to call symbols in dynamically loaded DSOs. The not change. Defining “semantic” for any non-trivial func-
DL CALL FCT macro has a low overhead and so could be tion is not easy, though. In the next section we try to
used unconditionally but for production code it is proba- define the requirements of a stable interface. Basically
bly best to avoid it. stability means that correct programs which ran in the
past continue to run in the future. One of the require-
ments therefore is that the parameters of a function do not
3 Maintaining APIs and ABIs change. This brings up an interesting point: in C++ this
is ensured automatically. Functions incorporate in their
When writing DSOs which are used as resources in mul- mangled names the parameter types. This means that any
tiple projects mastering the technical aspects of writing change in the signature of a function will result in link-
optimized DSOs is only part of what is needed. Main- time and run-time errors and therefore can be detected
taining the programming interface (API) and the binary easily. This is not the case for variables; their mangled
interface (ABI) play an even more important role in a suc- names only contain the namespace part. Another good
cessful project. Without API and ABI stability the DSO reason to not export variables as part of the API.
would be a burden to use or even unusable. In this sec-
tion we will introduce a number of rules which increase 3.2 Defining Stability
the chance of success for projects which provides inter-
faces for other projects. We are talking specifically about
library implementations in DSOs but most rules can be Having said that stability of the ABI is the highest goal
transferred to projects of any kind. of DSO maintenance, it is now time to define what sta-
bility means. This might be surprising for some readers
3.1 What are APIs and ABIs? as a naı̈ve view of the problem might be that everything
which worked before has to continue working in the fu-
ture. Everybody who tried this before will see a problem
DSOs are used both at compile time and at run-time. At with it.
compile time the linker tries to satisfy undefined refer-
ences from the definitions in the DSO. The linker then Requiring everything to continue to be possible in future
associates the reference with the definition in the DSO. In releases would mean that even programs, which use in-
ELF objects this reference is not explicitly present since terfaces in an undocumented way, have to be supported.
the symbol lookup allows finding different definitions at Almost all non-trivial function interfaces allow parame-
run-time. But the reference is marked to be satisfied. At ters to specify values which are outside the documented
run-time the program can rely on the fact that a defini- interface and most interfaces are influenced by side ef-
tion is present. If this would not be the case something fects from other functions or previous calls. Requiring
changed in the DSO between the time of linking the ap- that such uses of an interface are possible in future revi-
plication and the time the application is executed. A sions means that not only the interface but also the im-
change in which a symbol vanishes is usually fatal. In plementation is fixed.
some cases definitions in other DSOs can take over but
this is nothing which one can usually be depended on. As an example assume the implementation of the strtok
A symbol once exported must be available at run-time in function in the C run-time library. The standard requires
the future. that the first call if strtok gets passed a non-NULL first
parameter. But what happens if the first call has a NULL as
The ABI of the DSO comprises the collection of all the the first parameter? In this case the behavior is undefined
definitions which were available for use during the life- (not even implemented-defined in this case). Some im-

32 Version 3.0 How To Write Shared Libraries

plementations will in this case simply return NULL since But if a new application uses the new interface it will run
this a common side effect of a possible implementation. into problems if at runtime only the old version of the
But this is not guaranteed. The function call might as DSO, the one without the newly added symbol, is avail-
well cause the application to crash. Both are valid im- able. The user can detect this by forcing the dynamic
plementations but changing from one to the other in the linker to perform all relocations at load-time by defin-
lifetime of a DSO would mean an incompatibility. ing LD BIND NOW to an nonempty value in the environ-
ment before starting the application. The dynamic linker
The question is: does this really constitute an incompat- will abort with an error if an old DSO is used. But forc-
ibility? No valid program would ever be affected. Only ing the relocations introduces major performance penal-
programs which are not following the documented inter- ties (which is the reason why lazy relocations were in-
face are affected. And if the change in the implementa- troduced in the first place). Instead the dynamic linker
tion would mean an improvement in efficiency (accord- should detect the old DSO version without performing
ing to whatever measure) this would mean broken appli- the relocations.
cations prevent progress in the implementation of a DSO.
This is not acceptable. 3.3 ABI Versioning

Stability therefore should be defined using the documented

interface. Legitimate uses of interfaces should not be af- The term “ABI versioning” refers to the process of asso-
fected by changes in the implementation; using interfaces ciating an ABI with a specific version so that if necessary
in an undefined way void the warranty. The same is true more than one version of the ABI can be present at any
for using completely undocumented, internal symbols. one time. This is no new concept but it was refined over
Those must not be used at all. While this definition of time and not all possible versioning methods are available
stability is widely accepted it does not mean that avoid- on all systems.
ing or working around changes introduced by changes to
the implementation is wrong. It just is not necessary if The first method is the oldest and coarsest grained one. It
the achievement of stability comes at a cost which almost is implemented by using a different filename for each in-
always is the case. compatible DSO. In ELF binaries dependencies on DSOs
are recorded using DT NEEDED entries in the dynamic
Rejecting stability of undefined functionality is one thing, segment. The string associated with the entry has to be
but what happens if some documented behavior changes? the name of an existing DSO. It is usually taken from the
This is can happen for various reasons: string associated with the DT SONAME entry in the DSO.
Different names can point to different files which makes
coexistence of different DSOs possible and easy. But
• The implementation contains a bug. Other imple- while this method is easy to use and such DSOs can eas-
mentations produce different results and this is what ily be produced, it has a major drawback. For every re-
people interested in cross-platform compatibility leased version of the DSO which contains an incompati-
are interested in. The old, broken behavior might ble change the SONAME would have to be changed. This
be useful, too. can lead to large numbers of versions of the DSO which
each differ only slightly from each other. This wastes
• Similarly, alignment with standards, revisions of resources especially at run-time when the running appli-
them, or existing practice in other implementations cation need more than one version of the DSO. Another
can promise gains in the future and therefore mak- problem is the case when one single application loads
ing a change is useful. more than one version of the DSO. This is easily pos-
• Functionality of an interface gets extended or re- sible if dependencies (other DSOs the application needs)
duced according to availability of underlying tech- pull in independently these different versions. Since the
nology. For instance, the introduction of more ad- two versions of the versioned DSO do not know of each
vanced harddisk drives can handle requests which other, the results can be catastrophic. The only safe way
previous versions cannot handle and these addi- to handle versioning with filenames is to avoid the de-
tional requests can be exposed through function in- scribed situation completely. This is most probably only
terfaces. possible by updating all binaries right away which means
that effectively no versioning happens. The main advan-
tage of filename versioning is that it works everywhere
Not making the changes can have negative results. Blindly and can be used as a fallback solution in case no other
changing the code will definitely have negative results. versioning method is available.
Making the change and still maintaining ABI stability re-
quires the use of versioning. A second method with finer grained control was devel-
oped by Sun for its Solaris OS. In this method DSOs have
These incompatible changes to a DSO are not the only internal versioning methods (filename versioning is ob-
changes which can cause problems. Adding a new inter- viously available on top of them). The internal version-
face does not cause problems for existing applications. ing allows to make compatible changes to a DSO while

Ulrich Drepper Version 3.0 33

avoiding runtime problems with programs running in en- consistent. Every versioned DSO has at most one version
vironments which have only the old version of the DSO of every API which can be used at link-time. An API
available. Compatible changes mean adding new inter- (not ABI) can also vanish completely: this is a way to
faces or defining additional behavior for existing inter- deprecate APIs without affecting binary compatibility.
faces. Each symbol is associated with a version. The
versions in a file are described by a non-cyclical graph The only real problem of this approach is that if more
which forms a hierarchy. If a symbol is associated with a than one version of the same API is used in the same ap-
version which has a predecessor it means that the proper- plication. This can only happen if the uses are in different
ties of the symbol associated with the predecessor version objects, DSOs or the application itself. From inside one
are also fulfilled in the successor version. In short: a new object only one version can be accessed. In the last 8+
version is defined for a new release of a DSO whenever years this hasn’t been found to be a problem in the GNU
new features are added. The interfaces which changed C library development. If it becomes a problem it can po-
in a compatible way get the new version associated. All tentially be worked around by changing the implementa-
the other interfaces must not change and they keep the tion of the multi-versioned interface to make it aware of
version they had in the previous release. it. Since both versions of the interface are implemented
in the same DSO the versions can coordinate. In general,
When the linker uses the versioned DSO to satisfy a de- most of the implementation of the different versions is
pendency it also records the version of the used symbol. shared and the actual versioned interfaces are normally
This way it gets for each DSO a list of required versions. wrappers around a general implementation (see below).
This list is recorded in the binary which is produced.
With this information available it is now easy for the dy- If possible, projects implementing generally usable DSOs
namic linker to determine at startup-time whether all the should use symbol versioning from day one. Since the
interfaces the application needs are available in at least same techniques are used for symbol export control this is
the version which was used at link-time. To do this the attractive. Unfortunately this versioning scheme requires
dynamic linker has to go through the list of all required changes in the dynamic linker which are currently only
versions and search in the list of defined versions in the available on Linux and GNU Hurd.11 If this is not possi-
referenced DSOs for a matching entry. If no matching ble use Sun’s internal versioning for compatible changes
entry is found the DSO used at runtime is incompatible (really only applies to Solaris). Otherwise there is no op-
and the program does not start up. tion but to change the SONAME for every release with
incompatible and possible even releases with compati-
It should be noted that the number of versions is much ble changes. But the fact that such limited systems ex-
lower than the number of symbols and generally inde- ist should never make this the only implemented way: if
pendent of it. New versions are introduced only for up- better mechanisms are available they should be used.
dates of the DSO package or an OS release. Therefore
the version matching is a quick process. 3.4 Restricting Exports

While Sun’s extensions help to cope with parts of the

stability problem, the much larger problem remains to One of the reasons changes between revisions of a DSO
be solved: how to handle incompatible changes. Every appear incompatible is that users use internal interfaces
non-trivial DSO will sooner or later in its lifetime require of the DSO. This should never happen and usually the
some incompatible changes. Even changes made to cor- official interfaces are documented and the internal inter-
rect problems fall sometimes into this category. Some faces have special names. Still, many users choose to
(broken) program might depend on the old method. So ignore these rules and then complain when internal inter-
far there is only one way out: change the SONAME. faces change or go away entirely. There is no justification
for these complaints but developers can save themselves
With Linux’s symbol versioning mechanism this is not a lot of nerves by restricting the set of interfaces which
necessary. ABIs can normally be kept stable for as long are exported from the DSO.
as wanted. The symbol versioning mechanism [4] is an
extension of Sun’s internal versioning mechanism. The Section 2.2 introduced the mechanisms available for this.
two main differences are: it is possible to have more than Now that symbol versioning has been introduced we can
one definition of a given symbol (the associated version extend this discussion a bit. Using symbol maps was in-
must differ) and the application or DSO linked with the troduced as one of the possibilities to restrict the exported
versioned DSO contains not only a list of the required symbols. Ideally symbol maps should be used all the
version, but also records for each symbol which sym- time, in addition to the other method chosen. The rea-
bol version was used and from which DSO the definition son is that this allows associating version names with the
came. At runtime this information can then be used to interfaces which in turn later allow incompatible changes
pick the right version from all the different versions of to be made without breaking the ABI. The example map
the same interface. The only requirement is that the API
11 Apparently some of the BSD variants “borrowed” the symbol ver-
(headers, DSO used for linking, and documentation) is
sioning design. They never told me though.

34 Version 3.0 How To Write Shared Libraries

file in section 2.2.5 does not define a version name, it is function is defined using the new semantic. The extern
an anonymous version map. The version defining a ver- declaration following the function definition is in fact a
sion name would look like this: definition of an alias for the name index1 . This is
gcc’s syntax for expressing this. There are other ways
to express this but this one uses only C constructs which
VERS_1.0 {
are visible to the compiler. The reason for having this
global: index;
local: *;
alias definition can be found in the following two lines.
}; These introduce the “magic” to define a versioned sym-
bol with more than one definition. The assembler pseudo-
op .symver is used to define an alias of a symbol which
consists of the official name, @ or @@, and a version name.
In this example VERS 1.0 is an arbitrarily chosen version The alias name will be the name used to access the sym-
name. As far as the static and dynamic linker are con- bol. It has to be the same name used in the original code,
cerned version names are simply strings. But for mainte- index in this case. The version name must correspond
nance purposes it is advised that the names are chosen to to the name used in the map file (see the example in the
include the package name and a version number. For the previous section).
GNU C library project, for instance, the chosen names
are GLIBC 2.0, GLIBC 2.1, etc. What remains to be explained is the use of @ and @@. The
symbol defined using @@ is the default definition. There
3.5 Handling Compatible Changes (GNU) must be at most one. It is the version of the symbol used
in all linker runs involving the DSO. No symbol defined
using @ are ever considered by the linker. These are the
The two basic compatible changes, extending functional- compatibility symbols which are considered only by the
ity of an existing interface and introducing a new inter- dynamic linker.
face, can be handled similarly but not exactly the same
way. And we need slightly different code to handle the In this example we define both versions of the symbol to
Linux/Hurd and the Solaris way. To exemplify the changes use the same code. We could have just as well kept the
we extend the example in section 2.2. The index func- old definition of the function and added the new defini-
tion as defined cannot handle negative parameters. A ver- tion. This would have increased the code size but would
sion with this deficiency fixed can handle everything the provide exactly the same interface. Code which calls the
old implementation can handle but not vice versa. There- old version, index@VERS 1.0, would have produced un-
fore applications using the new interface should be pre- specified behavior with the old DSO and now it would re-
vented from running if only the old DSO is available. As turn the same as a call to index@@VERS 2.0. But since
a second change assume that a new function indexp1 is such a call is invalid anyway nobody can expect that the
defined. The code would now look like this when using ABI does not change in this regard.
Linux/Hurd:
Since this code introduced a new version name the map
static int last;
file has to change, too.

static int next (void) { VERS_1.0 {

return ++last; global: index;
} local: *;
};
int index1__ (int scale) {
return next () << (scale>0 ? scale : 0); VERS_2.0 {
} global: index; indexp1;
extern int index2__ (int) } VERS_1.0;
__attribute ((alias ("index1__")));
asm(".symver index1__,index@VERS_1.0");
asm(".symver index2__,index@@VERS_2.0");
The important points to note here are that index is men-
int indexp1 (int scale) {
tioned in more than one version, indexp1 only appears
return index2__ (scale) + 1;
} in VERS 2.0, the local: definitions only appear in the
VERS 1.0 definition, and the definition of VERS 2.0 refers
to VERS 1.0. The first point should be obvious: we want
two versions of index to be available, this is what the
Several things need explaining here. First, we do not ex- source code says. The second point is also easy to under-
plicitly define a function index anymore. Instead index1 stand: indexp1 is a new function and was not available
is defined (note the trailing underscore characters; lead- when version 1 of the DSO was released. It is not nec-
ing underscores are reserved for the implementation). This essary to mark the definition of indexp1 in the sources

Ulrich Drepper Version 3.0 35

with a version name. Since there is only one definition
the linker is able to figure this out by itself. VERS_1.0 {
local: *;
The omission of the catch-all local: * case might be };
a bit surprising. There is no local: case at all in the VERS_2.0 {
VERS 2.0 definition. What about internal symbols in- global: index; indexp1;
} VERS_1.0;
troduced in version 2 of the DSO? To understand this it
must be noted that all symbols matched in the local:
part of the version definition do not actually get a version
name assigned. They get a special internal version name
The change consists of removing the index entry from
representing all local symbols assigned. So, the local:
version VERS 1.0 and adding it to VERS 2.0. This leaves
part could appear anywhere, the result would be the same.
no exported symbol in version VERS 1.0 which is OK.
Duplicating local: * could possibly confuse the linker
It would be wrong to remove VERS 1.0 altogether after
since now there are two catch-all cases. It is no problem
moving the local: * case to VERS 2.0. Even if the
to explicitly mention newly introduced local symbols in
move would be done the VERS 1.0 definition must be
the local: cases of new versions, but it is normally not
kept around since this version is named as the predeces-
necessary since there always should be a catch-all case.
sor of VERS 2.0. If the predecessor reference would be
removed as well, programs linked against the old DSO
The fourth point, the VERS 1.0 version being referred
and referencing index in version VERS 1.0 would stop
to in the VERS 2.0 definition, is not really important in
working. Just like symbols, version names must never be
symbol versioning. It marks the predecessor relationship
removed.
of the two versions and it is done to maintain the similar-
ities with Solaris’ internal versioning. It does not cause
The code in this section has one little problem the code
any problem it might in fact be useful to a human reader
for the GNU versioning model in the previous section
so predecessors should always be mentioned.
does not have: the implementation of indexp1 refer-
ences the public symbol index and therefore calls it with
3.6 Handling Compatible Changes (Solaris) a jump to the PLT (which is slower and possibly allows
interposition). The solution for this is left as an exercise
to the user (see section 2.2.7).
The code changes to the code of the last section to handle
Solaris’ internal versioning simplify sources and the map The Solaris runtime linker uses the predecessor imple-
file. Since there can only be one definition of a symbol mentation to determine when it finds an interface not avail-
(and since a symbol cannot be removed there is exactly able with the version found at link-time. If a applica-
one definition) we do not need any alias and we do not tion was linked with the old DSO constructed from the
have to mention index twice in the map file. The source code above it would reference index@VERS 1.0. If the
code would look like this: new DSO is found at runtime the version found would
be index@VERS 2.0. In case such a mismatch is found
the dynamic linker looks into the list of symbols and tries
static int last; all predecessors in turn until all are checked or a match
is found. In our example the predecessor of VERS 2.0
static int next (void) { is VERS 1.0 and therefore the second comparison will
return ++last; succeed.
}
3.7 Incompatible Changes
int index (int scale) {
return next () << (scale>0 ? scale : 0);
}
Incompatible changes can only be handled with the sym-
int indexp1 (int scale) { bol versioning mechanism present on Linux and GNU
return index (scale) + 1; Hurd. For Solaris one has to fall back to the filename
} versioning method.

Having just covered the code for the compatible change,

the differences are not big. For illustration we pick up the
Note that this only works because the previously defined example code once again. This time, instead of making a
semantics of the index function is preserved in the new compatible change to the semantics of index we change
implementation. If this would not be the case this change the interface.
would not qualify as compatible and the whole discussion
would be moot. The equally simplified map file looks like
this: static int last;

36 Version 3.0 How To Write Shared Libraries

 ample, it is no problem at all if different parts of the pro-
static int next (void) {
gram call different versions of the index interface. The
return ++last;
only requirement is that the interface the caller saw at
}
compile time, also is the interface the linker finds when
int index1__ (int scale) { handling the relocatable object file. Since the relocatable
return next () << scale; object file does not contain the versioning information
} it is not possible to keep object files around and hope
asm(".symver index1__,index@VERS_1.0"); the right interface is picked by the linker. Symbol ver-
sioning only works for DSOs and executables. If it is
int index2__ (int scale, int *result) { necessary to reuse relocatable object files later, it is nec-
if (result < 0 essary to recreate the link environment the linker would
|| result >= 8 * sizeof (int)) have seen when the code was compiled. The header files
return -1;
(for C, and whatever other interface specification exists
*result = index1__ (scale);
for other languages) and the DSOs as used by linking to-
return 0;
} gether form the API. It is not possible to separate the two
asm(".symver index2__,index@@VERS_2.0"); steps, compiling and linking. For this reason packaging
systems, which distinguish between runtime and devel-
opment packages, put the headers and linkable DSOs in
one file, while the files needed at runtime are in another.
The interface of index in version VERS 2.0 as imple-
mented in index2 (note: this is the default version as 3.8 Using Versioned DSOs
can be seen by the two @ in the version definition) is quite
different and it can easily be seen that programs which
previously return some more or less sensible value now All methods which depend on symbol versioning have
can crash because *result is written to. This parameter one requirement in common: it is absolutely necessary
would contain garbage if the function would be used with for the users of the DSO to always link with it. This might
an old prototype. The index1 definition is the same as sound like a strange requirement but it actually is not
the previous index implementation. We once again have since it is not necessary to provide definitions for all ref-
to define the real function with an alias since the index erences when creating DSOs. I.e., the linker is perfectly
names get introduced by the .symver pseudo-ops. happy if a symbol is completely undefined in a DSO. It
is only the dynamic linker which would complain: if no
It is characteristic for incompatible changes that the im- object is in scope which defines the undefined symbol the
plementations of the different versions require separate lookup fails.
code. But as in this case one function can often be imple-
mented in terms of the other (the new code using the old This method is sometimes, rarely, a useful method. If a
code as it is the case here, or vice versa). DSO is behaving differently depending on the context it
is loaded in and if the context has to provide some call-
The map file for this example looks very much like the backs which make the DSO complete, using undefined
one for the compatible change: symbols is OK. But this does not extend to definitions
from DSOs which use symbol versioning.

VERS_1.0 { The problem is that unless the DSO containing the defi-
global: index; nitions is used at link time, the linker cannot add a ver-
local: *; sion name to the undefined reference. Following the rules
};
for symbol versioning [4] this means the earliest version
available at runtime is used which usually is not the in-
VERS_2.0 {
global: index; tended version. Going back to the example in section 3.7,
} VERS_1.0; assume the program using the DSO would be compiled
expecting the new interface index2 . Linking happens
without the DSO, which contains the definition. The ref-
erence will be for index and not index@@VERS 2.0. At
We have two definitions of index and therefore the name runtime the dynamic linker will find an unversioned ref-
must be mentioned by the appropriate sections for the two erence and versioned definitions. It will then select the
versions. oldest definition which happens to be index1 . The re-
sult can be catastrophic.
It might also be worthwhile pointing out once again that
the call to index1 in index2 does not use the PLT It is therefore highly recommended to never depend on
and is instead a direct, usually PC-relative, jump. undefined symbols. The linker can help to ensure this if
-Wl,-z,defs is added to compiler command line. If it
With a simple function definition, like the one in this ex- is really necessary to use undefined symbols the newly

Ulrich Drepper Version 3.0 37

built DSO should be examined to make sure that all ref- This will add the two named directories to the run path
erences to symbols in versioned DSOs are appropriately in the order in which say appear on the command line. If
marked. more than one -rpath/-R option is given the parameters
will be concatenated with a separating colon. The order
3.9 Inter-Object File Relations is once again the same as on the linker command line.
For compatibility reasons with older version of the linker
DT RPATH entries are created by default. The linker op-
Part of the ABI is also the relationship between the var- tion --enable-new-dtags must be used to also add
ious participating executables and DSOs which are cre- DT RUNPATH entry. This will cause both, DT RPATH and
ated by undefined references. It must be ensured that DT RUNPATH entries, to be created.
the dynamic linker can locate exactly the right DSOs at
program start time. The static linker uses the SONAME There are a number of pitfalls one has to be aware of
of a DSO in the record to specify the interdependencies when using run paths. The first is that an empty path
between two objects. The information is stored in the represents the current working directory (CWD) of the
DT NEEDED entries in the dynamic section of the object process at runtime. One can construct such an empty path
with the undefined references. Usually this is only a file by explicitly adding such a parameter (-Wl,-R,"") but
name, without a complete path. It is then the task of the also, and this is the dangerous part, by two consecutive
dynamic linker to find the correct file at startup time. colons or a colon at the beginning or end of the string.
That means the run path value ”:/home::/usr:” searches
This can be a problem, though. By default the dynamic the CWD, home, the CWD again, usr, and finally the
linker only looks into a few directories to find DSOs (on CWD again.12 It is very easy to add such an empty path.
Linux, in exactly two directories, /lib and /usr/lib). Makefiles often contain something like this:
More directories can be added by naming them in the
/etc/ld.so.conf file which is always consulted by
the dynamic linker. Before starting the application, the RPATH = $(GLOBAL\_RPATH):$(LOCAL\_RPATH)
user can add LD LIBRARY PATH to the environment of LDFLAGS += -Wl,-rpath,$(RPATH)
the process. The value is another list of directories which
are looked at.

But all this means that the selection of the directories is If either GLOBAL RPATH or LOCAL RPATH is empty the
under the control of the administrator. The program’s au- dynamic linker will be forced to look in the CWD. When
thor can influence these setting only indirectly by doc- constructing strings one must therefore always be careful
umenting the needs. But there is also way for the pro- about empty strings.
grammer to decide the path directly. This is sometimes
important. The system’s setting might not be usable by The second issue run paths have is that either that paths
all programs at the same time. like /usr/lib/someapp are not “relocatable”. I.e., the
package cannot be installed in another place by the user
For each object, DSO as well as executable, the author without playing tricks like creating symbolic links from
can define a “run path”. The dynamic linker will use the /usr/lib/someapp to the real directory. The use of rel-
value of the path string when searching for dependencies ative paths is possible, but highly discouraged. It might
of the object the run path is defined in. Run paths comes be OK in application which always control their CWD,
is two variants, of which one is deprecated. The runpaths but in DSOs which are used in more than one application
are accessible through entries in the dynamic section as using relative paths means calling for trouble since the
field with the tags DT RPATH and DT RUNPATH. The dif- application can change the CWD.
ference between the two value is when during the search
for dependencies they are used. The DT RPATH value is A solution out of the dilemma is an extension syntax for
used first, before any other path, specifically before the all search paths (run paths, but also LD LIBRARY PATH).
path defined in the LD LIBRARY PATH environment vari- If one uses the string $ORIGIN this will represent the ab-
able. This is problematic since it does not allow the user solute path of the directory the file containing this run
to overwrite the value. Therefore DT RPATH is depre- path is in. One common case for using this “dynamic
cated. The introduction of the new variant, DT RUNPATH, string token” (DST) is a program (usually installed in a
corrects this oversight by requiring the value is used after bin/ directory) which comes with one or more DSOs it
the path in LD LIBRARY PATH. needs, which are installed in the corresponding lib/ di-
rectory. For instance the paths could be /bin and /lib
If both a DT RPATH and a DT RUNPATH entry are avail- or /usr/bin and /usr/lib. In such a case the run
able, the former is ignored. To add a string to the run path of the application could contain $ORIGIN/../lib
path one must use the -rpath or -R for the linker. I.e., which will expand in the examples case just mentioned
on the gcc command line one must use something like to /bin/../lib and /usr/bin/../lib respectively.
12 The dynamic linker is of course free to avoid the triple search since

gcc -Wl,-rpath,/some/dir:/dir2 file.o after the first one it knows the result.

38 Version 3.0 How To Write Shared Libraries

The effective path will therefore point to the appropriate programmer can still name all the DSOs which might be
lib/ directory. needed at all times. The linker does all the hard work.

$ORIGIN is not the only DST available. The GNU libc This process should not be executed mindlessly, though.
dynamic currently recognizes two more. The first is $LIB Not having the DSO on the direct dependency list any-
which is useful on platforms which can run in 32- and 64- more means the symbol lookup path is altered. If the
bit mode (maybe more in future). On such platforms the DSO in question contains a definition of a symbol which
replacement value in 32-bit binaries is lib and for 64- also appears in a second DSO and now that second DSO
bit binaries it is lib64. This is what the system ABIs is earlier in the lookup path, the program’s semantics
specify as the directories for executable code. If the plat- might be altered. This is a rare occurrence, though.
form does not know more than one mode the replacement
value is lib. This DST makes it therefore easy to write
Makefiles creating the binaries since no knowledge about
the differentiation is needed.

The last DST is $PLATFORM. It is replaced by the dy-

namic linker with an architecture-specific string repre-
senting the name of the platform (as the name suggests).
For instance, it will be replaced with i386 or i686 on
IA-32 machines, depending on the CPU(s) used. This al-
lows using better optimized versions of a DSO if the CPU
supports it. On system with the GNU libc this is gener-
ally not needed since the dynamic linker by itself and by
default looks for such subdirectories. The actual rules are
quite complicated and not further discussed here. What
is important to remember is that the $PLATFORM DST is
not really useful; it is mainly available for compatibility
with Solaris’s dynamic linker.

Another aspect of DT NEEDED entries worth looking at

is whether they are necessary in the first place. Espe-
cially when the above guideline of using the -z defs
linker option is followed, many projects name all kinds of
DSOs on the linker command line, whether they are re-
ally needed or not in the specific case. This problem is in-
tensified with useless wrappers like pkg-config which
just add tons of dependencies to the link time. This might
have been OK in the days of static linking, but the de-
fault for DSOs appearing on the linker command line
is, that they are always added to the result’s dependency
list, whether they are actually used or not. To determine
whether an executable or DSO has such unnecessary de-
pendencies the ldd script can be used:

$ ldd -u -r \
/usr/lib/libgtk-x11-2.0.so.0.600.0
Unused direct dependencies:

/usr/lib/libpangox-1.0.so.0
/lib/libdl.so.2

These references can be manually eliminated by avoiding

to name the DSO on the linker command line. Alterna-
tively the --as-needed linker option can be used. If
this option is used, all DSOs named on the command line
after the option are only added to the dependency list if
they are really needed. This mode can be disabled again
with the --no-as-needed option. This way the lazy

Ulrich Drepper Version 3.0 39

A Counting Relocations

The following script computes the number of normal and relative relocations as well as the number of PLT entries
present in a binary. If an appropriate readelf implementation is used it can also be used to look at all files in an
archive. If prelink [7] is available and used, the script also tries to provide information about how often the DSO is
used. This gives the user some idea how much “damage” an ill-written DSO causes.

#! /usr/bin/perl
eval "exec /usr/bin/perl -S $0 $*"
if 0;
# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Red Hat, Inc.
# Written by Ulrich Drepper <[email protected]>, 2000.

# This program is free software; you can redistribute it and/or modify

# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */

for ($cnt = 0; $cnt <= $#ARGV; ++$cnt) {

$relent = 0;
$relsz = 0;
$relcount = 0;
$pltrelsz = 0;
$extplt = 0;
$users = 0;

open (READLINK, "readlink -f $ARGV[$cnt] |") || die "cannot open readlink";

while (<READLINK>) {
chop;
$fullpath = $_;
}
close (READLINK);

open (READELF, "eu-readelf -d $ARGV[$cnt] |") || die "cannot open $ARGV[$cnt]";

while (<READELF>) {
chop;
if (/.* \(RELENT\) *([0-9]*).*/) {
$relent = $1 + 0;
} elsif (/.* \(RELSZ\) *([0-9]*).*/) {
$relsz = $1 + 0;
} elsif (/.* \(RELCOUNT\) *([0-9]*).*/) {
$relcount = $1 + 0;
} elsif (/.* \(PLTRELSZ\) *([0-9]*).*/) {
$pltrelsz = $1 + 0;
}
}
close (READELF);

open (READELF, "eu-readelf -r $ARGV[$cnt] |") || die "cannot open $ARGV[$cnt]";

while (<READELF>) {
chop;
if (/.*JU?MP_SLOT *0+ .*/) {
++$extplt;
}
}

40 Version 3.0 How To Write Shared Libraries

 close (READELF);

if (open (PRELINK, "/usr/sbin/prelink -p 2>/dev/null | fgrep \"$fullpath\" |")) {

while (<PRELINK>) {
++$users;
}
close(PRELINK);
} else {
$users = -1;
}

printf("%s: %d relocations, %d relative (%d%%), %d PLT entries, %d for local syms (%d%%)",
$ARGV[$cnt], $relent == 0 ? 0 : $relsz / $relent, $relcount,
$relent == 0 ? 0 : ($relcount * 100) / ($relsz / $relent),
$relent == 0 ? 0 : $pltrelsz / $relent,
$relent == 0 ? 0 : $pltrelsz / $relent - $extplt,
$relent == 0 ? 0 : ((($pltrelsz / $relent - $extplt) * 100)
/ ($pltrelsz / $relent)));
if ($users >= 0) {
printf(", %d users", $users);
}
printf("\n");
}

Ulrich Drepper Version 3.0 41

B Automatic Handler of Arrays of String Pointers

The method to handle arrays of string pointers presented in section 2.4.3 show the principle method to construct data
structures which do not require relocations. But the construction is awkward and error-prone. Duplicating the strings
in multiple places in the sources always has the problem of keeping them in sync.

Bruno Haible suggested something like the following to automatically generate the tables. The programmer only has
to add the strings, appropriately marked, to a data file which is used in the compilation. The framework in the actual
sources looks like this:

#include <stddef.h>

#define MSGSTRFIELD(line) MSGSTRFIELD1(line)

#define MSGSTRFIELD1(line) str##line
static const union msgstr_t {
struct {
#define _S(n, s) char MSGSTRFIELD(__LINE__)[sizeof(s)];
#include "stringtab.h"
#undef _S
};
char str[0];
} msgstr = { {
#define _S(n, s) s,
#include "stringtab.h"
#undef _S
} };
static const unsigned int msgidx[] = {
#define _S(n, s) [n] = offsetof(union msgstr_t, MSGSTRFIELD(__LINE__)),
#include "stringtab.h"
#undef _S
};

const char *errstr (int nr) {

return msgstr.str + msgidx[nr];
}

The string data has to be provided in the file stringtab.h. For the example from section 2.4.3 the data would look
like this:

_S(ERR1, "message for err1")

_S(ERR3, "message for err3")
_S(ERR2, "message for err2")

The macro S takes two parameters: the first is the index used to locate the string and the second is the string itself.
The order in which the strings are provided is not important. The value of the first parameter is used to place the offset
in the correct slot of the array. It is worthwhile running these sources through the preprocessor to see the results. This
way of handling string arrays has the clear advantage that strings have to be specified only in one place and that the
order they are specified in is not important. Both these issues can otherwise easily lead to very hard to find bugs.

The array msgidx in this cases uses the type unsigned int which is in most cases 32 bits wide. This is usually far
too much to address all bytes in the string collectionin msgstr. So, if size is an issue the type used could be uint16 t
or even uint8 t.

Note that both arrays are marked with const and therefore are not only stored in the read-only data segment and there-
fore shared between processes, preserving, precious data memory, making the data read-only also prevents possible
security problems resulting from overwriting values which can trick the program into doing something harmful.

42 Version 3.0 How To Write Shared Libraries

C Index
default symbol, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
--as-needed, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 default visibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17f.
--no-as-needed, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 destructor, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
--shared, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 DF BIND NOW, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
--version-script, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 DF DYNAMIC, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
-fno-common, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14f. DF SYMBOLIC, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 18, 24
-fpic, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10, 13 DF TEXTREL, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
-fvisibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 DL CALL FCT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
-fvisibility-inlines-hidden, . . . . . . . . . . . . . . . . . 19 dlopen(), . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 31
-rpath, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 dlsym(), . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
-z defs, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37, 39 documented interface, . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
-z now, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 31 DSO, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
-z relro, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 DST, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
.symver, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35f. DT FLAGS, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 24
@GOT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10, 16, 21 DT NEEDED, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 33, 38f.
@GOTOFF, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 21, 29 DT RPATH, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
@PLT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10, 16 DT RUNPATH, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
$LIB, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 DT SONAME, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
$ORIGIN, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 DT SYMBOLIC, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18, 24
$PLATFORM, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 DT TEXTREL, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
dynamic linker, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 4
ABI, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32, 34
dynamic shared object, . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
versioning, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
dynamic string token, . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
absolute address, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
access permission, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
ELF, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Ada names, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
entry point, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
adding symbols, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
exception handling, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
address space, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
executable linkage format, . . . . . . . . . . . . . . . . . . . . . . . . 2
aliases, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23, 35
execve(), . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
alternative entry point, . . . . . . . . . . . . . . . . . . . . . . . . . . 22
export map, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
anonymous version map, . . . . . . . . . . . . . . . . . . . . . . . . 34
a.out, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1f.
file-local scope, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
API, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32, 34
filename versioning, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
auxiliary vector, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
fini, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

binary format, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 function array, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

BSS section, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 function attribute, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
function semantics, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C++
classes, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 gABI, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
names, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 global offset table, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
typeinfo, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 GNU, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
virtual function table, . . . . . . . . . . . . . . . . . . . . . . . 28 versioning, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35f.
chain length, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 GOT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10, 30
class visibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 attacking, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
code generation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 gprof, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
COFF, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
common variable, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 hash chain, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
compatibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 hidden visibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17f.
compatibility symbol, . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Hurd, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34f.
compatible changes, . . . . . . . . . . . . . . . . . . . . . . . . . 33, 35
computed goto, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 IA-32, . . . . . . . . . . . . . . . . . . . . . . . . . 10f., 13, 16, 29f., 32
constant data, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25, 31 IA-64, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29f.
constructor, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 implementation-defined behavior, . . . . . . . . . . . . . . . . 32
copy relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 incompatible changes, . . . . . . . . . . . . . . . . . . . . . . . 34, 36
cost of relocations, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 init, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
initialized variable, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
deep binding, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 interposition, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 10

Ulrich Drepper Version 3.0 43

lazy relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 5, 30 shared object name, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
LD BIND NOW, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 33 SHF MERGE, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
ldd, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 SHF STRINGS, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
LD DEBUG, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 13 Solaris, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20, 33–36
LD LIBRARY PATH, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 SONAME, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31, 33f., 38
LD PRELOAD, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 sprof, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
LD PROFILE, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24, 31 stable interface, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
libtool, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 22 startup costs, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Linux,. . . . . . . . . . . . . . . . . . . . . . . .1f., 7, 11, 31, 34f., 38 static linking, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
load address, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1ff. STV HIDDEN, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
lookup process, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 string definitions, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
lookup scope, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 8 STV DEFAULT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
successful lookup, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
member function, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 switch, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
memory page, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 symbol alias, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
memory protection, . . . . . . . . . . . . . . . . . . . . . . . . . 3f., 30 symbol export, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15, 34
mmap(), . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 symbol reference, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
mprotect(), . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 symbol relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 28
symbol versioning, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33f.
name mangling, . . . . . . . . . . . . . . . . . . . . . . . . . 7, 21, 23f.
symbol visibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
non-lazy relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
text relocation, . . . . . . . . . . . . . . . . . . . . . . . 5, 13f., 29, 31
object file, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
text segment, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
OpenOffice.org, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
overhead, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 undefined behavior, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
undefined symbol, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
PC-relative, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 21, 29
uninitialized variable, . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
PIC register, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10, 29
unsuccessful lookup, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
PIE, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 31
PLT, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 versioning, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
attacking, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
pointer array, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 wrapper function, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
position independent executable, . . . . . . . . . . . . . . . 2, 31 write access, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
pragma visibility, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17, 20
pre-linking, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 x86-64, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29f.
procedure linkage table, . . . . . . . . . . . . . . . . . . . . . . . . . 10
profiling, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
program header, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
psABI, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 11
PT GNU RELRO, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
PT INTERP, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
PT LOAD, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3f.

read-only memory, . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 25
relative address, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
relative relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 28
relinfo, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
relocatable binary, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
relocatable object file, . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
relocation, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
counting, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
RTLD DEEPBIND, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
RTLD GLOBAL, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
run path, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

scope, lookup, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
security, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11, 30
Security Enhanced Linux, . . . . . . . . . . . . . . . . . . . . . . . 31
segment, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
SELinux, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
shared library, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

44 Version 3.0 How To Write Shared Libraries

D References
[1] System V Application Binary Interface, http://www.caldera.com/developers/gabi/, 2001.
[2] Ulrich Drepper, Red Hat, Inc., ELF Handling For Thread-Local Storage, http://people.redhat.com/drepper/tls.pdf,
2003.
[3] Ulrich Drepper, Red Hat, Inc., Good Practices in Library Design, Implementation, and Maintenance,
http://people.redhat.com/drepper/goodpractices.pdf, 2002.
[4] Ulrich Drepper, Red Hat, Inc., ELF Symbol Versioning, http://people.redhat.com/drepper/symbol-versioning, 1999.
[5] Sun Microsystems, Linker and Library Guide, http://docs.sun.com/db/doc/816-1386, 2002.
[6] TIS Committee, Executable and Linking Format (ELF) Specification, Version 1.2,
http://x86.ddj.com/ftp/manuals/tools/elf.pdf, 1995.
[7] Jakub Jelinek, Red Hat, Inc., Prelink, http://people.redhat.com/jakub/prelink.pdf, 2003.
[8] Security Enhanced Linux http://www.nsa.gov/selinux/.

E Revision History

2002-11-2 First public draft.

2002-11-8 Fixed a couple of typos.
Document one more possibility for handling arrays of string pointers.
Describe PLT on IA-32 in more details.

2002-11-14 Document implications of using C++ virtual functions.

2003-1-20 Incorporate several suggestions by Bruno Haible.
Describe visibility attribute and aliasing in C++ code.
2003-2-9 Some more cleanups. Version 1.0 release.
2003-2-27 Minor language cleanup. Describe using export maps with C++. Version 1.1.
2003-3-18 Some more linguistic changes. Version 1.2.
2003-4-4 Document how to write constructor/destructors. Version 1.3.
2003-12-8 Describe how to use run paths. Version 1.4.
2003-12-9 Add section about avoided PIC reload. Version 1.5.
2004-2-4 Fix some typos. Explain optimizations gcc does without -fpic. Explain -z relro. Version 1.7.
2004-2-8 Introduce the lookup scope in more details. Version 1.9.

2004-8-4 Warn about aliases of static objects. Significant change to section 2.2 to introduce new features of gcc 4.0.
Version 1.99.
2004-8-27 Update code in appendices A and B. Version 2.0.
2004-9-23 Document RTLD DEEPBIND and sprof. Version 2.2.

2005-1-22 Brushed up language in many places. Add Index. Version 3.0.

Ulrich Drepper Version 3.0 45