8.4.26 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 take 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.obj in the rts64plus_eabi.lib library:

--retain=rts64plus_eabi.lib<printf.obj>(.text)

If the library is specified with the --library option (--library=rts64plus_eabi.lib) the library search path is used to search for the library. You cannot specify '*<*>(*)'.