10.4.6. Symbol Management Options¶

The options listed in the subsections below control how the linker manages symbols. On the tiarmclang command-line they should be passed to the linker using the -Wl or -Xlinker option as described in Passing Options to the Linker.

Option Summary
Define an Entry Point (--entry_point Option)
Change Symbol Localization (--globalize and --localize options)
Make All Global Symbols Static (--make_static Option)
Hiding Symbols (--hide and --unhide options)
Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)
Strip Symbolic Information (--no_symtable Option)
Retain Discarded Sections (--retain Option)
Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries Option)
Mapping of Symbols (--symbol_map Option)
Introduce an Unresolved Symbol (--undef_sym Option)

10.4.6.1. Option Summary ¶

--entry_point (-e)¶: Defines a global symbol that specifies the primary entry point for the output module. See Define an Entry Point (--entry_point Option).

--globalize¶: Changes the symbol linkage to global for symbols that match pattern. See Hiding Symbols (--hide and --unhide options).

--hide¶: Hides global symbols that match pattern. See Hiding Symbols (--hide and --unhide options).

--localize¶: Changes the symbol linkage to local for symbols that match pattern. See Change Symbol Localization (--globalize and --localize options).

--make_global (-g)¶: Makes symbol global (overrides -h). See Make All Global Symbols Static (--make_static Option).

--make_static (-h)¶: Makes all global symbols static. See Make All Global Symbols Static (--make_static Option).

--no_sym_merge (-s)¶: Disables merging of symbolic debugging information. See Disable Merging of Symbolic Debugging Information (--no_sym_merge Option).

--no_symtable (-s)¶: Strips symbol table information and line number entries from the output module. See Strip Symbolic Information (--no_symtable Option).

--retain¶: Retains a list of sections that otherwise would be discarded. See Retain Discarded Sections (--retain Option).

--scan_libraries (-scanlibs)¶: Scans all libraries for duplicate symbol definitions. See Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries Option).

--symbol_map¶: Maps symbol references to a symbol definition of a different name. See Mapping of Symbols (--symbol_map Option).

--undef_sym (-u)¶: Places an unresolved external symbol into the output module’s symbol table. See Introduce an Unresolved Symbol (--undef_sym Option).

--unhide¶: Reveals (un-hides) global symbols that match pattern. See Hiding Symbols (--hide and --unhide options).

10.4.6.2. Define an Entry Point (--entry_point Option)¶

The memory address at which a program begins executing is called the entry point. When a loader loads a program into target memory, the program counter (PC) must be initialized to the entry point; the PC then points to the beginning of the program.

The linker can assign one of four values to the entry point. These values are listed below in the order in which the linker tries to use them. If you use one of the first three values, it must be an external symbol in the symbol table.

The value specified by the --entry_point option. The syntax is --entry_point=global_symbol where global_symbol defines the entry point and must be defined as an external symbol of the input files. The external symbol name of C or C++ objects may be different than the name as declared in the source language. See Entry Point.
The value of symbol _c_int00 (if present). The _c_int00 symbol must be the entry point if you are linking code produced by the C compiler.
The value of symbol _main (if present)
0 (default value)

This example links file1.c.o and file2.c.o. The symbol begin is the entry point; begin must be defined as external in file1 or file2.

tiarmclang -Wl,--entry_point=begin file1.c.o file2.c.o

See Using Linker Symbols in C/C++ Applications for information about referring to linker symbols in C/C++ code.

10.4.6.3. Change Symbol Localization (--globalize and --localize options)¶

Symbol localization changes symbol linkage from global to local (static). This is used to obscure global symbols that should not be widely visible, but must be global because they are accessed by several modules in the library. The linker supports symbol localization through the --localize and --globalize linker options.

The syntax for these options are:

--localize='pattern'

--globalize='pattern'

The pattern is a “glob” (a string with optional ? or * wildcards). Use ? to match a single character. Use * to match zero or more characters.

The --localize option changes the symbol linkage to local for symbols matching the pattern.

The --globalize option changes the symbol linkage to global for symbols matching the pattern. The --globalize option only affects symbols that are localized by the --localize option. The --globalize option excludes symbols that match the pattern from symbol localization, provided the pattern defined by --globalize is more restrictive than the pattern defined by --localize.

