ld: Options
1
1 2.1 Command Line Options
1 ========================
1
1 The linker supports a plethora of command-line options, but in actual
1 practice few of them are used in any particular context. For instance,
1 a frequent use of 'ld' is to link standard Unix object files on a
1 standard, supported Unix system. On such a system, to link a file
1 'hello.o':
1
1 ld -o OUTPUT /lib/crt0.o hello.o -lc
1
1 This tells 'ld' to produce a file called OUTPUT as the result of
1 linking the file '/lib/crt0.o' with 'hello.o' and the library 'libc.a',
1 which will come from the standard search directories. (See the
1 discussion of the '-l' option below.)
1
1 Some of the command-line options to 'ld' may be specified at any
1 point in the command line. However, options which refer to files, such
1 as '-l' or '-T', cause the file to be read at the point at which the
1 option appears in the command line, relative to the object files and
1 other file options. Repeating non-file options with a different
1 argument will either have no further effect, or override prior
1 occurrences (those further to the left on the command line) of that
1 option. Options which may be meaningfully specified more than once are
1 noted in the descriptions below.
1
1 Non-option arguments are object files or archives which are to be
1 linked together. They may follow, precede, or be mixed in with
1 command-line options, except that an object file argument may not be
1 placed between an option and its argument.
1
1 Usually the linker is invoked with at least one object file, but you
1 can specify other forms of binary input files using '-l', '-R', and the
1 script command language. If _no_ binary input files at all are
1 specified, the linker does not produce any output, and issues the
1 message 'No input files'.
1
1 If the linker cannot recognize the format of an object file, it will
1 assume that it is a linker script. A script specified in this way
1 augments the main linker script used for the link (either the default
1 linker script or the one specified by using '-T'). This feature permits
1 the linker to link against a file which appears to be an object or an
1 archive, but actually merely defines some symbol values, or uses 'INPUT'
1 or 'GROUP' to load other objects. Specifying a script in this way
1 merely augments the main linker script, with the extra commands placed
1 after the main script; use the '-T' option to replace the default linker
11 script entirely, but note the effect of the 'INSERT' command. ⇒
Scripts.
1
1 For options whose names are a single letter, option arguments must
1 either follow the option letter without intervening whitespace, or be
1 given as separate arguments immediately following the option that
1 requires them.
1
1 For options whose names are multiple letters, either one dash or two
1 can precede the option name; for example, '-trace-symbol' and
1 '--trace-symbol' are equivalent. Note--there is one exception to this
1 rule. Multiple letter options that start with a lower case 'o' can only
1 be preceded by two dashes. This is to reduce confusion with the '-o'
1 option. So for example '-omagic' sets the output file name to 'magic'
1 whereas '--omagic' sets the NMAGIC flag on the output.
1
1 Arguments to multiple-letter options must either be separated from
1 the option name by an equals sign, or be given as separate arguments
1 immediately following the option that requires them. For example,
1 '--trace-symbol foo' and '--trace-symbol=foo' are equivalent. Unique
1 abbreviations of the names of multiple-letter options are accepted.
1
1 Note--if the linker is being invoked indirectly, via a compiler
1 driver (e.g. 'gcc') then all the linker command line options should be
1 prefixed by '-Wl,' (or whatever is appropriate for the particular
1 compiler driver) like this:
1
1 gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
1
1 This is important, because otherwise the compiler driver program may
1 silently drop the linker options, resulting in a bad link. Confusion
1 may also arise when passing options that require values through a
1 driver, as the use of a space between option and argument acts as a
1 separator, and causes the driver to pass only the option to the linker
1 and the argument to the compiler. In this case, it is simplest to use
1 the joined forms of both single- and multiple-letter options, such as:
1
1 gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
1
1 Here is a table of the generic command line switches accepted by the
1 GNU linker:
1
1 '@FILE'
1 Read command-line options from FILE. The options read are inserted
1 in place of the original @FILE option. If FILE does not exist, or
1 cannot be read, then the option will be treated literally, and not
1 removed.
1
1 Options in FILE are separated by whitespace. A whitespace
1 character may be included in an option by surrounding the entire
1 option in either single or double quotes. Any character (including
1 a backslash) may be included by prefixing the character to be
1 included with a backslash. The FILE may itself contain additional
1 @FILE options; any such options will be processed recursively.
1
1 '-a KEYWORD'
1 This option is supported for HP/UX compatibility. The KEYWORD
1 argument must be one of the strings 'archive', 'shared', or
1 'default'. '-aarchive' is functionally equivalent to '-Bstatic',
1 and the other two keywords are functionally equivalent to
1 '-Bdynamic'. This option may be used any number of times.
1
1 '--audit AUDITLIB'
1 Adds AUDITLIB to the 'DT_AUDIT' entry of the dynamic section.
1 AUDITLIB is not checked for existence, nor will it use the
1 DT_SONAME specified in the library. If specified multiple times
1 'DT_AUDIT' will contain a colon separated list of audit interfaces
1 to use. If the linker finds an object with an audit entry while
1 searching for shared libraries, it will add a corresponding
1 'DT_DEPAUDIT' entry in the output file. This option is only
1 meaningful on ELF platforms supporting the rtld-audit interface.
1
1 '-A ARCHITECTURE'
1 '--architecture=ARCHITECTURE'
1 In the current release of 'ld', this option is useful only for the
1 Intel 960 family of architectures. In that 'ld' configuration, the
1 ARCHITECTURE argument identifies the particular architecture in the
1 960 family, enabling some safeguards and modifying the
11 archive-library search path. ⇒'ld' and the Intel 960 family
i960, for details.
1
1 Future releases of 'ld' may support similar functionality for other
1 architecture families.
1
1 '-b INPUT-FORMAT'
1 '--format=INPUT-FORMAT'
1 'ld' may be configured to support more than one kind of object
1 file. If your 'ld' is configured this way, you can use the '-b'
1 option to specify the binary format for input object files that
1 follow this option on the command line. Even when 'ld' is
1 configured to support alternative object formats, you don't usually
1 need to specify this, as 'ld' should be configured to expect as a
1 default input format the most usual format on each machine.
1 INPUT-FORMAT is a text string, the name of a particular format
1 supported by the BFD libraries. (You can list the available binary
1 formats with 'objdump -i'.) ⇒BFD.
1
1 You may want to use this option if you are linking files with an
1 unusual binary format. You can also use '-b' to switch formats
1 explicitly (when linking object files of different formats), by
1 including '-b INPUT-FORMAT' before each group of object files in a
1 particular format.
1
1 The default format is taken from the environment variable
1 'GNUTARGET'. ⇒Environment. You can also define the input
11 format from a script, using the command 'TARGET'; see ⇒Format
Commands.
1
1 '-c MRI-COMMANDFILE'
1 '--mri-script=MRI-COMMANDFILE'
1 For compatibility with linkers produced by MRI, 'ld' accepts script
1 files written in an alternate, restricted command language,
1 described in ⇒MRI Compatible Script Files MRI. Introduce MRI
1 script files with the option '-c'; use the '-T' option to run
1 linker scripts written in the general-purpose 'ld' scripting
1 language. If MRI-CMDFILE does not exist, 'ld' looks for it in the
1 directories specified by any '-L' options.
1
1 '-d'
1 '-dc'
1 '-dp'
1 These three options are equivalent; multiple forms are supported
1 for compatibility with other linkers. They assign space to common
1 symbols even if a relocatable output file is specified (with '-r').
1 The script command 'FORCE_COMMON_ALLOCATION' has the same effect.
1 ⇒Miscellaneous Commands.
1
1 '--depaudit AUDITLIB'
1 '-P AUDITLIB'
1 Adds AUDITLIB to the 'DT_DEPAUDIT' entry of the dynamic section.
1 AUDITLIB is not checked for existence, nor will it use the
1 DT_SONAME specified in the library. If specified multiple times
1 'DT_DEPAUDIT' will contain a colon separated list of audit
1 interfaces to use. This option is only meaningful on ELF platforms
1 supporting the rtld-audit interface. The -P option is provided for
1 Solaris compatibility.
1
1 '-e ENTRY'
1 '--entry=ENTRY'
1 Use ENTRY as the explicit symbol for beginning execution of your
1 program, rather than the default entry point. If there is no
1 symbol named ENTRY, the linker will try to parse ENTRY as a number,
1 and use that as the entry address (the number will be interpreted
1 in base 10; you may use a leading '0x' for base 16, or a leading
1 '0' for base 8). ⇒Entry Point, for a discussion of defaults
1 and other ways of specifying the entry point.
1
1 '--exclude-libs LIB,LIB,...'
1 Specifies a list of archive libraries from which symbols should not
1 be automatically exported. The library names may be delimited by
1 commas or colons. Specifying '--exclude-libs ALL' excludes symbols
1 in all archive libraries from automatic export. This option is
1 available only for the i386 PE targeted port of the linker and for
1 ELF targeted ports. For i386 PE, symbols explicitly listed in a
1 .def file are still exported, regardless of this option. For ELF
1 targeted ports, symbols affected by this option will be treated as
1 hidden.
1
1 '--exclude-modules-for-implib MODULE,MODULE,...'
1 Specifies a list of object files or archive members, from which
1 symbols should not be automatically exported, but which should be
1 copied wholesale into the import library being generated during the
1 link. The module names may be delimited by commas or colons, and
1 must match exactly the filenames used by 'ld' to open the files;
1 for archive members, this is simply the member name, but for object
1 files the name listed must include and match precisely any path
1 used to specify the input file on the linker's command-line. This
1 option is available only for the i386 PE targeted port of the
1 linker. Symbols explicitly listed in a .def file are still
1 exported, regardless of this option.
1
1 '-E'
1 '--export-dynamic'
1 '--no-export-dynamic'
1 When creating a dynamically linked executable, using the '-E'
1 option or the '--export-dynamic' option causes the linker to add
1 all symbols to the dynamic symbol table. The dynamic symbol table
1 is the set of symbols which are visible from dynamic objects at run
1 time.
1
1 If you do not use either of these options (or use the
1 '--no-export-dynamic' option to restore the default behavior), the
1 dynamic symbol table will normally contain only those symbols which
1 are referenced by some dynamic object mentioned in the link.
1
1 If you use 'dlopen' to load a dynamic object which needs to refer
1 back to the symbols defined by the program, rather than some other
1 dynamic object, then you will probably need to use this option when
1 linking the program itself.
1
1 You can also use the dynamic list to control what symbols should be
1 added to the dynamic symbol table if the output format supports it.
1 See the description of '--dynamic-list'.
1
1 Note that this option is specific to ELF targeted ports. PE
1 targets support a similar function to export all symbols from a DLL
1 or EXE; see the description of '--export-all-symbols' below.
1
1 '-EB'
1 Link big-endian objects. This affects the default output format.
1
1 '-EL'
1 Link little-endian objects. This affects the default output
1 format.
1
1 '-f NAME'
1 '--auxiliary=NAME'
1 When creating an ELF shared object, set the internal DT_AUXILIARY
1 field to the specified name. This tells the dynamic linker that
1 the symbol table of the shared object should be used as an
1 auxiliary filter on the symbol table of the shared object NAME.
1
1 If you later link a program against this filter object, then, when
1 you run the program, the dynamic linker will see the DT_AUXILIARY
1 field. If the dynamic linker resolves any symbols from the filter
1 object, it will first check whether there is a definition in the
1 shared object NAME. If there is one, it will be used instead of
1 the definition in the filter object. The shared object NAME need
1 not exist. Thus the shared object NAME may be used to provide an
1 alternative implementation of certain functions, perhaps for
1 debugging or for machine specific performance.
1
1 This option may be specified more than once. The DT_AUXILIARY
1 entries will be created in the order in which they appear on the
1 command line.
1
1 '-F NAME'
1 '--filter=NAME'
1 When creating an ELF shared object, set the internal DT_FILTER
1 field to the specified name. This tells the dynamic linker that
1 the symbol table of the shared object which is being created should
1 be used as a filter on the symbol table of the shared object NAME.
1
1 If you later link a program against this filter object, then, when
1 you run the program, the dynamic linker will see the DT_FILTER
1 field. The dynamic linker will resolve symbols according to the
1 symbol table of the filter object as usual, but it will actually
1 link to the definitions found in the shared object NAME. Thus the
1 filter object can be used to select a subset of the symbols
1 provided by the object NAME.
1
1 Some older linkers used the '-F' option throughout a compilation
1 toolchain for specifying object-file format for both input and
1 output object files. The GNU linker uses other mechanisms for this
1 purpose: the '-b', '--format', '--oformat' options, the 'TARGET'
1 command in linker scripts, and the 'GNUTARGET' environment
1 variable. The GNU linker will ignore the '-F' option when not
1 creating an ELF shared object.
1
1 '-fini=NAME'
1 When creating an ELF executable or shared object, call NAME when
1 the executable or shared object is unloaded, by setting DT_FINI to
1 the address of the function. By default, the linker uses '_fini'
1 as the function to call.
1
1 '-g'
1 Ignored. Provided for compatibility with other tools.
1
1 '-G VALUE'
1 '--gpsize=VALUE'
1 Set the maximum size of objects to be optimized using the GP
1 register to SIZE. This is only meaningful for object file formats
1 such as MIPS ELF that support putting large and small objects into
1 different sections. This is ignored for other object file formats.
1
1 '-h NAME'
1 '-soname=NAME'
1 When creating an ELF shared object, set the internal DT_SONAME
1 field to the specified name. When an executable is linked with a
1 shared object which has a DT_SONAME field, then when the executable
1 is run the dynamic linker will attempt to load the shared object
1 specified by the DT_SONAME field rather than the using the file
1 name given to the linker.
1
1 '-i'
1 Perform an incremental link (same as option '-r').
1
1 '-init=NAME'
1 When creating an ELF executable or shared object, call NAME when
1 the executable or shared object is loaded, by setting DT_INIT to
1 the address of the function. By default, the linker uses '_init'
1 as the function to call.
1
1 '-l NAMESPEC'
1 '--library=NAMESPEC'
1 Add the archive or object file specified by NAMESPEC to the list of
1 files to link. This option may be used any number of times. If
1 NAMESPEC is of the form ':FILENAME', 'ld' will search the library
1 path for a file called FILENAME, otherwise it will search the
1 library path for a file called 'libNAMESPEC.a'.
1
1 On systems which support shared libraries, 'ld' may also search for
1 files other than 'libNAMESPEC.a'. Specifically, on ELF and SunOS
1 systems, 'ld' will search a directory for a library called
1 'libNAMESPEC.so' before searching for one called 'libNAMESPEC.a'.
1 (By convention, a '.so' extension indicates a shared library.)
1 Note that this behavior does not apply to ':FILENAME', which always
1 specifies a file called FILENAME.
1
1 The linker will search an archive only once, at the location where
1 it is specified on the command line. If the archive defines a
1 symbol which was undefined in some object which appeared before the
1 archive on the command line, the linker will include the
1 appropriate file(s) from the archive. However, an undefined symbol
1 in an object appearing later on the command line will not cause the
1 linker to search the archive again.
1
1 See the '-(' option for a way to force the linker to search
1 archives multiple times.
1
1 You may list the same archive multiple times on the command line.
1
1 This type of archive searching is standard for Unix linkers.
1 However, if you are using 'ld' on AIX, note that it is different
1 from the behaviour of the AIX linker.
1
1 '-L SEARCHDIR'
1 '--library-path=SEARCHDIR'
1 Add path SEARCHDIR to the list of paths that 'ld' will search for
1 archive libraries and 'ld' control scripts. You may use this
1 option any number of times. The directories are searched in the
1 order in which they are specified on the command line. Directories
1 specified on the command line are searched before the default
1 directories. All '-L' options apply to all '-l' options,
1 regardless of the order in which the options appear. '-L' options
1 do not affect how 'ld' searches for a linker script unless '-T'
1 option is specified.
1
1 If SEARCHDIR begins with '=' or '$SYSROOT', then this prefix will
1 be replaced by the "sysroot prefix", controlled by the '--sysroot'
1 option, or specified when the linker is configured.
1
1 The default set of paths searched (without being specified with
1 '-L') depends on which emulation mode 'ld' is using, and in some
1 cases also on how it was configured. ⇒Environment.
1
1 The paths can also be specified in a link script with the
1 'SEARCH_DIR' command. Directories specified this way are searched
1 at the point in which the linker script appears in the command
1 line.
1
1 '-m EMULATION'
1 Emulate the EMULATION linker. You can list the available
1 emulations with the '--verbose' or '-V' options.
1
1 If the '-m' option is not used, the emulation is taken from the
1 'LDEMULATION' environment variable, if that is defined.
1
1 Otherwise, the default emulation depends upon how the linker was
1 configured.
1
1 '-M'
1 '--print-map'
1 Print a link map to the standard output. A link map provides
1 information about the link, including the following:
1
1 * Where object files are mapped into memory.
1 * How common symbols are allocated.
1 * All archive members included in the link, with a mention of
1 the symbol which caused the archive member to be brought in.
1 * The values assigned to symbols.
1
1 Note - symbols whose values are computed by an expression
1 which involves a reference to a previous value of the same
1 symbol may not have correct result displayed in the link map.
1 This is because the linker discards intermediate results and
1 only retains the final value of an expression. Under such
1 circumstances the linker will display the final value enclosed
1 by square brackets. Thus for example a linker script
1 containing:
1
1 foo = 1
1 foo = foo * 4
1 foo = foo + 8
1
1 will produce the following output in the link map if the '-M'
1 option is used:
1
1 0x00000001 foo = 0x1
1 [0x0000000c] foo = (foo * 0x4)
1 [0x0000000c] foo = (foo + 0x8)
1
1 See ⇒Expressions for more information about expressions
1 in linker scripts.
1
1 '-n'
1 '--nmagic'
1 Turn off page alignment of sections, and disable linking against
1 shared libraries. If the output format supports Unix style magic
1 numbers, mark the output as 'NMAGIC'.
1
1 '-N'
1 '--omagic'
1 Set the text and data sections to be readable and writable. Also,
1 do not page-align the data segment, and disable linking against
1 shared libraries. If the output format supports Unix style magic
1 numbers, mark the output as 'OMAGIC'. Note: Although a writable
1 text section is allowed for PE-COFF targets, it does not conform to
1 the format specification published by Microsoft.
1
1 '--no-omagic'
1 This option negates most of the effects of the '-N' option. It
1 sets the text section to be read-only, and forces the data segment
1 to be page-aligned. Note - this option does not enable linking
1 against shared libraries. Use '-Bdynamic' for this.
1
1 '-o OUTPUT'
1 '--output=OUTPUT'
1 Use OUTPUT as the name for the program produced by 'ld'; if this
1 option is not specified, the name 'a.out' is used by default. The
1 script command 'OUTPUT' can also specify the output file name.
1
1 '-O LEVEL'
1 If LEVEL is a numeric values greater than zero 'ld' optimizes the
1 output. This might take significantly longer and therefore
1 probably should only be enabled for the final binary. At the
1 moment this option only affects ELF shared library generation.
1 Future releases of the linker may make more use of this option.
1 Also currently there is no difference in the linker's behaviour for
1 different non-zero values of this option. Again this may change
1 with future releases.
1
1 '-plugin NAME'
1 Involve a plugin in the linking process. The NAME parameter is the
1 absolute filename of the plugin. Usually this parameter is
1 automatically added by the complier, when using link time
1 optimization, but users can also add their own plugins if they so
1 wish.
1
1 Note that the location of the compiler originated plugins is
1 different from the place where the 'ar', 'nm' and 'ranlib' programs
1 search for their plugins. In order for those commands to make use
1 of a compiler based plugin it must first be copied into the
1 '${libdir}/bfd-plugins' directory. All gcc based linker plugins
1 are backward compatible, so it is sufficient to just copy in the
1 newest one.
1
1 '--push-state'
1 The '--push-state' allows to preserve the current state of the
1 flags which govern the input file handling so that they can all be
1 restored with one corresponding '--pop-state' option.
1
1 The option which are covered are: '-Bdynamic', '-Bstatic', '-dn',
1 '-dy', '-call_shared', '-non_shared', '-static', '-N', '-n',
1 '--whole-archive', '--no-whole-archive', '-r', '-Ur',
1 '--copy-dt-needed-entries', '--no-copy-dt-needed-entries',
1 '--as-needed', '--no-as-needed', and '-a'.
1
1 One target for this option are specifications for 'pkg-config'.
1 When used with the '--libs' option all possibly needed libraries
1 are listed and then possibly linked with all the time. It is
1 better to return something as follows:
1
1 -Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
1
1 '--pop-state'
1 Undoes the effect of -push-state, restores the previous values of
1 the flags governing input file handling.
1
1 '-q'
1 '--emit-relocs'
1 Leave relocation sections and contents in fully linked executables.
1 Post link analysis and optimization tools may need this information
1 in order to perform correct modifications of executables. This
1 results in larger executables.
1
1 This option is currently only supported on ELF platforms.
1
1 '--force-dynamic'
1 Force the output file to have dynamic sections. This option is
1 specific to VxWorks targets.
1
1 '-r'
1 '--relocatable'
1 Generate relocatable output--i.e., generate an output file that can
1 in turn serve as input to 'ld'. This is often called "partial
1 linking". As a side effect, in environments that support standard
1 Unix magic numbers, this option also sets the output file's magic
1 number to 'OMAGIC'. If this option is not specified, an absolute
1 file is produced. When linking C++ programs, this option _will
1 not_ resolve references to constructors; to do that, use '-Ur'.
1
1 When an input file does not have the same format as the output
1 file, partial linking is only supported if that input file does not
1 contain any relocations. Different output formats can have further
1 restrictions; for example some 'a.out'-based formats do not support
1 partial linking with input files in other formats at all.
1
1 This option does the same thing as '-i'.
1
1 '-R FILENAME'
1 '--just-symbols=FILENAME'
1 Read symbol names and their addresses from FILENAME, but do not
1 relocate it or include it in the output. This allows your output
1 file to refer symbolically to absolute locations of memory defined
1 in other programs. You may use this option more than once.
1
1 For compatibility with other ELF linkers, if the '-R' option is
1 followed by a directory name, rather than a file name, it is
1 treated as the '-rpath' option.
1
1 '-s'
1 '--strip-all'
1 Omit all symbol information from the output file.
1
1 '-S'
1 '--strip-debug'
1 Omit debugger symbol information (but not all symbols) from the
1 output file.
1
1 '--strip-discarded'
1 '--no-strip-discarded'
1 Omit (or do not omit) global symbols defined in discarded sections.
1 Enabled by default.
1
1 '-t'
1 '--trace'
1 Print the names of the input files as 'ld' processes them.
1
1 '-T SCRIPTFILE'
1 '--script=SCRIPTFILE'
1 Use SCRIPTFILE as the linker script. This script replaces 'ld''s
1 default linker script (rather than adding to it), so COMMANDFILE
1 must specify everything necessary to describe the output file.
1 ⇒Scripts. If SCRIPTFILE does not exist in the current
1 directory, 'ld' looks for it in the directories specified by any
1 preceding '-L' options. Multiple '-T' options accumulate.
1
1 '-dT SCRIPTFILE'
1 '--default-script=SCRIPTFILE'
1 Use SCRIPTFILE as the default linker script. ⇒Scripts.
1
1 This option is similar to the '--script' option except that
1 processing of the script is delayed until after the rest of the
1 command line has been processed. This allows options placed after
1 the '--default-script' option on the command line to affect the
1 behaviour of the linker script, which can be important when the
1 linker command line cannot be directly controlled by the user. (eg
1 because the command line is being constructed by another tool, such
1 as 'gcc').
1
1 '-u SYMBOL'
1 '--undefined=SYMBOL'
1 Force SYMBOL to be entered in the output file as an undefined
1 symbol. Doing this may, for example, trigger linking of additional
1 modules from standard libraries. '-u' may be repeated with
1 different option arguments to enter additional undefined symbols.
1 This option is equivalent to the 'EXTERN' linker script command.
1
1 If this option is being used to force additional modules to be
1 pulled into the link, and if it is an error for the symbol to
1 remain undefined, then the option '--require-defined' should be
1 used instead.
1
1 '--require-defined=SYMBOL'
1 Require that SYMBOL is defined in the output file. This option is
1 the same as option '--undefined' except that if SYMBOL is not
1 defined in the output file then the linker will issue an error and
1 exit. The same effect can be achieved in a linker script by using
1 'EXTERN', 'ASSERT' and 'DEFINED' together. This option can be used
1 multiple times to require additional symbols.
1
1 '-Ur'
1 For anything other than C++ programs, this option is equivalent to
1 '-r': it generates relocatable output--i.e., an output file that
1 can in turn serve as input to 'ld'. When linking C++ programs,
1 '-Ur' _does_ resolve references to constructors, unlike '-r'. It
1 does not work to use '-Ur' on files that were themselves linked
1 with '-Ur'; once the constructor table has been built, it cannot be
1 added to. Use '-Ur' only for the last partial link, and '-r' for
1 the others.
1
1 '--orphan-handling=MODE'
1 Control how orphan sections are handled. An orphan section is one
11 not specifically mentioned in a linker script. ⇒Orphan
Sections.
1
1 MODE can have any of the following values:
1
1 'place'
1 Orphan sections are placed into a suitable output section
1 following the strategy described in ⇒Orphan Sections.
1 The option '--unique' also affects how sections are placed.
1
1 'discard'
1 All orphan sections are discarded, by placing them in the
1 '/DISCARD/' section (⇒Output Section Discarding).
1
1 'warn'
1 The linker will place the orphan section as for 'place' and
1 also issue a warning.
1
1 'error'
1 The linker will exit with an error if any orphan section is
1 found.
1
1 The default if '--orphan-handling' is not given is 'place'.
1
1 '--unique[=SECTION]'
1 Creates a separate output section for every input section matching
1 SECTION, or if the optional wildcard SECTION argument is missing,
1 for every orphan input section. An orphan section is one not
1 specifically mentioned in a linker script. You may use this option
1 multiple times on the command line; It prevents the normal merging
1 of input sections with the same name, overriding output section
1 assignments in a linker script.
1
1 '-v'
1 '--version'
1 '-V'
1 Display the version number for 'ld'. The '-V' option also lists
1 the supported emulations.
1
1 '-x'
1 '--discard-all'
1 Delete all local symbols.
1
1 '-X'
1 '--discard-locals'
1 Delete all temporary local symbols. (These symbols start with
1 system-specific local label prefixes, typically '.L' for ELF
1 systems or 'L' for traditional a.out systems.)
1
1 '-y SYMBOL'
1 '--trace-symbol=SYMBOL'
1 Print the name of each linked file in which SYMBOL appears. This
1 option may be given any number of times. On many systems it is
1 necessary to prepend an underscore.
1
1 This option is useful when you have an undefined symbol in your
1 link but don't know where the reference is coming from.
1
1 '-Y PATH'
1 Add PATH to the default library search path. This option exists
1 for Solaris compatibility.
1
1 '-z KEYWORD'
1 The recognized keywords are:
1
1 'bndplt'
1 Always generate BND prefix in PLT entries. Supported for
1 Linux/x86_64.
1
1 'call-nop=prefix-addr'
1 'call-nop=suffix-nop'
1 'call-nop=prefix-BYTE'
1 'call-nop=suffix-BYTE'
1 Specify the 1-byte 'NOP' padding when transforming indirect
1 call to a locally defined function, foo, via its GOT slot.
1 'call-nop=prefix-addr' generates '0x67 call foo'.
1 'call-nop=suffix-nop' generates 'call foo 0x90'.
1 'call-nop=prefix-BYTE' generates 'BYTE call foo'.
1 'call-nop=suffix-BYTE' generates 'call foo BYTE'. Supported
1 for i386 and x86_64.
1
1 'combreloc'
1 'nocombreloc'
1 Combine multiple dynamic relocation sections and sort to
1 improve dynamic symbol lookup caching. Do not do this if
1 'nocombreloc'.
1
1 'common'
1 'nocommon'
1 Generate common symbols with STT_COMMON type during a
1 relocatable link. Use STT_OBJECT type if 'nocommon'.
1
1 'common-page-size=VALUE'
1 Set the page size most commonly used to VALUE. Memory image
1 layout will be optimized to minimize memory pages if the
1 system is using pages of this size.
1
1 'defs'
1 Report unresolved symbol references from regular object files.
1 This is done even if the linker is creating a non-symbolic
1 shared library. This option is the inverse of '-z undefs'.
1
1 'dynamic-undefined-weak'
1 'nodynamic-undefined-weak'
1 Make undefined weak symbols dynamic when building a dynamic
1 object, if they are referenced from a regular object file and
1 not forced local by symbol visibility or versioning. Do not
1 make them dynamic if 'nodynamic-undefined-weak'. If neither
1 option is given, a target may default to either option being
1 in force, or make some other selection of undefined weak
1 symbols dynamic. Not all targets support these options.
1
1 'execstack'
1 Marks the object as requiring executable stack.
1
1 'global'
1 This option is only meaningful when building a shared object.
1 It makes the symbols defined by this shared object available
1 for symbol resolution of subsequently loaded libraries.
1
1 'globalaudit'
1 This option is only meaningful when building a dynamic
1 executable. This option marks the executable as requiring
1 global auditing by setting the 'DF_1_GLOBAUDIT' bit in the
1 'DT_FLAGS_1' dynamic tag. Global auditing requires that any
1 auditing library defined via the '--depaudit' or '-P' command
1 line options be run for all dynamic objects loaded by the
1 application.
1
1 'ibtplt'
1 Generate Intel Indirect Branch Tracking (IBT) enabled PLT
1 entries. Supported for Linux/i386 and Linux/x86_64.
1
1 'ibt'
1 Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property
1 section to indicate compatibility with IBT. This also implies
1 'ibtplt'. Supported for Linux/i386 and Linux/x86_64.
1
1 'initfirst'
1 This option is only meaningful when building a shared object.
1 It marks the object so that its runtime initialization will
1 occur before the runtime initialization of any other objects
1 brought into the process at the same time. Similarly the
1 runtime finalization of the object will occur after the
1 runtime finalization of any other objects.
1
1 'interpose'
1 Specify that the dynamic loader should modify its symbol
1 search order so that symbols in this shared library interpose
1 all other shared libraries not so marked.
1
1 'lazy'
1 When generating an executable or shared library, mark it to
1 tell the dynamic linker to defer function call resolution to
1 the point when the function is called (lazy binding), rather
1 than at load time. Lazy binding is the default.
1
1 'loadfltr'
1 Specify that the object's filters be processed immediately at
1 runtime.
1
1 'max-page-size=VALUE'
1 Set the maximum memory page size supported to VALUE.
1
1 'muldefs'
1 Allow multiple definitions.
1
1 'nocopyreloc'
1 Disable linker generated .dynbss variables used in place of
1 variables defined in shared libraries. May result in dynamic
1 text relocations.
1
1 'nodefaultlib'
1 Specify that the dynamic loader search for dependencies of
1 this object should ignore any default library search paths.
1
1 'nodelete'
1 Specify that the object shouldn't be unloaded at runtime.
1
1 'nodlopen'
1 Specify that the object is not available to 'dlopen'.
1
1 'nodump'
1 Specify that the object can not be dumped by 'dldump'.
1
1 'noexecstack'
1 Marks the object as not requiring executable stack.
1
1 'noextern-protected-data'
1 Don't treat protected data symbols as external when building a
1 shared library. This option overrides the linker backend
1 default. It can be used to work around incorrect relocations
1 against protected data symbols generated by compiler. Updates
1 on protected data symbols by another module aren't visible to
1 the resulting shared library. Supported for i386 and x86-64.
1
1 'noreloc-overflow'
1 Disable relocation overflow check. This can be used to
1 disable relocation overflow check if there will be no dynamic
1 relocation overflow at run-time. Supported for x86_64.
1
1 'now'
1 When generating an executable or shared library, mark it to
1 tell the dynamic linker to resolve all symbols when the
1 program is started, or when the shared library is loaded by
1 dlopen, instead of deferring function call resolution to the
1 point when the function is first called.
1
1 'origin'
1 Specify that the object requires '$ORIGIN' handling in paths.
1
1 'relro'
1 'norelro'
1 Create an ELF 'PT_GNU_RELRO' segment header in the object.
1 This specifies a memory segment that should be made read-only
1 after relocation, if supported. Specifying 'common-page-size'
1 smaller than the system page size will render this protection
1 ineffective. Don't create an ELF 'PT_GNU_RELRO' segment if
1 'norelro'.
1
1 'separate-code'
1 'noseparate-code'
1 Create separate code 'PT_LOAD' segment header in the object.
1 This specifies a memory segment that should contain only
1 instructions and must be in wholly disjoint pages from any
1 other data. Don't create separate code 'PT_LOAD' segment if
1 'noseparate-code' is used.
1
1 'shstk'
1 Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in
1 .note.gnu.property section to indicate compatibility with
1 Intel Shadow Stack. Supported for Linux/i386 and
1 Linux/x86_64.
1
1 'stack-size=VALUE'
1 Specify a stack size for an ELF 'PT_GNU_STACK' segment.
1 Specifying zero will override any default non-zero sized
1 'PT_GNU_STACK' segment creation.
1
1 'text'
1 'notext'
1 'textoff'
1 Report an error if DT_TEXTREL is set, i.e., if the binary has
1 dynamic relocations in read-only sections. Don't report an
1 error if 'notext' or 'textoff'.
1
1 'undefs'
1 Do not report unresolved symbol references from regular object
1 files, either when creating an executable, or when creating a
1 shared library. This option is the inverse of '-z defs'.
1
1 Other keywords are ignored for Solaris compatibility.
1
1 '-( ARCHIVES -)'
1 '--start-group ARCHIVES --end-group'
1 The ARCHIVES should be a list of archive files. They may be either
1 explicit file names, or '-l' options.
1
1 The specified archives are searched repeatedly until no new
1 undefined references are created. Normally, an archive is searched
1 only once in the order that it is specified on the command line.
1 If a symbol in that archive is needed to resolve an undefined
1 symbol referred to by an object in an archive that appears later on
1 the command line, the linker would not be able to resolve that
1 reference. By grouping the archives, they all be searched
1 repeatedly until all possible references are resolved.
1
1 Using this option has a significant performance cost. It is best
1 to use it only when there are unavoidable circular references
1 between two or more archives.
1
1 '--accept-unknown-input-arch'
1 '--no-accept-unknown-input-arch'
1 Tells the linker to accept input files whose architecture cannot be
1 recognised. The assumption is that the user knows what they are
1 doing and deliberately wants to link in these unknown input files.
1 This was the default behaviour of the linker, before release 2.14.
1 The default behaviour from release 2.14 onwards is to reject such
1 input files, and so the '--accept-unknown-input-arch' option has
1 been added to restore the old behaviour.
1
1 '--as-needed'
1 '--no-as-needed'
1 This option affects ELF DT_NEEDED tags for dynamic libraries
1 mentioned on the command line after the '--as-needed' option.
1 Normally the linker will add a DT_NEEDED tag for each dynamic
1 library mentioned on the command line, regardless of whether the
1 library is actually needed or not. '--as-needed' causes a
1 DT_NEEDED tag to only be emitted for a library that _at that point
1 in the link_ satisfies a non-weak undefined symbol reference from a
1 regular object file or, if the library is not found in the
1 DT_NEEDED lists of other needed libraries, a non-weak undefined
1 symbol reference from another needed dynamic library. Object files
1 or libraries appearing on the command line _after_ the library in
1 question do not affect whether the library is seen as needed. This
1 is similar to the rules for extraction of object files from
1 archives. '--no-as-needed' restores the default behaviour.
1
1 '--add-needed'
1 '--no-add-needed'
1 These two options have been deprecated because of the similarity of
1 their names to the '--as-needed' and '--no-as-needed' options.
1 They have been replaced by '--copy-dt-needed-entries' and
1 '--no-copy-dt-needed-entries'.
1
1 '-assert KEYWORD'
1 This option is ignored for SunOS compatibility.
1
1 '-Bdynamic'
1 '-dy'
1 '-call_shared'
1 Link against dynamic libraries. This is only meaningful on
1 platforms for which shared libraries are supported. This option is
1 normally the default on such platforms. The different variants of
1 this option are for compatibility with various systems. You may
1 use this option multiple times on the command line: it affects
1 library searching for '-l' options which follow it.
1
1 '-Bgroup'
1 Set the 'DF_1_GROUP' flag in the 'DT_FLAGS_1' entry in the dynamic
1 section. This causes the runtime linker to handle lookups in this
1 object and its dependencies to be performed only inside the group.
1 '--unresolved-symbols=report-all' is implied. This option is only
1 meaningful on ELF platforms which support shared libraries.
1
1 '-Bstatic'
1 '-dn'
1 '-non_shared'
1 '-static'
1 Do not link against shared libraries. This is only meaningful on
1 platforms for which shared libraries are supported. The different
1 variants of this option are for compatibility with various systems.
1 You may use this option multiple times on the command line: it
1 affects library searching for '-l' options which follow it. This
1 option also implies '--unresolved-symbols=report-all'. This option
1 can be used with '-shared'. Doing so means that a shared library
1 is being created but that all of the library's external references
1 must be resolved by pulling in entries from static libraries.
1
1 '-Bsymbolic'
1 When creating a shared library, bind references to global symbols
1 to the definition within the shared library, if any. Normally, it
1 is possible for a program linked against a shared library to
1 override the definition within the shared library. This option can
1 also be used with the '--export-dynamic' option, when creating a
1 position independent executable, to bind references to global
1 symbols to the definition within the executable. This option is
1 only meaningful on ELF platforms which support shared libraries and
1 position independent executables.
1
1 '-Bsymbolic-functions'
1 When creating a shared library, bind references to global function
1 symbols to the definition within the shared library, if any. This
1 option can also be used with the '--export-dynamic' option, when
1 creating a position independent executable, to bind references to
1 global function symbols to the definition within the executable.
1 This option is only meaningful on ELF platforms which support
1 shared libraries and position independent executables.
1
1 '--dynamic-list=DYNAMIC-LIST-FILE'
1 Specify the name of a dynamic list file to the linker. This is
1 typically used when creating shared libraries to specify a list of
1 global symbols whose references shouldn't be bound to the
1 definition within the shared library, or creating dynamically
1 linked executables to specify a list of symbols which should be
1 added to the symbol table in the executable. This option is only
1 meaningful on ELF platforms which support shared libraries.
1
1 The format of the dynamic list is the same as the version node
1 without scope and node name. See ⇒VERSION for more
1 information.
1
1 '--dynamic-list-data'
1 Include all global data symbols to the dynamic list.
1
1 '--dynamic-list-cpp-new'
1 Provide the builtin dynamic list for C++ operator new and delete.
1 It is mainly useful for building shared libstdc++.
1
1 '--dynamic-list-cpp-typeinfo'
1 Provide the builtin dynamic list for C++ runtime type
1 identification.
1
1 '--check-sections'
1 '--no-check-sections'
1 Asks the linker _not_ to check section addresses after they have
1 been assigned to see if there are any overlaps. Normally the
1 linker will perform this check, and if it finds any overlaps it
1 will produce suitable error messages. The linker does know about,
1 and does make allowances for sections in overlays. The default
1 behaviour can be restored by using the command line switch
1 '--check-sections'. Section overlap is not usually checked for
1 relocatable links. You can force checking in that case by using
1 the '--check-sections' option.
1
1 '--copy-dt-needed-entries'
1 '--no-copy-dt-needed-entries'
1 This option affects the treatment of dynamic libraries referred to
1 by DT_NEEDED tags _inside_ ELF dynamic libraries mentioned on the
1 command line. Normally the linker won't add a DT_NEEDED tag to the
1 output binary for each library mentioned in a DT_NEEDED tag in an
1 input dynamic library. With '--copy-dt-needed-entries' specified
1 on the command line however any dynamic libraries that follow it
1 will have their DT_NEEDED entries added. The default behaviour can
1 be restored with '--no-copy-dt-needed-entries'.
1
1 This option also has an effect on the resolution of symbols in
1 dynamic libraries. With '--copy-dt-needed-entries' dynamic
1 libraries mentioned on the command line will be recursively
1 searched, following their DT_NEEDED tags to other libraries, in
1 order to resolve symbols required by the output binary. With the
1 default setting however the searching of dynamic libraries that
1 follow it will stop with the dynamic library itself. No DT_NEEDED
1 links will be traversed to resolve symbols.
1
1 '--cref'
1 Output a cross reference table. If a linker map file is being
1 generated, the cross reference table is printed to the map file.
1 Otherwise, it is printed on the standard output.
1
1 The format of the table is intentionally simple, so that it may be
1 easily processed by a script if necessary. The symbols are printed
1 out, sorted by name. For each symbol, a list of file names is
1 given. If the symbol is defined, the first file listed is the
1 location of the definition. If the symbol is defined as a common
1 value then any files where this happens appear next. Finally any
1 files that reference the symbol are listed.
1
1 '--no-define-common'
1 This option inhibits the assignment of addresses to common symbols.
1 The script command 'INHIBIT_COMMON_ALLOCATION' has the same effect.
1 ⇒Miscellaneous Commands.
1
1 The '--no-define-common' option allows decoupling the decision to
1 assign addresses to Common symbols from the choice of the output
1 file type; otherwise a non-Relocatable output type forces assigning
1 addresses to Common symbols. Using '--no-define-common' allows
1 Common symbols that are referenced from a shared library to be
1 assigned addresses only in the main program. This eliminates the
1 unused duplicate space in the shared library, and also prevents any
1 possible confusion over resolving to the wrong duplicate when there
1 are many dynamic modules with specialized search paths for runtime
1 symbol resolution.
1
1 '--force-group-allocation'
1 This option causes the linker to place section group members like
1 normal input sections, and to delete the section groups. This is
1 the default behaviour for a final link but this option can be used
1 to change the behaviour of a relocatable link ('-r'). The script
11 command 'FORCE_GROUP_ALLOCATION' has the same effect. ⇒
Miscellaneous Commands.
1
1 '--defsym=SYMBOL=EXPRESSION'
1 Create a global symbol in the output file, containing the absolute
1 address given by EXPRESSION. You may use this option as many times
1 as necessary to define multiple symbols in the command line. A
1 limited form of arithmetic is supported for the EXPRESSION in this
1 context: you may give a hexadecimal constant or the name of an
1 existing symbol, or use '+' and '-' to add or subtract hexadecimal
1 constants or symbols. If you need more elaborate expressions,
11 consider using the linker command language from a script (⇒
Assignments). _Note:_ there should be no white space between
1 SYMBOL, the equals sign ("<=>"), and EXPRESSION.
1
1 '--demangle[=STYLE]'
1 '--no-demangle'
1 These options control whether to demangle symbol names in error
1 messages and other output. When the linker is told to demangle, it
1 tries to present symbol names in a readable fashion: it strips
1 leading underscores if they are used by the object file format, and
1 converts C++ mangled symbol names into user readable names.
1 Different compilers have different mangling styles. The optional
1 demangling style argument can be used to choose an appropriate
1 demangling style for your compiler. The linker will demangle by
1 default unless the environment variable 'COLLECT_NO_DEMANGLE' is
1 set. These options may be used to override the default.
1
1 '-IFILE'
1 '--dynamic-linker=FILE'
1 Set the name of the dynamic linker. This is only meaningful when
1 generating dynamically linked ELF executables. The default dynamic
1 linker is normally correct; don't use this unless you know what you
1 are doing.
1
1 '--no-dynamic-linker'
1 When producing an executable file, omit the request for a dynamic
1 linker to be used at load-time. This is only meaningful for ELF
1 executables that contain dynamic relocations, and usually requires
1 entry point code that is capable of processing these relocations.
1
1 '--embedded-relocs'
1 This option is similar to the '--emit-relocs' option except that
1 the relocs are stored in a target specific section. This option is
1 only supported by the 'BFIN', 'CR16' and _M68K_ targets.
1
1 '--fatal-warnings'
1 '--no-fatal-warnings'
1 Treat all warnings as errors. The default behaviour can be
1 restored with the option '--no-fatal-warnings'.
1
1 '--force-exe-suffix'
1 Make sure that an output file has a .exe suffix.
1
1 If a successfully built fully linked output file does not have a
1 '.exe' or '.dll' suffix, this option forces the linker to copy the
1 output file to one of the same name with a '.exe' suffix. This
1 option is useful when using unmodified Unix makefiles on a
1 Microsoft Windows host, since some versions of Windows won't run an
1 image unless it ends in a '.exe' suffix.
1
1 '--gc-sections'
1 '--no-gc-sections'
1 Enable garbage collection of unused input sections. It is ignored
1 on targets that do not support this option. The default behaviour
1 (of not performing this garbage collection) can be restored by
1 specifying '--no-gc-sections' on the command line. Note that
1 garbage collection for COFF and PE format targets is supported, but
1 the implementation is currently considered to be experimental.
1
1 '--gc-sections' decides which input sections are used by examining
1 symbols and relocations. The section containing the entry symbol
1 and all sections containing symbols undefined on the command-line
1 will be kept, as will sections containing symbols referenced by
1 dynamic objects. Note that when building shared libraries, the
1 linker must assume that any visible symbol is referenced. Once
1 this initial set of sections has been determined, the linker
1 recursively marks as used any section referenced by their
1 relocations. See '--entry' and '--undefined'.
1
1 This option can be set when doing a partial link (enabled with
1 option '-r'). In this case the root of symbols kept must be
1 explicitly specified either by an '--entry' or '--undefined' option
1 or by a 'ENTRY' command in the linker script.
1
1 '--print-gc-sections'
1 '--no-print-gc-sections'
1 List all sections removed by garbage collection. The listing is
1 printed on stderr. This option is only effective if garbage
1 collection has been enabled via the '--gc-sections') option. The
1 default behaviour (of not listing the sections that are removed)
1 can be restored by specifying '--no-print-gc-sections' on the
1 command line.
1
1 '--gc-keep-exported'
1 When '--gc-sections' is enabled, this option prevents garbage
1 collection of unused input sections that contain global symbols
1 having default or protected visibility. This option is intended to
1 be used for executables where unreferenced sections would otherwise
1 be garbage collected regardless of the external visibility of
1 contained symbols. Note that this option has no effect when
1 linking shared objects since it is already the default behaviour.
1 This option is only supported for ELF format targets.
1
1 '--print-output-format'
1 Print the name of the default output format (perhaps influenced by
1 other command-line options). This is the string that would appear
11 in an 'OUTPUT_FORMAT' linker script command (⇒File
Commands).
1
1 '--print-memory-usage'
1 Print used size, total size and used size of memory regions created
1 with the ⇒MEMORY command. This is useful on embedded
1 targets to have a quick view of amount of free memory. The format
1 of the output has one headline and one line per region. It is both
1 human readable and easily parsable by tools. Here is an example of
1 an output:
1
1 Memory region Used Size Region Size %age Used
1 ROM: 256 KB 1 MB 25.00%
1 RAM: 32 B 2 GB 0.00%
1
1 '--help'
1 Print a summary of the command-line options on the standard output
1 and exit.
1
1 '--target-help'
1 Print a summary of all target specific options on the standard
1 output and exit.
1
1 '-Map=MAPFILE'
1 Print a link map to the file MAPFILE. See the description of the
1 '-M' option, above.
1
1 '--no-keep-memory'
1 'ld' normally optimizes for speed over memory usage by caching the
1 symbol tables of input files in memory. This option tells 'ld' to
1 instead optimize for memory usage, by rereading the symbol tables
1 as necessary. This may be required if 'ld' runs out of memory
1 space while linking a large executable.
1
1 '--no-undefined'
1 '-z defs'
1 Report unresolved symbol references from regular object files.
1 This is done even if the linker is creating a non-symbolic shared
1 library. The switch '--[no-]allow-shlib-undefined' controls the
1 behaviour for reporting unresolved references found in shared
1 libraries being linked in.
1
1 The effects of this option can be reverted by using '-z undefs'.
1
1 '--allow-multiple-definition'
1 '-z muldefs'
1 Normally when a symbol is defined multiple times, the linker will
1 report a fatal error. These options allow multiple definitions and
1 the first definition will be used.
1
1 '--allow-shlib-undefined'
1 '--no-allow-shlib-undefined'
1 Allows or disallows undefined symbols in shared libraries. This
1 switch is similar to '--no-undefined' except that it determines the
1 behaviour when the undefined symbols are in a shared library rather
1 than a regular object file. It does not affect how undefined
1 symbols in regular object files are handled.
1
1 The default behaviour is to report errors for any undefined symbols
1 referenced in shared libraries if the linker is being used to
1 create an executable, but to allow them if the linker is being used
1 to create a shared library.
1
1 The reasons for allowing undefined symbol references in shared
1 libraries specified at link time are that:
1
1 * A shared library specified at link time may not be the same as
1 the one that is available at load time, so the symbol might
1 actually be resolvable at load time.
1 * There are some operating systems, eg BeOS and HPPA, where
1 undefined symbols in shared libraries are normal.
1
1 The BeOS kernel for example patches shared libraries at load
1 time to select whichever function is most appropriate for the
1 current architecture. This is used, for example, to
1 dynamically select an appropriate memset function.
1
1 '--no-undefined-version'
1 Normally when a symbol has an undefined version, the linker will
1 ignore it. This option disallows symbols with undefined version
1 and a fatal error will be issued instead.
1
1 '--default-symver'
1 Create and use a default symbol version (the soname) for
1 unversioned exported symbols.
1
1 '--default-imported-symver'
1 Create and use a default symbol version (the soname) for
1 unversioned imported symbols.
1
1 '--no-warn-mismatch'
1 Normally 'ld' will give an error if you try to link together input
1 files that are mismatched for some reason, perhaps because they
1 have been compiled for different processors or for different
1 endiannesses. This option tells 'ld' that it should silently
1 permit such possible errors. This option should only be used with
1 care, in cases when you have taken some special action that ensures
1 that the linker errors are inappropriate.
1
1 '--no-warn-search-mismatch'
1 Normally 'ld' will give a warning if it finds an incompatible
1 library during a library search. This option silences the warning.
1
1 '--no-whole-archive'
1 Turn off the effect of the '--whole-archive' option for subsequent
1 archive files.
1
1 '--noinhibit-exec'
1 Retain the executable output file whenever it is still usable.
1 Normally, the linker will not produce an output file if it
1 encounters errors during the link process; it exits without writing
1 an output file when it issues any error whatsoever.
1
1 '-nostdlib'
1 Only search library directories explicitly specified on the command
1 line. Library directories specified in linker scripts (including
1 linker scripts specified on the command line) are ignored.
1
1 '--oformat=OUTPUT-FORMAT'
1 'ld' may be configured to support more than one kind of object
1 file. If your 'ld' is configured this way, you can use the
1 '--oformat' option to specify the binary format for the output
1 object file. Even when 'ld' is configured to support alternative
1 object formats, you don't usually need to specify this, as 'ld'
1 should be configured to produce as a default output format the most
1 usual format on each machine. OUTPUT-FORMAT is a text string, the
1 name of a particular format supported by the BFD libraries. (You
1 can list the available binary formats with 'objdump -i'.) The
1 script command 'OUTPUT_FORMAT' can also specify the output format,
1 but this option overrides it. ⇒BFD.
1
1 '--out-implib FILE'
1 Create an import library in FILE corresponding to the executable
1 the linker is generating (eg. a DLL or ELF program). This import
1 library (which should be called '*.dll.a' or '*.a' for DLLs) may be
1 used to link clients against the generated executable; this
1 behaviour makes it possible to skip a separate import library
1 creation step (eg. 'dlltool' for DLLs). This option is only
1 available for the i386 PE and ELF targetted ports of the linker.
1
1 '-pie'
1 '--pic-executable'
1 Create a position independent executable. This is currently only
1 supported on ELF platforms. Position independent executables are
1 similar to shared libraries in that they are relocated by the
1 dynamic linker to the virtual address the OS chooses for them
1 (which can vary between invocations). Like normal dynamically
1 linked executables they can be executed and symbols defined in the
1 executable cannot be overridden by shared libraries.
1
1 '-qmagic'
1 This option is ignored for Linux compatibility.
1
1 '-Qy'
1 This option is ignored for SVR4 compatibility.
1
1 '--relax'
1 '--no-relax'
1 An option with machine dependent effects. This option is only
1 supported on a few targets. ⇒'ld' and the H8/300 H8/300.
DONTPRINTYET 1 ⇒'ld' and the Intel 960 family i960. *Note'ld' and Xtensa
DONTPRINTYET 1DONTPRINTYET 1 ⇒'ld' and the Intel 960 family i960. ⇒'ld' and Xtensa
Processors Xtensa. *Note'ld' and the 68HC11 and 68HC12:
DONTPRINTYET 1DONTPRINTYET 1DONTPRINTYET 1 ⇒'ld' and the Intel 960 family i960. ⇒'ld' and Xtensa
Processors Xtensa. ⇒'ld' and the 68HC11 and 68HC12
M68HC11/68HC12. ⇒'ld' and the Altera Nios II Nios II. *Note1DONTPRINTYET 1DONTPRINTYET 1DONTPRINTYET 1 ⇒'ld' and the Intel 960 family i960. ⇒'ld' and Xtensa
Processors Xtensa. ⇒'ld' and the 68HC11 and 68HC12
M68HC11/68HC12. ⇒'ld' and the Altera Nios II Nios II. ⇒
'ld' and PowerPC 32-bit ELF Support PowerPC ELF32.
1
1 On some platforms the '--relax' option performs target specific,
1 global optimizations that become possible when the linker resolves
1 addressing in the program, such as relaxing address modes,
1 synthesizing new instructions, selecting shorter version of current
1 instructions, and combining constant values.
1
1 On some platforms these link time global optimizations may make
1 symbolic debugging of the resulting executable impossible. This is
1 known to be the case for the Matsushita MN10200 and MN10300 family
1 of processors.
1
1 On platforms where this is not supported, '--relax' is accepted,
1 but ignored.
1
1 On platforms where '--relax' is accepted the option '--no-relax'
1 can be used to disable the feature.
1
1 '--retain-symbols-file=FILENAME'
1 Retain _only_ the symbols listed in the file FILENAME, discarding
1 all others. FILENAME is simply a flat file, with one symbol name
1 per line. This option is especially useful in environments (such
1 as VxWorks) where a large global symbol table is accumulated
1 gradually, to conserve run-time memory.
1
1 '--retain-symbols-file' does _not_ discard undefined symbols, or
1 symbols needed for relocations.
1
1 You may only specify '--retain-symbols-file' once in the command
1 line. It overrides '-s' and '-S'.
1
1 '-rpath=DIR'
1 Add a directory to the runtime library search path. This is used
1 when linking an ELF executable with shared objects. All '-rpath'
1 arguments are concatenated and passed to the runtime linker, which
1 uses them to locate shared objects at runtime. The '-rpath' option
1 is also used when locating shared objects which are needed by
1 shared objects explicitly included in the link; see the description
1 of the '-rpath-link' option. If '-rpath' is not used when linking
1 an ELF executable, the contents of the environment variable
1 'LD_RUN_PATH' will be used if it is defined.
1
1 The '-rpath' option may also be used on SunOS. By default, on
1 SunOS, the linker will form a runtime search path out of all the
1 '-L' options it is given. If a '-rpath' option is used, the
1 runtime search path will be formed exclusively using the '-rpath'
1 options, ignoring the '-L' options. This can be useful when using
1 gcc, which adds many '-L' options which may be on NFS mounted file
1 systems.
1
1 For compatibility with other ELF linkers, if the '-R' option is
1 followed by a directory name, rather than a file name, it is
1 treated as the '-rpath' option.
1
1 '-rpath-link=DIR'
1 When using ELF or SunOS, one shared library may require another.
1 This happens when an 'ld -shared' link includes a shared library as
1 one of the input files.
1
1 When the linker encounters such a dependency when doing a
1 non-shared, non-relocatable link, it will automatically try to
1 locate the required shared library and include it in the link, if
1 it is not included explicitly. In such a case, the '-rpath-link'
1 option specifies the first set of directories to search. The
1 '-rpath-link' option may specify a sequence of directory names
1 either by specifying a list of names separated by colons, or by
1 appearing multiple times.
1
1 The tokens $ORIGIN and $LIB can appear in these search directories.
1 They will be replaced by the full path to the directory containing
1 the program or shared object in the case of $ORIGIN and either
1 'lib' - for 32-bit binaries - or 'lib64' - for 64-bit binaries - in
1 the case of $LIB.
1
1 The alternative form of these tokens - ${ORIGIN} and ${LIB} can
1 also be used. The token $PLATFORM is not supported.
1
1 This option should be used with caution as it overrides the search
1 path that may have been hard compiled into a shared library. In
1 such a case it is possible to use unintentionally a different
1 search path than the runtime linker would do.
1
1 The linker uses the following search paths to locate required
1 shared libraries:
1 1. Any directories specified by '-rpath-link' options.
1 2. Any directories specified by '-rpath' options. The difference
1 between '-rpath' and '-rpath-link' is that directories
1 specified by '-rpath' options are included in the executable
1 and used at runtime, whereas the '-rpath-link' option is only
1 effective at link time. Searching '-rpath' in this way is
1 only supported by native linkers and cross linkers which have
1 been configured with the '--with-sysroot' option.
1 3. On an ELF system, for native linkers, if the '-rpath' and
1 '-rpath-link' options were not used, search the contents of
1 the environment variable 'LD_RUN_PATH'.
1 4. On SunOS, if the '-rpath' option was not used, search any
1 directories specified using '-L' options.
1 5. For a native linker, search the contents of the environment
1 variable 'LD_LIBRARY_PATH'.
1 6. For a native ELF linker, the directories in 'DT_RUNPATH' or
1 'DT_RPATH' of a shared library are searched for shared
1 libraries needed by it. The 'DT_RPATH' entries are ignored if
1 'DT_RUNPATH' entries exist.
1 7. The default directories, normally '/lib' and '/usr/lib'.
1 8. For a native linker on an ELF system, if the file
1 '/etc/ld.so.conf' exists, the list of directories found in
1 that file.
1
1 If the required shared library is not found, the linker will issue
1 a warning and continue with the link.
1
1 '-shared'
1 '-Bshareable'
1 Create a shared library. This is currently only supported on ELF,
1 XCOFF and SunOS platforms. On SunOS, the linker will automatically
1 create a shared library if the '-e' option is not used and there
1 are undefined symbols in the link.
1
1 '--sort-common'
1 '--sort-common=ascending'
1 '--sort-common=descending'
1 This option tells 'ld' to sort the common symbols by alignment in
1 ascending or descending order when it places them in the
1 appropriate output sections. The symbol alignments considered are
1 sixteen-byte or larger, eight-byte, four-byte, two-byte, and
1 one-byte. This is to prevent gaps between symbols due to alignment
1 constraints. If no sorting order is specified, then descending
1 order is assumed.
1
1 '--sort-section=name'
1 This option will apply 'SORT_BY_NAME' to all wildcard section
1 patterns in the linker script.
1
1 '--sort-section=alignment'
1 This option will apply 'SORT_BY_ALIGNMENT' to all wildcard section
1 patterns in the linker script.
1
1 '--spare-dynamic-tags=COUNT'
1 This option specifies the number of empty slots to leave in the
1 .dynamic section of ELF shared objects. Empty slots may be needed
1 by post processing tools, such as the prelinker. The default is 5.
1
1 '--split-by-file[=SIZE]'
1 Similar to '--split-by-reloc' but creates a new output section for
1 each input file when SIZE is reached. SIZE defaults to a size of 1
1 if not given.
1
1 '--split-by-reloc[=COUNT]'
1 Tries to creates extra sections in the output file so that no
1 single output section in the file contains more than COUNT
1 relocations. This is useful when generating huge relocatable files
1 for downloading into certain real time kernels with the COFF object
1 file format; since COFF cannot represent more than 65535
1 relocations in a single section. Note that this will fail to work
1 with object file formats which do not support arbitrary sections.
1 The linker will not split up individual input sections for
1 redistribution, so if a single input section contains more than
1 COUNT relocations one output section will contain that many
1 relocations. COUNT defaults to a value of 32768.
1
1 '--stats'
1 Compute and display statistics about the operation of the linker,
1 such as execution time and memory usage.
1
1 '--sysroot=DIRECTORY'
1 Use DIRECTORY as the location of the sysroot, overriding the
1 configure-time default. This option is only supported by linkers
1 that were configured using '--with-sysroot'.
1
1 '--task-link'
1 This is used by COFF/PE based targets to create a task-linked
1 object file where all of the global symbols have been converted to
1 statics.
1
1 '--traditional-format'
1 For some targets, the output of 'ld' is different in some ways from
1 the output of some existing linker. This switch requests 'ld' to
1 use the traditional format instead.
1
1 For example, on SunOS, 'ld' combines duplicate entries in the
1 symbol string table. This can reduce the size of an output file
1 with full debugging information by over 30 percent. Unfortunately,
1 the SunOS 'dbx' program can not read the resulting program ('gdb'
1 has no trouble). The '--traditional-format' switch tells 'ld' to
1 not combine duplicate entries.
1
1 '--section-start=SECTIONNAME=ORG'
1 Locate a section in the output file at the absolute address given
1 by ORG. You may use this option as many times as necessary to
1 locate multiple sections in the command line. ORG must be a single
1 hexadecimal integer; for compatibility with other linkers, you may
1 omit the leading '0x' usually associated with hexadecimal values.
1 _Note:_ there should be no white space between SECTIONNAME, the
1 equals sign ("<=>"), and ORG.
1
1 '-Tbss=ORG'
1 '-Tdata=ORG'
1 '-Ttext=ORG'
1 Same as '--section-start', with '.bss', '.data' or '.text' as the
1 SECTIONNAME.
1
1 '-Ttext-segment=ORG'
1 When creating an ELF executable, it will set the address of the
1 first byte of the text segment.
1
1 '-Trodata-segment=ORG'
1 When creating an ELF executable or shared object for a target where
1 the read-only data is in its own segment separate from the
1 executable text, it will set the address of the first byte of the
1 read-only data segment.
1
1 '-Tldata-segment=ORG'
1 When creating an ELF executable or shared object for x86-64 medium
1 memory model, it will set the address of the first byte of the
1 ldata segment.
1
1 '--unresolved-symbols=METHOD'
1 Determine how to handle unresolved symbols. There are four
1 possible values for 'method':
1
1 'ignore-all'
1 Do not report any unresolved symbols.
1
1 'report-all'
1 Report all unresolved symbols. This is the default.
1
1 'ignore-in-object-files'
1 Report unresolved symbols that are contained in shared
1 libraries, but ignore them if they come from regular object
1 files.
1
1 'ignore-in-shared-libs'
1 Report unresolved symbols that come from regular object files,
1 but ignore them if they come from shared libraries. This can
1 be useful when creating a dynamic binary and it is known that
1 all the shared libraries that it should be referencing are
1 included on the linker's command line.
1
1 The behaviour for shared libraries on their own can also be
1 controlled by the '--[no-]allow-shlib-undefined' option.
1
1 Normally the linker will generate an error message for each
1 reported unresolved symbol but the option
1 '--warn-unresolved-symbols' can change this to a warning.
1
1 '--dll-verbose'
1 '--verbose[=NUMBER]'
1 Display the version number for 'ld' and list the linker emulations
1 supported. Display which input files can and cannot be opened.
1 Display the linker script being used by the linker. If the
1 optional NUMBER argument > 1, plugin symbol status will also be
1 displayed.
1
1 '--version-script=VERSION-SCRIPTFILE'
1 Specify the name of a version script to the linker. This is
1 typically used when creating shared libraries to specify additional
1 information about the version hierarchy for the library being
1 created. This option is only fully supported on ELF platforms
1 which support shared libraries; see ⇒VERSION. It is
1 partially supported on PE platforms, which can use version scripts
1 to filter symbol visibility in auto-export mode: any symbols marked
1 'local' in the version script will not be exported. ⇒WIN32.
1
1 '--warn-common'
1 Warn when a common symbol is combined with another common symbol or
1 with a symbol definition. Unix linkers allow this somewhat sloppy
1 practice, but linkers on some other operating systems do not. This
1 option allows you to find potential problems from combining global
1 symbols. Unfortunately, some C libraries use this practice, so you
1 may get some warnings about symbols in the libraries as well as in
1 your programs.
1
1 There are three kinds of global symbols, illustrated here by C
1 examples:
1
1 'int i = 1;'
1 A definition, which goes in the initialized data section of
1 the output file.
1
1 'extern int i;'
1 An undefined reference, which does not allocate space. There
1 must be either a definition or a common symbol for the
1 variable somewhere.
1
1 'int i;'
1 A common symbol. If there are only (one or more) common
1 symbols for a variable, it goes in the uninitialized data area
1 of the output file. The linker merges multiple common symbols
1 for the same variable into a single symbol. If they are of
1 different sizes, it picks the largest size. The linker turns
1 a common symbol into a declaration, if there is a definition
1 of the same variable.
1
1 The '--warn-common' option can produce five kinds of warnings.
1 Each warning consists of a pair of lines: the first describes the
1 symbol just encountered, and the second describes the previous
1 symbol encountered with the same name. One or both of the two
1 symbols will be a common symbol.
1
1 1. Turning a common symbol into a reference, because there is
1 already a definition for the symbol.
1 FILE(SECTION): warning: common of `SYMBOL'
1 overridden by definition
1 FILE(SECTION): warning: defined here
1
1 2. Turning a common symbol into a reference, because a later
1 definition for the symbol is encountered. This is the same as
1 the previous case, except that the symbols are encountered in
1 a different order.
1 FILE(SECTION): warning: definition of `SYMBOL'
1 overriding common
1 FILE(SECTION): warning: common is here
1
1 3. Merging a common symbol with a previous same-sized common
1 symbol.
1 FILE(SECTION): warning: multiple common
1 of `SYMBOL'
1 FILE(SECTION): warning: previous common is here
1
1 4. Merging a common symbol with a previous larger common symbol.
1 FILE(SECTION): warning: common of `SYMBOL'
1 overridden by larger common
1 FILE(SECTION): warning: larger common is here
1
1 5. Merging a common symbol with a previous smaller common symbol.
1 This is the same as the previous case, except that the symbols
1 are encountered in a different order.
1 FILE(SECTION): warning: common of `SYMBOL'
1 overriding smaller common
1 FILE(SECTION): warning: smaller common is here
1
1 '--warn-constructors'
1 Warn if any global constructors are used. This is only useful for
1 a few object file formats. For formats like COFF or ELF, the
1 linker can not detect the use of global constructors.
1
1 '--warn-multiple-gp'
1 Warn if multiple global pointer values are required in the output
1 file. This is only meaningful for certain processors, such as the
1 Alpha. Specifically, some processors put large-valued constants in
1 a special section. A special register (the global pointer) points
1 into the middle of this section, so that constants can be loaded
1 efficiently via a base-register relative addressing mode. Since
1 the offset in base-register relative mode is fixed and relatively
1 small (e.g., 16 bits), this limits the maximum size of the constant
1 pool. Thus, in large programs, it is often necessary to use
1 multiple global pointer values in order to be able to address all
1 possible constants. This option causes a warning to be issued
1 whenever this case occurs.
1
1 '--warn-once'
1 Only warn once for each undefined symbol, rather than once per
1 module which refers to it.
1
1 '--warn-section-align'
1 Warn if the address of an output section is changed because of
1 alignment. Typically, the alignment will be set by an input
1 section. The address will only be changed if it not explicitly
1 specified; that is, if the 'SECTIONS' command does not specify a
1 start address for the section (⇒SECTIONS).
1
1 '--warn-shared-textrel'
1 Warn if the linker adds a DT_TEXTREL to a shared object.
1
1 '--warn-alternate-em'
1 Warn if an object has alternate ELF machine code.
1
1 '--warn-unresolved-symbols'
1 If the linker is going to report an unresolved symbol (see the
1 option '--unresolved-symbols') it will normally generate an error.
1 This option makes it generate a warning instead.
1
1 '--error-unresolved-symbols'
1 This restores the linker's default behaviour of generating errors
1 when it is reporting unresolved symbols.
1
1 '--whole-archive'
1 For each archive mentioned on the command line after the
1 '--whole-archive' option, include every object file in the archive
1 in the link, rather than searching the archive for the required
1 object files. This is normally used to turn an archive file into a
1 shared library, forcing every object to be included in the
1 resulting shared library. This option may be used more than once.
1
1 Two notes when using this option from gcc: First, gcc doesn't know
1 about this option, so you have to use '-Wl,-whole-archive'.
1 Second, don't forget to use '-Wl,-no-whole-archive' after your list
1 of archives, because gcc will add its own list of archives to your
1 link and you may not want this flag to affect those as well.
1
1 '--wrap=SYMBOL'
1 Use a wrapper function for SYMBOL. Any undefined reference to
1 SYMBOL will be resolved to '__wrap_SYMBOL'. Any undefined
1 reference to '__real_SYMBOL' will be resolved to SYMBOL.
1
1 This can be used to provide a wrapper for a system function. The
1 wrapper function should be called '__wrap_SYMBOL'. If it wishes to
1 call the system function, it should call '__real_SYMBOL'.
1
1 Here is a trivial example:
1
1 void *
1 __wrap_malloc (size_t c)
1 {
1 printf ("malloc called with %zu\n", c);
1 return __real_malloc (c);
1 }
1
1 If you link other code with this file using '--wrap malloc', then
1 all calls to 'malloc' will call the function '__wrap_malloc'
1 instead. The call to '__real_malloc' in '__wrap_malloc' will call
1 the real 'malloc' function.
1
1 You may wish to provide a '__real_malloc' function as well, so that
1 links without the '--wrap' option will succeed. If you do this,
1 you should not put the definition of '__real_malloc' in the same
1 file as '__wrap_malloc'; if you do, the assembler may resolve the
1 call before the linker has a chance to wrap it to 'malloc'.
1
1 '--eh-frame-hdr'
1 '--no-eh-frame-hdr'
1 Request ('--eh-frame-hdr') or suppress ('--no-eh-frame-hdr') the
1 creation of '.eh_frame_hdr' section and ELF 'PT_GNU_EH_FRAME'
1 segment header.
1
1 '--no-ld-generated-unwind-info'
1 Request creation of '.eh_frame' unwind info for linker generated
1 code sections like PLT. This option is on by default if linker
1 generated unwind info is supported.
1
1 '--enable-new-dtags'
1 '--disable-new-dtags'
1 This linker can create the new dynamic tags in ELF. But the older
1 ELF systems may not understand them. If you specify
1 '--enable-new-dtags', the new dynamic tags will be created as
1 needed and older dynamic tags will be omitted. If you specify
1 '--disable-new-dtags', no new dynamic tags will be created. By
1 default, the new dynamic tags are not created. Note that those
1 options are only available for ELF systems.
1
1 '--hash-size=NUMBER'
1 Set the default size of the linker's hash tables to a prime number
1 close to NUMBER. Increasing this value can reduce the length of
1 time it takes the linker to perform its tasks, at the expense of
1 increasing the linker's memory requirements. Similarly reducing
1 this value can reduce the memory requirements at the expense of
1 speed.
1
1 '--hash-style=STYLE'
1 Set the type of linker's hash table(s). STYLE can be either 'sysv'
1 for classic ELF '.hash' section, 'gnu' for new style GNU
1 '.gnu.hash' section or 'both' for both the classic ELF '.hash' and
1 new style GNU '.gnu.hash' hash tables. The default is 'sysv'.
1
1 '--compress-debug-sections=none'
1 '--compress-debug-sections=zlib'
1 '--compress-debug-sections=zlib-gnu'
1 '--compress-debug-sections=zlib-gabi'
1 On ELF platforms, these options control how DWARF debug sections
1 are compressed using zlib.
1
1 '--compress-debug-sections=none' doesn't compress DWARF debug
1 sections. '--compress-debug-sections=zlib-gnu' compresses DWARF
1 debug sections and renames them to begin with '.zdebug' instead of
1 '.debug'. '--compress-debug-sections=zlib-gabi' also compresses
1 DWARF debug sections, but rather than renaming them it sets the
1 SHF_COMPRESSED flag in the sections' headers.
1
1 The '--compress-debug-sections=zlib' option is an alias for
1 '--compress-debug-sections=zlib-gabi'.
1
1 Note that this option overrides any compression in input debug
1 sections, so if a binary is linked with
1 '--compress-debug-sections=none' for example, then any compressed
1 debug sections in input files will be uncompressed before they are
1 copied into the output binary.
1
1 The default compression behaviour varies depending upon the target
1 involved and the configure options used to build the toolchain.
1 The default can be determined by examining the output from the
1 linker's '--help' option.
1
1 '--reduce-memory-overheads'
1 This option reduces memory requirements at ld runtime, at the
1 expense of linking speed. This was introduced to select the old
1 O(n^2) algorithm for link map file generation, rather than the new
1 O(n) algorithm which uses about 40% more memory for symbol storage.
1
1 Another effect of the switch is to set the default hash table size
1 to 1021, which again saves memory at the cost of lengthening the
1 linker's run time. This is not done however if the '--hash-size'
1 switch has been used.
1
1 The '--reduce-memory-overheads' switch may be also be used to
1 enable other tradeoffs in future versions of the linker.
1
1 '--build-id'
1 '--build-id=STYLE'
1 Request the creation of a '.note.gnu.build-id' ELF note section or
1 a '.buildid' COFF section. The contents of the note are unique
1 bits identifying this linked file. STYLE can be 'uuid' to use 128
1 random bits, 'sha1' to use a 160-bit SHA1 hash on the normative
1 parts of the output contents, 'md5' to use a 128-bit MD5 hash on
1 the normative parts of the output contents, or '0xHEXSTRING' to use
1 a chosen bit string specified as an even number of hexadecimal
1 digits ('-' and ':' characters between digit pairs are ignored).
1 If STYLE is omitted, 'sha1' is used.
1
1 The 'md5' and 'sha1' styles produces an identifier that is always
1 the same in an identical output file, but will be unique among all
1 nonidentical output files. It is not intended to be compared as a
1 checksum for the file's contents. A linked file may be changed
1 later by other tools, but the build ID bit string identifying the
1 original linked file does not change.
1
1 Passing 'none' for STYLE disables the setting from any '--build-id'
1 options earlier on the command line.
1
1 2.1.1 Options Specific to i386 PE Targets
1 -----------------------------------------
1
1 The i386 PE linker supports the '-shared' option, which causes the
1 output to be a dynamically linked library (DLL) instead of a normal
1 executable. You should name the output '*.dll' when you use this
1 option. In addition, the linker fully supports the standard '*.def'
1 files, which may be specified on the linker command line like an object
1 file (in fact, it should precede archives it exports symbols from, to
1 ensure that they get linked in, just like a normal object file).
1
1 In addition to the options common to all targets, the i386 PE linker
1 support additional command line options that are specific to the i386 PE
1 target. Options that take values may be separated from their values by
1 either a space or an equals sign.
1
1 '--add-stdcall-alias'
1 If given, symbols with a stdcall suffix (@NN) will be exported
1 as-is and also with the suffix stripped. [This option is specific
1 to the i386 PE targeted port of the linker]
1
1 '--base-file FILE'
1 Use FILE as the name of a file in which to save the base addresses
1 of all the relocations needed for generating DLLs with 'dlltool'.
1 [This is an i386 PE specific option]
1
1 '--dll'
1 Create a DLL instead of a regular executable. You may also use
1 '-shared' or specify a 'LIBRARY' in a given '.def' file. [This
1 option is specific to the i386 PE targeted port of the linker]
1
1 '--enable-long-section-names'
1 '--disable-long-section-names'
1 The PE variants of the COFF object format add an extension that
1 permits the use of section names longer than eight characters, the
1 normal limit for COFF. By default, these names are only allowed in
1 object files, as fully-linked executable images do not carry the
1 COFF string table required to support the longer names. As a GNU
1 extension, it is possible to allow their use in executable images
1 as well, or to (probably pointlessly!) disallow it in object
1 files, by using these two options. Executable images generated
1 with these long section names are slightly non-standard, carrying
1 as they do a string table, and may generate confusing output when
1 examined with non-GNU PE-aware tools, such as file viewers and
1 dumpers. However, GDB relies on the use of PE long section names
1 to find Dwarf-2 debug information sections in an executable image
1 at runtime, and so if neither option is specified on the
1 command-line, 'ld' will enable long section names, overriding the
1 default and technically correct behaviour, when it finds the
1 presence of debug information while linking an executable image and
1 not stripping symbols. [This option is valid for all PE targeted
1 ports of the linker]
1
1 '--enable-stdcall-fixup'
1 '--disable-stdcall-fixup'
1 If the link finds a symbol that it cannot resolve, it will attempt
1 to do "fuzzy linking" by looking for another defined symbol that
1 differs only in the format of the symbol name (cdecl vs stdcall)
1 and will resolve that symbol by linking to the match. For example,
1 the undefined symbol '_foo' might be linked to the function
1 '_foo@12', or the undefined symbol '_bar@16' might be linked to the
1 function '_bar'. When the linker does this, it prints a warning,
1 since it normally should have failed to link, but sometimes import
1 libraries generated from third-party dlls may need this feature to
1 be usable. If you specify '--enable-stdcall-fixup', this feature
1 is fully enabled and warnings are not printed. If you specify
1 '--disable-stdcall-fixup', this feature is disabled and such
1 mismatches are considered to be errors. [This option is specific
1 to the i386 PE targeted port of the linker]
1
1 '--leading-underscore'
1 '--no-leading-underscore'
1 For most targets default symbol-prefix is an underscore and is
1 defined in target's description. By this option it is possible to
1 disable/enable the default underscore symbol-prefix.
1
1 '--export-all-symbols'
1 If given, all global symbols in the objects used to build a DLL
1 will be exported by the DLL. Note that this is the default if there
1 otherwise wouldn't be any exported symbols. When symbols are
1 explicitly exported via DEF files or implicitly exported via
1 function attributes, the default is to not export anything else
1 unless this option is given. Note that the symbols 'DllMain@12',
1 'DllEntryPoint@0', 'DllMainCRTStartup@12', and 'impure_ptr' will
1 not be automatically exported. Also, symbols imported from other
1 DLLs will not be re-exported, nor will symbols specifying the DLL's
1 internal layout such as those beginning with '_head_' or ending
1 with '_iname'. In addition, no symbols from 'libgcc', 'libstd++',
1 'libmingw32', or 'crtX.o' will be exported. Symbols whose names
1 begin with '__rtti_' or '__builtin_' will not be exported, to help
1 with C++ DLLs. Finally, there is an extensive list of
1 cygwin-private symbols that are not exported (obviously, this
1 applies on when building DLLs for cygwin targets). These
1 cygwin-excludes are: '_cygwin_dll_entry@12',
1 '_cygwin_crt0_common@8', '_cygwin_noncygwin_dll_entry@12',
1 '_fmode', '_impure_ptr', 'cygwin_attach_dll', 'cygwin_premain0',
1 'cygwin_premain1', 'cygwin_premain2', 'cygwin_premain3', and
1 'environ'. [This option is specific to the i386 PE targeted port
1 of the linker]
1
1 '--exclude-symbols SYMBOL,SYMBOL,...'
1 Specifies a list of symbols which should not be automatically
1 exported. The symbol names may be delimited by commas or colons.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--exclude-all-symbols'
1 Specifies no symbols should be automatically exported. [This
1 option is specific to the i386 PE targeted port of the linker]
1
1 '--file-alignment'
1 Specify the file alignment. Sections in the file will always begin
1 at file offsets which are multiples of this number. This defaults
1 to 512. [This option is specific to the i386 PE targeted port of
1 the linker]
1
1 '--heap RESERVE'
1 '--heap RESERVE,COMMIT'
1 Specify the number of bytes of memory to reserve (and optionally
1 commit) to be used as heap for this program. The default is 1MB
1 reserved, 4K committed. [This option is specific to the i386 PE
1 targeted port of the linker]
1
1 '--image-base VALUE'
1 Use VALUE as the base address of your program or dll. This is the
1 lowest memory location that will be used when your program or dll
1 is loaded. To reduce the need to relocate and improve performance
1 of your dlls, each should have a unique base address and not
1 overlap any other dlls. The default is 0x400000 for executables,
1 and 0x10000000 for dlls. [This option is specific to the i386 PE
1 targeted port of the linker]
1
1 '--kill-at'
1 If given, the stdcall suffixes (@NN) will be stripped from symbols
1 before they are exported. [This option is specific to the i386 PE
1 targeted port of the linker]
1
1 '--large-address-aware'
1 If given, the appropriate bit in the "Characteristics" field of the
1 COFF header is set to indicate that this executable supports
1 virtual addresses greater than 2 gigabytes. This should be used in
1 conjunction with the /3GB or /USERVA=VALUE megabytes switch in the
1 "[operating systems]" section of the BOOT.INI. Otherwise, this bit
1 has no effect. [This option is specific to PE targeted ports of
1 the linker]
1
1 '--disable-large-address-aware'
1 Reverts the effect of a previous '--large-address-aware' option.
1 This is useful if '--large-address-aware' is always set by the
1 compiler driver (e.g. Cygwin gcc) and the executable does not
1 support virtual addresses greater than 2 gigabytes. [This option
1 is specific to PE targeted ports of the linker]
1
1 '--major-image-version VALUE'
1 Sets the major number of the "image version". Defaults to 1.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--major-os-version VALUE'
1 Sets the major number of the "os version". Defaults to 4. [This
1 option is specific to the i386 PE targeted port of the linker]
1
1 '--major-subsystem-version VALUE'
1 Sets the major number of the "subsystem version". Defaults to 4.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--minor-image-version VALUE'
1 Sets the minor number of the "image version". Defaults to 0.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--minor-os-version VALUE'
1 Sets the minor number of the "os version". Defaults to 0. [This
1 option is specific to the i386 PE targeted port of the linker]
1
1 '--minor-subsystem-version VALUE'
1 Sets the minor number of the "subsystem version". Defaults to 0.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--output-def FILE'
1 The linker will create the file FILE which will contain a DEF file
1 corresponding to the DLL the linker is generating. This DEF file
1 (which should be called '*.def') may be used to create an import
1 library with 'dlltool' or may be used as a reference to
1 automatically or implicitly exported symbols. [This option is
1 specific to the i386 PE targeted port of the linker]
1
1 '--enable-auto-image-base'
1 '--enable-auto-image-base=VALUE'
1 Automatically choose the image base for DLLs, optionally starting
1 with base VALUE, unless one is specified using the '--image-base'
1 argument. By using a hash generated from the dllname to create
1 unique image bases for each DLL, in-memory collisions and
1 relocations which can delay program execution are avoided. [This
1 option is specific to the i386 PE targeted port of the linker]
1
1 '--disable-auto-image-base'
1 Do not automatically generate a unique image base. If there is no
1 user-specified image base ('--image-base') then use the platform
1 default. [This option is specific to the i386 PE targeted port of
1 the linker]
1
1 '--dll-search-prefix STRING'
1 When linking dynamically to a dll without an import library, search
1 for '<string><basename>.dll' in preference to 'lib<basename>.dll'.
1 This behaviour allows easy distinction between DLLs built for the
1 various "subplatforms": native, cygwin, uwin, pw, etc. For
1 instance, cygwin DLLs typically use '--dll-search-prefix=cyg'.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--enable-auto-import'
1 Do sophisticated linking of '_symbol' to '__imp__symbol' for DATA
1 imports from DLLs, and create the necessary thunking symbols when
1 building the import libraries with those DATA exports. Note: Use
1 of the 'auto-import' extension will cause the text section of the
1 image file to be made writable. This does not conform to the
1 PE-COFF format specification published by Microsoft.
1
1 Note - use of the 'auto-import' extension will also cause read only
1 data which would normally be placed into the .rdata section to be
1 placed into the .data section instead. This is in order to work
1 around a problem with consts that is described here:
1 http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
1
1 Using 'auto-import' generally will 'just work' - but sometimes you
1 may see this message:
1
1 "variable '<var>' can't be auto-imported. Please read the
1 documentation for ld's '--enable-auto-import' for details."
1
1 This message occurs when some (sub)expression accesses an address
1 ultimately given by the sum of two constants (Win32 import tables
1 only allow one). Instances where this may occur include accesses
1 to member fields of struct variables imported from a DLL, as well
1 as using a constant index into an array variable imported from a
1 DLL. Any multiword variable (arrays, structs, long long, etc) may
1 trigger this error condition. However, regardless of the exact
1 data type of the offending exported variable, ld will always detect
1 it, issue the warning, and exit.
1
1 There are several ways to address this difficulty, regardless of
1 the data type of the exported variable:
1
1 One way is to use -enable-runtime-pseudo-reloc switch. This leaves
1 the task of adjusting references in your client code for runtime
1 environment, so this method works only when runtime environment
1 supports this feature.
1
1 A second solution is to force one of the 'constants' to be a
1 variable - that is, unknown and un-optimizable at compile time.
1 For arrays, there are two possibilities: a) make the indexee (the
1 array's address) a variable, or b) make the 'constant' index a
1 variable. Thus:
1
1 extern type extern_array[];
1 extern_array[1] -->
1 { volatile type *t=extern_array; t[1] }
1
1 or
1
1 extern type extern_array[];
1 extern_array[1] -->
1 { volatile int t=1; extern_array[t] }
1
1 For structs (and most other multiword data types) the only option
1 is to make the struct itself (or the long long, or the ...)
1 variable:
1
1 extern struct s extern_struct;
1 extern_struct.field -->
1 { volatile struct s *t=&extern_struct; t->field }
1
1 or
1
1 extern long long extern_ll;
1 extern_ll -->
1 { volatile long long * local_ll=&extern_ll; *local_ll }
1
1 A third method of dealing with this difficulty is to abandon
1 'auto-import' for the offending symbol and mark it with
1 '__declspec(dllimport)'. However, in practice that requires using
1 compile-time #defines to indicate whether you are building a DLL,
1 building client code that will link to the DLL, or merely
1 building/linking to a static library. In making the choice between
1 the various methods of resolving the 'direct address with constant
1 offset' problem, you should consider typical real-world usage:
1
1 Original:
1 --foo.h
1 extern int arr[];
1 --foo.c
1 #include "foo.h"
1 void main(int argc, char **argv){
1 printf("%d\n",arr[1]);
1 }
1
1 Solution 1:
1 --foo.h
1 extern int arr[];
1 --foo.c
1 #include "foo.h"
1 void main(int argc, char **argv){
1 /* This workaround is for win32 and cygwin; do not "optimize" */
1 volatile int *parr = arr;
1 printf("%d\n",parr[1]);
1 }
1
1 Solution 2:
1 --foo.h
1 /* Note: auto-export is assumed (no __declspec(dllexport)) */
1 #if (defined(_WIN32) || defined(__CYGWIN__)) && \
1 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
1 #define FOO_IMPORT __declspec(dllimport)
1 #else
1 #define FOO_IMPORT
1 #endif
1 extern FOO_IMPORT int arr[];
1 --foo.c
1 #include "foo.h"
1 void main(int argc, char **argv){
1 printf("%d\n",arr[1]);
1 }
1
1 A fourth way to avoid this problem is to re-code your library to
1 use a functional interface rather than a data interface for the
1 offending variables (e.g. set_foo() and get_foo() accessor
1 functions). [This option is specific to the i386 PE targeted port
1 of the linker]
1
1 '--disable-auto-import'
1 Do not attempt to do sophisticated linking of '_symbol' to
1 '__imp__symbol' for DATA imports from DLLs. [This option is
1 specific to the i386 PE targeted port of the linker]
1
1 '--enable-runtime-pseudo-reloc'
1 If your code contains expressions described in -enable-auto-import
1 section, that is, DATA imports from DLL with non-zero offset, this
1 switch will create a vector of 'runtime pseudo relocations' which
1 can be used by runtime environment to adjust references to such
1 data in your client code. [This option is specific to the i386 PE
1 targeted port of the linker]
1
1 '--disable-runtime-pseudo-reloc'
1 Do not create pseudo relocations for non-zero offset DATA imports
1 from DLLs. [This option is specific to the i386 PE targeted port
1 of the linker]
1
1 '--enable-extra-pe-debug'
1 Show additional debug info related to auto-import symbol thunking.
1 [This option is specific to the i386 PE targeted port of the
1 linker]
1
1 '--section-alignment'
1 Sets the section alignment. Sections in memory will always begin
1 at addresses which are a multiple of this number. Defaults to
1 0x1000. [This option is specific to the i386 PE targeted port of
1 the linker]
1
1 '--stack RESERVE'
1 '--stack RESERVE,COMMIT'
1 Specify the number of bytes of memory to reserve (and optionally
1 commit) to be used as stack for this program. The default is 2MB
1 reserved, 4K committed. [This option is specific to the i386 PE
1 targeted port of the linker]
1
1 '--subsystem WHICH'
1 '--subsystem WHICH:MAJOR'
1 '--subsystem WHICH:MAJOR.MINOR'
1 Specifies the subsystem under which your program will execute. The
1 legal values for WHICH are 'native', 'windows', 'console', 'posix',
1 and 'xbox'. You may optionally set the subsystem version also.
1 Numeric values are also accepted for WHICH. [This option is
1 specific to the i386 PE targeted port of the linker]
1
1 The following options set flags in the 'DllCharacteristics' field
1 of the PE file header: [These options are specific to PE targeted
1 ports of the linker]
1
1 '--high-entropy-va'
1 Image is compatible with 64-bit address space layout randomization
1 (ASLR).
1
1 '--dynamicbase'
1 The image base address may be relocated using address space layout
1 randomization (ASLR). This feature was introduced with MS Windows
1 Vista for i386 PE targets.
1
1 '--forceinteg'
1 Code integrity checks are enforced.
1
1 '--nxcompat'
1 The image is compatible with the Data Execution Prevention. This
1 feature was introduced with MS Windows XP SP2 for i386 PE targets.
1
1 '--no-isolation'
1 Although the image understands isolation, do not isolate the image.
1
1 '--no-seh'
1 The image does not use SEH. No SE handler may be called from this
1 image.
1
1 '--no-bind'
1 Do not bind this image.
1
1 '--wdmdriver'
1 The driver uses the MS Windows Driver Model.
1
1 '--tsaware'
1 The image is Terminal Server aware.
1
1 '--insert-timestamp'
1 '--no-insert-timestamp'
1 Insert a real timestamp into the image. This is the default
1 behaviour as it matches legacy code and it means that the image
1 will work with other, proprietary tools. The problem with this
1 default is that it will result in slightly different images being
1 produced each time the same sources are linked. The option
1 '--no-insert-timestamp' can be used to insert a zero value for the
1 timestamp, this ensuring that binaries produced from identical
1 sources will compare identically.
1
1 2.1.2 Options specific to C6X uClinux targets
1 ---------------------------------------------
1
1 The C6X uClinux target uses a binary format called DSBT to support
1 shared libraries. Each shared library in the system needs to have a
1 unique index; all executables use an index of 0.
1
1 '--dsbt-size SIZE'
1 This option sets the number of entries in the DSBT of the current
1 executable or shared library to SIZE. The default is to create a
1 table with 64 entries.
1
1 '--dsbt-index INDEX'
1 This option sets the DSBT index of the current executable or shared
1 library to INDEX. The default is 0, which is appropriate for
1 generating executables. If a shared library is generated with a
1 DSBT index of 0, the 'R_C6000_DSBT_INDEX' relocs are copied into
1 the output file.
1
1 The '--no-merge-exidx-entries' switch disables the merging of
1 adjacent exidx entries in frame unwind info.
1
1 2.1.3 Options specific to Motorola 68HC11 and 68HC12 targets
1 ------------------------------------------------------------
1
1 The 68HC11 and 68HC12 linkers support specific options to control the
1 memory bank switching mapping and trampoline code generation.
1
1 '--no-trampoline'
1 This option disables the generation of trampoline. By default a
1 trampoline is generated for each far function which is called using
1 a 'jsr' instruction (this happens when a pointer to a far function
1 is taken).
1
1 '--bank-window NAME'
1 This option indicates to the linker the name of the memory region
1 in the 'MEMORY' specification that describes the memory bank
1 window. The definition of such region is then used by the linker
1 to compute paging and addresses within the memory window.
1
1 2.1.4 Options specific to Motorola 68K target
1 ---------------------------------------------
1
1 The following options are supported to control handling of GOT
1 generation when linking for 68K targets.
1
1 '--got=TYPE'
1 This option tells the linker which GOT generation scheme to use.
1 TYPE should be one of 'single', 'negative', 'multigot' or 'target'.
1 For more information refer to the Info entry for 'ld'.
1
1 2.1.5 Options specific to MIPS targets
1 --------------------------------------
1
1 The following options are supported to control microMIPS instruction
1 generation and branch relocation checks for ISA mode transitions when
1 linking for MIPS targets.
1
1 '--insn32'
1 '--no-insn32'
1 These options control the choice of microMIPS instructions used in
1 code generated by the linker, such as that in the PLT or lazy
1 binding stubs, or in relaxation. If '--insn32' is used, then the
1 linker only uses 32-bit instruction encodings. By default or if
1 '--no-insn32' is used, all instruction encodings are used,
1 including 16-bit ones where possible.
1
1 '--ignore-branch-isa'
1 '--no-ignore-branch-isa'
1 These options control branch relocation checks for invalid ISA mode
1 transitions. If '--ignore-branch-isa' is used, then the linker
1 accepts any branch relocations and any ISA mode transition required
1 is lost in relocation calculation, except for some cases of 'BAL'
1 instructions which meet relaxation conditions and are converted to
1 equivalent 'JALX' instructions as the associated relocation is
1 calculated. By default or if '--no-ignore-branch-isa' is used a
1 check is made causing the loss of an ISA mode transition to produce
1 an error.
1