Defining Additional Symbols
Besides the symbols provided from input files, you can supply additional global symbol references or global symbol definitions to a link-edit. In the simplest form, symbol references can be generated using the link-editor's -u option. Greater flexibility is provided with the link-editor's -M option and an associated mapfile. This mapfile enables you to define global symbol references and a variety of global symbol definitions. Attributes of the symbol such as visibility and type can be specified, See SYMBOL_SCOPE / SYMBOL_VERSION Directives for a complete description of the available options.
Defining Additional Symbols with the -u option
The -u option provides a mechanism for generating a global symbol reference from the link-edit command line. This option can be used to perform a link-edit entirely from archives. This option can also provide additional flexibility in selecting the objects to extract from multiple archives. See section Archive Processing for an overview of archive extraction.
For example, perhaps you want to generate a dynamic executable from the relocatable object main.o, which refers to the symbols foo and bar. You want to obtain the symbol definition foo from the relocatable object foo.o contained in lib1.a, and the symbol definition bar from the relocatable object bar.o, contained in lib2.a.
However, the archive lib1.a also contains a relocatable object that defines the symbol bar. This relocatable object is presumably of differing functionality to the relocatable object that is provided in lib2.a. To specify the required archive extraction, you can use the following link-edit.
$ cc -o prog -L. -u foo -l1 main.o -l2 |
The -u option generates a reference to the symbol foo. This reference causes extraction of the relocatable object foo.o from the archive lib1.a. The first reference to the symbol bar occurs in main.o, which is encountered after lib1.a has been processed. Therefore, the relocatable object bar.o is obtained from the archive lib2.a.
Note –
This simple example assumes that the relocatable object foo.o from lib1.a does not directly or indirectly reference the symbol bar. If lib1.a does reference bar, then the relocatable object bar.o is also extracted from lib1.a during its processing. See Archive Processing for a discussion of the link-editor's multi-pass processing of an archive.
Defining Symbol References
The following example shows how three symbol references can be defined. These references are then used to extract members of an archive. Although this archive extraction can be achieved by specifying multiple -u options to the link-edit, this example also shows how the eventual scope of a symbol can be reduced to local.
$ cat foo.c
#include <stdio.h>
void foo()
{
(void) printf("foo: called from lib.a\n");
}
$ cat bar.c
#include <stdio.h>
void bar()
{
(void) printf("bar: called from lib.a\n");
}
$ cat main.c
extern void foo(), bar();
void main()
{
foo();
bar();
}
$ cc -c foo.c bar.c main.c
$ ar -rc lib.a foo.o bar.o main.o
$ cat mapfile
$mapfile_version 2
SYMBOL_SCOPE {
local:
foo;
bar;
global:
main;
};
$ cc -o prog -M mapfile lib.a
$ prog
foo: called from lib.a
bar: called from lib.a
$ elfdump -sN.symtab prog | egrep 'main$|foo$|bar$'
[29] 0x00010f30 0x00000024 FUNC LOCL H 0 .text bar
[30] 0x00010ef8 0x00000024 FUNC LOCL H 0 .text foo
[55] 0x00010f68 0x00000024 FUNC GLOB D 0 .text main
|
The significance of reducing symbol scope from global to local is covered in more detail in the section Reducing Symbol Scope.
Defining Absolute Symbols
The following example shows how two absolute symbol definitions can be defined. These definitions are then used to resolve the references from the input file main.c.
$ cat main.c
#include <stdio.h>
extern int foo();
extern int bar;
void main()
{
(void) printf("&foo = 0x%p\n", &foo);
(void) printf("&bar = 0x%p\n", &bar);
}
$ cat mapfile
$mapfile_version 2
SYMBOL_SCOPE {
global:
foo { TYPE=FUNCTION; VALUE=0x400 };
bar { TYPE=DATA; VALUE=0x800 };
};
$ cc -o prog -M mapfile main.c
$ prog
&foo = 0x400
&bar = 0x800
$ elfdump -sN.symtab prog | egrep 'foo$|bar$'
[45] 0x00000800 0x00000000 OBJT GLOB D 0 ABS bar
[69] 0x00000400 0x00000000 FUNC GLOB D 0 ABS foo
|
When obtained from an input file, symbol definitions for functions or data items are usually associated with elements of data storage. A mapfile definition is insufficient to be able to construct this data storage, so these symbols must remain as absolute values. A simple mapfile definition that is associated with a size, but no value results in the creation of data storage. In this case, the symbol definition is accompanied with a section index. However, a mapfile definition that is accompanied with a value results in the creation of an absolute symbol. If a symbol is defined in a shared object, an absolute definition should be avoided. See Augmenting a Symbol Definition.
Defining Tentative Symbols
A mapfile can also be used to define a COMMON, or tentative, symbol. Unlike other types of symbol definition, tentative symbols do not occupy storage within a file, but define storage that must be allocated at runtime. Therefore, symbol definitions of this kind can contribute to the storage allocation of the output file being generated.
A feature of tentative symbols that differs from other symbol types is that their value attribute indicates their alignment requirement. A mapfile definition can therefore be used to realign tentative definitions that are obtained from the input files of a link-edit.
The following example shows the definition of two tentative symbols. The symbol foo defines a new storage region whereas the symbol bar is actually used to change the alignment of the same tentative definition within the file main.c.
$ cat main.c
#include <stdio.h>
extern int foo;
int bar[0x10];
void main()
{
(void) printf("&foo = 0x%p\n", &foo);
(void) printf("&bar = 0x%p\n", &bar);
}
$ cat mapfile
$mapfile_version 2
SYMBOL_SCOPE {
global:
foo { TYPE=COMMON; VALUE=0x4; SIZE=0x200 };
bar { TYPE=COMMON; VALUE=0x102; SIZE=0x40 };
};
$ cc -o prog -M mapfile main.c
ld: warning: symbol 'bar' has differing alignments:
(file mapfile value=0x102; file main.o value=0x4);
largest value applied
$ prog
&foo = 0x21264
&bar = 0x21224
$ elfdump -sN.symtab prog | egrep 'foo$|bar$'
[45] 0x00021224 0x00000040 OBJT GLOB D 0 .bss bar
[69] 0x00021264 0x00000200 OBJT GLOB D 0 .bss foo
|
Note –
This symbol resolution diagnostic can be suppressed by using the link-editor's -t option.
Augmenting a Symbol Definition
The creation of an absolute data symbol within a shared object should be avoided. An external reference from a dynamic executable to a data item within a shared object typically requires the creation of a copy relocation. See Copy Relocations. To provide for this relocation, the data item should be associated with data storage. This association can be produced by defining the symbol within a relocatable object file. This association can also be produced by defining the symbol within a mapfile together with a size declaration and no value declaration. See SYMBOL_SCOPE / SYMBOL_VERSION Directives.
A data symbol can be filtered. See Shared Objects as Filters. To provide this filtering, an object file definition can be augmented with a mapfile definition. The following example creates a filter containing a function and data definition.
$ cat mapfile
$mapfile_version 2
SYMBOL_SCOPE {
global:
foo { TYPE=FUNCTION; FILTER=filtee.so.1 };
bar { TYPE=DATA; SIZE=0x4; FILTER=filtee.so.1 };
local:
*;
};
$ cc -o filter.so.1 -G -Kpic -h filter.so.1 -M mapfile -R.
$ elfdump -sN.dynsym filter.so.1 | egrep 'foo|bar'
[1] 0x000105f8 0x00000004 OBJT GLOB D 1 .data bar
[7] 0x00000000 0x00000000 FUNC GLOB D 1 ABS foo
$ elfdump -y filter.so.1 | egrep 'foo|bar'
[1] F [0] filtee.so.1 bar
[7] F [0] filtee.so.1 foo
|
At runtime, a reference from an external object to either of these symbols is resolved to the definition within the filtee.
- © 2010, Oracle Corporation and/or its affiliates