See Specifying C/C++ Symbols with Linker Options for information about using C/C++ identifiers in linker options such as --localize and --globalize.

These options have the following properties:

The --localize and --globalize options can be specified more than once on the command line.
The order of --localize and --globalize options has no significance.
A symbol is matched by only one pattern defined by either --localize or --globalize.
A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
It is an error if a symbol matches patterns from --localize and --globalize and if one does not supersede other. Pattern A supersedes pattern B if A can match everything B can, and some more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
These options affect final and partial linking.

In map files these symbols are listed under the Localized Symbols heading.

10.4.6.4. Make All Global Symbols Static (--make_static Option)¶

The --make_static option makes all global symbols static. Static symbols are not visible to externally linked modules. By making global symbols static, global symbols are essentially hidden. This allows external symbols with the same name (in different files) to be treated as unique.

The --make_static option effectively nullifies all .global assembler directives. All symbols become local to the module in which they are defined, so no external references are possible. For example, assume file1.c.o and file2.c.o both define global symbols called EXT. By using the --make_static option, you can link these files without conflict. The symbol EXT defined in file1.c.o is treated separately from the symbol EXT defined in file2.c.o.

tiarmclang -Wl,--make_static file1.c.o file2.c.o

The --make_static option makes all global symbols static. If you have a symbol that you want to remain global and you use the --make_static option, you can use the --make_global option to declare that symbol to be global. The --make_global option overrides the effect of the --make_static option for the symbol that you specify. The syntax for the --make_global option is:

--make_global=global_symbol

10.4.6.5. Hiding Symbols (--hide and --unhide options)¶

Symbol hiding prevents the symbol from being listed in the output file’s symbol table. While localization is used to prevent name space clashes in a link unit (see Change Symbol Localization (--globalize and --localize options)), symbol hiding is used to obscure symbols that should not be visible outside a link unit. Such symbol names appear only as empty strings or “no name” in object file readers. The linker supports symbol hiding through the --hide and --unhide options.

The syntax for these options are:

--hide='pattern'

--unhide='pattern'

The pattern is a “glob” (a string with optional ? or * wildcards). Use ? to match a single character. Use * to match zero or more characters.

The --hide option hides global symbols with a linkname matching the pattern. It hides symbols matching the pattern by changing the name to an empty string. A global symbol that is hidden is also localized.

The --unhide option reveals (un-hides) global symbols that match the pattern that are hidden by the --hide option. The --unhide option excludes symbols that match pattern from symbol hiding provided the pattern defined by --unhide is more restrictive than the pattern defined by --hide.

These options have the following properties:

The --hide and --unhide options can be specified more than once on the command line.
The order of --hide and --unhide has no significance.
A symbol is matched by only one pattern defined by either --hide or --unhide.
A symbol is matched by the most restrictive pattern. Pattern A is considered more restrictive than Pattern B, if Pattern A matches a narrower set than Pattern B.
It is an error if a symbol matches patterns from --hide and --unhide and one does not supersede the other. Pattern A supersedes pattern B if A can match everything B can and more. If Pattern A supersedes Pattern B, then Pattern B is said to more restrictive than Pattern A.
These options affect final and partial linking.

In map files these symbols are listed under the Hidden Symbols heading.

10.4.6.6. Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)¶

By default, the linker eliminates duplicate entries of symbolic debugging information. Such duplicate information is commonly generated when a C program is compiled for debugging. For example:

-[ header.h ]-
typedef struct
{
     <define some structure members>
} XYZ;

-[ f1.c ]-
#include "header.h"
...

-[ f2.c ]-
#include "header.h"
...

When these files are compiled for debugging, both f1.c.o and f2.c.o have symbolic debugging entries to describe type XYZ. For the final output file, only one set of these entries is necessary. The linker eliminates the duplicate entries automatically.

10.4.6.7. Strip Symbolic Information (--no_symtable Option)¶

The --no_symtable option creates a smaller output module by omitting symbol table information and line number entries. The --no_symtable option is useful for production applications when you do not want to disclose symbolic information to the consumer.

This example links file1.c.o and file2.c.o and creates an output module, stripped of line numbers and symbol table information, named nosym.out:

tiarmclang -Wl,--output_file=nosym.out,--no_symtable file1.c.o file2.c.o

Using the --no_symtable option limits later use of a symbolic debugger.

Note

Stripping Symbolic Information The --no_symtable option is deprecated. To remove symbol table information, use the armstrip utility as described in tiarmstrip - Object File Stripping Tool.

10.4.6.8. Retain Discarded Sections (--retain Option)¶

When --unused_section_elimination is on, the ELF linker does not include a section in the final link if it is not needed in the executable to resolve references. The --retain option tells the linker to retain a list of sections that would otherwise not be retained. This option accepts the wildcards * and ?. When wildcards are used, the argument should be in quotes. The syntax for this option is:

--retain=sym_or_scn_spec

The --retain option takes one of the following forms:

--retain=symbol_spec¶: Specifying the symbol format retains sections that define symbol_spec. For example, this code retains sections that define symbols that start with init:

--retain="init*"

You cannot specify --retain=”*”.

--retain=file_spec(scn_spec[, scn_spec, ...])¶

Specifying the file format retains sections that match one or more scn_spec from files matching the file_spec. For example, this code retains .intvec sections from all input files:

--retain="*(.int*)"

You can specify --retain=”*(*)” to retain all sections from all input files. However, this does not prevent sections from library members from being optimized out.

--retain=ar_spec<mem_spec, [mem_spec, ...>(scn_spec[, scn_spec, ...])¶: Specifying the archive format retains sections matching one or more scn_spec from members matching one or more mem_spec from archive files matching ar_spec. For example, this code retains the .text sections from printf.c.o in the libc.a library:

--retain=-llibc.a<printf.c.o>(.text)

If the library is specified with the --library or -l option (-llibc.a) the library search path is used to search for the library.

Note

Using “*<*>(scn_spec)” or “*<*>(*)” as the argument to --retain will be ignored

You cannot specify “*<*>(scn_spec)” or “*<*>(*)” as the argument to a --retain option. Either of these arguments will be detected and ignored with a warning diagnostic by the linker. If allowed, the linker would try to scan all object file members of all libraries referenced in the linker invocation, including any that are mentioned in linker command files that are referenced. This would also include all C++, C, and compiler runtime libraries that are implicitly referenced from the tiarmclang command line during a link.

10.4.6.9. Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries Option)¶

The --scan_libraries option scans all libraries during a link looking for duplicate symbol definitions to those symbols that are actually included in the link. The scan does not consider absolute symbols or symbols defined in COMDAT sections. The --scan_libraries option helps determine those symbols that were actually chosen by the linker over other existing definitions of the same symbol in a library.

The library scanning feature can be used to check against unintended resolution of a symbol reference to a definition when multiple definitions are available in the libraries.

10.4.6.10. Mapping of Symbols (--symbol_map Option)¶

Symbol mapping allows a symbol reference to be resolved by a symbol with a different name. Symbol mapping allows functions to be overridden with alternate definitions. This feature can be used to patch in alternate implementations, which provide patches (bug fixes) or alternate functionality. The syntax for the --symbol_map option is:

--symbol_map=refname=defname

For example, the following code makes the linker resolve any references to foo by the definition foo_patch:

--symbol_map=foo=foo_patch

The --symbol_map option is now supported even if -flto was used when compiling and linking.

The string passed with the --symbol_map option should contain no spaces and not be surrounded by quotes. This allows the same linker option syntax to work on the command line, in a linker command file, and in an options file.

10.4.6.11. Introduce an Unresolved Symbol (--undef_sym Option)¶

The --undef_sym option introduces the linkname for an unresolved symbol into the linker’s symbol table. This forces the linker to search a library and include the member that defines the symbol. The linker must encounter the --undef_sym option before it links in the member that defines the symbol. The syntax for the --undef_sym option is:

--undef_sym=symbol

For example, suppose a library named rtsv4_A_be_eabi.lib contains a member that defines the symbol symtab; none of the object files being linked reference symtab. However, suppose you plan to relink the output module and you want to include the library member that defines symtab in this link. Using the --undef_sym option as shown below forces the linker to search rtsv4_A_be_eabi.lib for the member that defines symtab and to link in the member.

tiarmclang -Wl,--undef_sym=symtab file1.c.o file2.c.o rtsv4_A_be_eabi.lib

If you do not use --undef_sym, this member is not included, because there is no explicit reference to it in file1.c.o or file2.c.o.