1<html lang="en"> 2<head> 3<title>Options - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Invocation.html#Invocation" title="Invocation"> 9<link rel="next" href="Environment.html#Environment" title="Environment"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12This file documents the GNU linker LD 13(Sourcery CodeBench Lite 2011.09-69) 14version 2.21.53. 15 16Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 172001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. 18 19Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.3 21or any later version published by the Free Software Foundation; 22with no Invariant Sections, with no Front-Cover Texts, and with no 23Back-Cover Texts. A copy of the license is included in the 24section entitled ``GNU Free Documentation License''.--> 25<meta http-equiv="Content-Style-Type" content="text/css"> 26<style type="text/css"><!-- 27 pre.display { font-family:inherit } 28 pre.format { font-family:inherit } 29 pre.smalldisplay { font-family:inherit; font-size:smaller } 30 pre.smallformat { font-family:inherit; font-size:smaller } 31 pre.smallexample { font-size:smaller } 32 pre.smalllisp { font-size:smaller } 33 span.sc { font-variant:small-caps } 34 span.roman { font-family:serif; font-weight:normal; } 35 span.sansserif { font-family:sans-serif; font-weight:normal; } 36--></style> 37<link rel="stylesheet" type="text/css" href="../cs.css"> 38</head> 39<body> 40<div class="node"> 41<a name="Options"></a> 42<p> 43Next: <a rel="next" accesskey="n" href="Environment.html#Environment">Environment</a>, 44Up: <a rel="up" accesskey="u" href="Invocation.html#Invocation">Invocation</a> 45<hr> 46</div> 47 48<h3 class="section">2.1 Command Line Options</h3> 49 50 <p><a name="index-command-line-3"></a><a name="index-options-4"></a> 51<!-- man begin OPTIONS --> 52 53 <p>The linker supports a plethora of command-line options, but in actual 54practice few of them are used in any particular context. 55<a name="index-standard-Unix-system-5"></a>For instance, a frequent use of <samp><span class="command">ld</span></samp> is to link standard Unix 56object files on a standard, supported Unix system. On such a system, to 57link a file <code>hello.o</code>: 58 59<pre class="smallexample"> ld -o <var>output</var> /lib/crt0.o hello.o -lc 60</pre> 61 <p>This tells <samp><span class="command">ld</span></samp> to produce a file called <var>output</var> as the 62result of linking the file <code>/lib/crt0.o</code> with <code>hello.o</code> and 63the library <code>libc.a</code>, which will come from the standard search 64directories. (See the discussion of the ‘<samp><span class="samp">-l</span></samp>’ option below.) 65 66 <p>Some of the command-line options to <samp><span class="command">ld</span></samp> may be specified at any 67point in the command line. However, options which refer to files, such 68as ‘<samp><span class="samp">-l</span></samp>’ or ‘<samp><span class="samp">-T</span></samp>’, cause the file to be read at the point at 69which the option appears in the command line, relative to the object 70files and other file options. Repeating non-file options with a 71different argument will either have no further effect, or override prior 72occurrences (those further to the left on the command line) of that 73option. Options which may be meaningfully specified more than once are 74noted in the descriptions below. 75 76 <p><a name="index-object-files-6"></a>Non-option arguments are object files or archives which are to be linked 77together. They may follow, precede, or be mixed in with command-line 78options, except that an object file argument may not be placed between 79an option and its argument. 80 81 <p>Usually the linker is invoked with at least one object file, but you can 82specify other forms of binary input files using ‘<samp><span class="samp">-l</span></samp>’, ‘<samp><span class="samp">-R</span></samp>’, 83and the script command language. If <em>no</em> binary input files at all 84are specified, the linker does not produce any output, and issues the 85message ‘<samp><span class="samp">No input files</span></samp>’. 86 87 <p>If the linker cannot recognize the format of an object file, it will 88assume that it is a linker script. A script specified in this way 89augments the main linker script used for the link (either the default 90linker script or the one specified by using ‘<samp><span class="samp">-T</span></samp>’). This feature 91permits the linker to link against a file which appears to be an object 92or an archive, but actually merely defines some symbol values, or uses 93<code>INPUT</code> or <code>GROUP</code> to load other objects. Specifying a 94script in this way merely augments the main linker script, with the 95extra commands placed after the main script; use the ‘<samp><span class="samp">-T</span></samp>’ option 96to replace the default linker script entirely, but note the effect of 97the <code>INSERT</code> command. See <a href="Scripts.html#Scripts">Scripts</a>. 98 99 <p>For options whose names are a single letter, 100option arguments must either follow the option letter without intervening 101whitespace, or be given as separate arguments immediately following the 102option that requires them. 103 104 <p>For options whose names are multiple letters, either one dash or two can 105precede the option name; for example, ‘<samp><span class="samp">-trace-symbol</span></samp>’ and 106‘<samp><span class="samp">--trace-symbol</span></samp>’ are equivalent. Note—there is one exception to 107this rule. Multiple letter options that start with a lower case 'o' can 108only be preceded by two dashes. This is to reduce confusion with the 109‘<samp><span class="samp">-o</span></samp>’ option. So for example ‘<samp><span class="samp">-omagic</span></samp>’ sets the output file 110name to ‘<samp><span class="samp">magic</span></samp>’ whereas ‘<samp><span class="samp">--omagic</span></samp>’ sets the NMAGIC flag on the 111output. 112 113 <p>Arguments to multiple-letter options must either be separated from the 114option name by an equals sign, or be given as separate arguments 115immediately following the option that requires them. For example, 116‘<samp><span class="samp">--trace-symbol foo</span></samp>’ and ‘<samp><span class="samp">--trace-symbol=foo</span></samp>’ are equivalent. 117Unique abbreviations of the names of multiple-letter options are 118accepted. 119 120 <p>Note—if the linker is being invoked indirectly, via a compiler driver 121(e.g. ‘<samp><span class="samp">gcc</span></samp>’) then all the linker command line options should be 122prefixed by ‘<samp><span class="samp">-Wl,</span></samp>’ (or whatever is appropriate for the particular 123compiler driver) like this: 124 125<pre class="smallexample"> gcc -Wl,--start-group foo.o bar.o -Wl,--end-group 126</pre> 127 <p>This is important, because otherwise the compiler driver program may 128silently drop the linker options, resulting in a bad link. Confusion 129may also arise when passing options that require values through a 130driver, as the use of a space between option and argument acts as 131a separator, and causes the driver to pass only the option to the linker 132and the argument to the compiler. In this case, it is simplest to use 133the joined forms of both single- and multiple-letter options, such as: 134 135<pre class="smallexample"> gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map 136</pre> 137 <p>Here is a table of the generic command line switches accepted by the GNU 138linker: 139 140 <dl> 141<!-- This file is designed to be included in manuals that use --> 142<!-- expandargv. --> 143 144 <dt><code>@</code><var>file</var><dd>Read command-line options from <var>file</var>. The options read are 145inserted in place of the original @<var>file</var> option. If <var>file</var> 146does not exist, or cannot be read, then the option will be treated 147literally, and not removed. 148 149 <p>Options in <var>file</var> are separated by whitespace. A whitespace 150character may be included in an option by surrounding the entire 151option in either single or double quotes. Any character (including a 152backslash) may be included by prefixing the character to be included 153with a backslash. The <var>file</var> may itself contain additional 154@<var>file</var> options; any such options will be processed recursively. 155 156 <p><a name="index-g_t_002da-_0040var_007bkeyword_007d-7"></a><br><dt><code>-a </code><var>keyword</var><dd>This option is supported for HP/UX compatibility. The <var>keyword</var> 157argument must be one of the strings ‘<samp><span class="samp">archive</span></samp>’, ‘<samp><span class="samp">shared</span></samp>’, or 158‘<samp><span class="samp">default</span></samp>’. ‘<samp><span class="samp">-aarchive</span></samp>’ is functionally equivalent to 159‘<samp><span class="samp">-Bstatic</span></samp>’, and the other two keywords are functionally equivalent 160to ‘<samp><span class="samp">-Bdynamic</span></samp>’. This option may be used any number of times. 161 162 <p><a name="index-g_t_002d_002daudit-_0040var_007bAUDITLIB_007d-8"></a><br><dt><code>--audit </code><var>AUDITLIB</var><dd>Adds <var>AUDITLIB</var> to the <code>DT_AUDIT</code> entry of the dynamic section. 163<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME 164specified in the library. If specified multiple times <code>DT_AUDIT</code> 165will contain a colon separated list of audit interfaces to use. If the linker 166finds an object with an audit entry while searching for shared libraries, 167it will add a corresponding <code>DT_DEPAUDIT</code> entry in the output file. 168This option is only meaningful on ELF platforms supporting the rtld-audit 169interface. 170 171 <p><a name="index-architectures-9"></a><a name="index-g_t_002dA-_0040var_007barch_007d-10"></a><br><dt><code>-A </code><var>architecture</var><dd><a name="index-g_t_002d_002darchitecture_003d_0040var_007barch_007d-11"></a><dt><code>--architecture=</code><var>architecture</var><dd>In the current release of <samp><span class="command">ld</span></samp>, this option is useful only for the 172Intel 960 family of architectures. In that <samp><span class="command">ld</span></samp> configuration, the 173<var>architecture</var> argument identifies the particular architecture in 174the 960 family, enabling some safeguards and modifying the 175archive-library search path. See <a href="i960.html#i960"><samp><span class="command">ld</span></samp> and the Intel 960 family</a>, for details. 176 177 <p>Future releases of <samp><span class="command">ld</span></samp> may support similar functionality for 178other architecture families. 179 180 <p><a name="index-binary-input-format-12"></a><a name="index-g_t_002db-_0040var_007bformat_007d-13"></a><a name="index-g_t_002d_002dformat_003d_0040var_007bformat_007d-14"></a><a name="index-input-format-15"></a><a name="index-input-format-16"></a><br><dt><code>-b </code><var>input-format</var><dt><code>--format=</code><var>input-format</var><dd><samp><span class="command">ld</span></samp> may be configured to support more than one kind of object 181file. If your <samp><span class="command">ld</span></samp> is configured this way, you can use the 182‘<samp><span class="samp">-b</span></samp>’ option to specify the binary format for input object files 183that follow this option on the command line. Even when <samp><span class="command">ld</span></samp> is 184configured to support alternative object formats, you don't usually need 185to specify this, as <samp><span class="command">ld</span></samp> should be configured to expect as a 186default input format the most usual format on each machine. 187<var>input-format</var> is a text string, the name of a particular format 188supported by the BFD libraries. (You can list the available binary 189formats with ‘<samp><span class="samp">objdump -i</span></samp>’.) 190See <a href="BFD.html#BFD">BFD</a>. 191 192 <p>You may want to use this option if you are linking files with an unusual 193binary format. You can also use ‘<samp><span class="samp">-b</span></samp>’ to switch formats explicitly (when 194linking object files of different formats), by including 195‘<samp><span class="samp">-b </span><var>input-format</var></samp>’ before each group of object files in a 196particular format. 197 198 <p>The default format is taken from the environment variable 199<code>GNUTARGET</code>. 200See <a href="Environment.html#Environment">Environment</a>. 201You can also define the input format from a script, using the command 202<code>TARGET</code>; 203see <a href="Format-Commands.html#Format-Commands">Format Commands</a>. 204 205 <p><a name="index-g_t_002dc-_0040var_007bMRI_002dcmdfile_007d-17"></a><a name="index-g_t_002d_002dmri_002dscript_003d_0040var_007bMRI_002dcmdfile_007d-18"></a><a name="index-compatibility_002c-MRI-19"></a><br><dt><code>-c </code><var>MRI-commandfile</var><dt><code>--mri-script=</code><var>MRI-commandfile</var><dd>For compatibility with linkers produced by MRI, <samp><span class="command">ld</span></samp> accepts script 206files written in an alternate, restricted command language, described in 207<a href="MRI.html#MRI">MRI Compatible Script Files</a>. 208Introduce MRI script files with 209the option ‘<samp><span class="samp">-c</span></samp>’; use the ‘<samp><span class="samp">-T</span></samp>’ option to run linker 210scripts written in the general-purpose <samp><span class="command">ld</span></samp> scripting language. 211If <var>MRI-cmdfile</var> does not exist, <samp><span class="command">ld</span></samp> looks for it in the directories 212specified by any ‘<samp><span class="samp">-L</span></samp>’ options. 213 214 <p><a name="index-common-allocation-20"></a><a name="index-g_t_002dd-21"></a><a name="index-g_t_002ddc-22"></a><a name="index-g_t_002ddp-23"></a><br><dt><code>-d</code><dt><code>-dc</code><dt><code>-dp</code><dd>These three options are equivalent; multiple forms are supported for 215compatibility with other linkers. They assign space to common symbols 216even if a relocatable output file is specified (with ‘<samp><span class="samp">-r</span></samp>’). The 217script command <code>FORCE_COMMON_ALLOCATION</code> has the same effect. 218See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>. 219 220 <p><a name="index-g_t_002d_002ddepaudit-_0040var_007bAUDITLIB_007d-24"></a><a name="index-g_t_002dP-_0040var_007bAUDITLIB_007d-25"></a><br><dt><code>--depaudit </code><var>AUDITLIB</var><dt><code>-P </code><var>AUDITLIB</var><dd>Adds <var>AUDITLIB</var> to the <code>DT_DEPAUDIT</code> entry of the dynamic section. 221<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME 222specified in the library. If specified multiple times <code>DT_DEPAUDIT</code> 223will contain a colon separated list of audit interfaces to use. This 224option is only meaningful on ELF platforms supporting the rtld-audit interface. 225The -P option is provided for Solaris compatibility. 226 227 <p><a name="index-entry-point_002c-from-command-line-26"></a><a name="index-g_t_002de-_0040var_007bentry_007d-27"></a><a name="index-g_t_002d_002dentry_003d_0040var_007bentry_007d-28"></a><br><dt><code>-e </code><var>entry</var><dt><code>--entry=</code><var>entry</var><dd>Use <var>entry</var> as the explicit symbol for beginning execution of your 228program, rather than the default entry point. If there is no symbol 229named <var>entry</var>, the linker will try to parse <var>entry</var> as a number, 230and use that as the entry address (the number will be interpreted in 231base 10; you may use a leading ‘<samp><span class="samp">0x</span></samp>’ for base 16, or a leading 232‘<samp><span class="samp">0</span></samp>’ for base 8). See <a href="Entry-Point.html#Entry-Point">Entry Point</a>, for a discussion of defaults 233and other ways of specifying the entry point. 234 235 <p><a name="index-g_t_002d_002dexclude_002dlibs-29"></a><br><dt><code>--exclude-libs </code><var>lib</var><code>,</code><var>lib</var><code>,...</code><dd>Specifies a list of archive libraries from which symbols should not be automatically 236exported. The library names may be delimited by commas or colons. Specifying 237<code>--exclude-libs ALL</code> excludes symbols in all archive libraries from 238automatic export. This option is available only for the i386 PE targeted 239port of the linker and for ELF targeted ports. For i386 PE, symbols 240explicitly listed in a .def file are still exported, regardless of this 241option. For ELF targeted ports, symbols affected by this option will 242be treated as hidden. 243 244 <p><a name="index-g_t_002d_002dexclude_002dmodules_002dfor_002dimplib-30"></a><br><dt><code>--exclude-modules-for-implib </code><var>module</var><code>,</code><var>module</var><code>,...</code><dd>Specifies a list of object files or archive members, from which symbols 245should not be automatically exported, but which should be copied wholesale 246into the import library being generated during the link. The module names 247may be delimited by commas or colons, and must match exactly the filenames 248used by <samp><span class="command">ld</span></samp> to open the files; for archive members, this is simply 249the member name, but for object files the name listed must include and 250match precisely any path used to specify the input file on the linker's 251command-line. This option is available only for the i386 PE targeted port 252of the linker. Symbols explicitly listed in a .def file are still exported, 253regardless of this option. 254 255 <p><a name="index-dynamic-symbol-table-31"></a><a name="index-g_t_002dE-32"></a><a name="index-g_t_002d_002dexport_002ddynamic-33"></a><a name="index-g_t_002d_002dno_002dexport_002ddynamic-34"></a><br><dt><code>-E</code><dt><code>--export-dynamic</code><dt><code>--no-export-dynamic</code><dd>When creating a dynamically linked executable, using the <samp><span class="option">-E</span></samp> 256option or the <samp><span class="option">--export-dynamic</span></samp> option causes the linker to add 257all symbols to the dynamic symbol table. The dynamic symbol table is the 258set of symbols which are visible from dynamic objects at run time. 259 260 <p>If you do not use either of these options (or use the 261<samp><span class="option">--no-export-dynamic</span></samp> option to restore the default behavior), the 262dynamic symbol table will normally contain only those symbols which are 263referenced by some dynamic object mentioned in the link. 264 265 <p>If you use <code>dlopen</code> to load a dynamic object which needs to refer 266back to the symbols defined by the program, rather than some other 267dynamic object, then you will probably need to use this option when 268linking the program itself. 269 270 <p>You can also use the dynamic list to control what symbols should 271be added to the dynamic symbol table if the output format supports it. 272See the description of ‘<samp><span class="samp">--dynamic-list</span></samp>’. 273 274 <p>Note that this option is specific to ELF targeted ports. PE targets 275support a similar function to export all symbols from a DLL or EXE; see 276the description of ‘<samp><span class="samp">--export-all-symbols</span></samp>’ below. 277 278 <p><a name="index-big_002dendian-objects-35"></a><a name="index-endianness-36"></a><a name="index-g_t_002dEB-37"></a><br><dt><code>-EB</code><dd>Link big-endian objects. This affects the default output format. 279 280 <p><a name="index-little_002dendian-objects-38"></a><a name="index-g_t_002dEL-39"></a><br><dt><code>-EL</code><dd>Link little-endian objects. This affects the default output format. 281 282 <p><a name="index-g_t_002df-_0040var_007bname_007d-40"></a><a name="index-g_t_002d_002dauxiliary_003d_0040var_007bname_007d-41"></a><br><dt><code>-f </code><var>name</var><dt><code>--auxiliary=</code><var>name</var><dd>When creating an ELF shared object, set the internal DT_AUXILIARY field 283to the specified name. This tells the dynamic linker that the symbol 284table of the shared object should be used as an auxiliary filter on the 285symbol table of the shared object <var>name</var>. 286 287 <p>If you later link a program against this filter object, then, when you 288run the program, the dynamic linker will see the DT_AUXILIARY field. If 289the dynamic linker resolves any symbols from the filter object, it will 290first check whether there is a definition in the shared object 291<var>name</var>. If there is one, it will be used instead of the definition 292in the filter object. The shared object <var>name</var> need not exist. 293Thus the shared object <var>name</var> may be used to provide an alternative 294implementation of certain functions, perhaps for debugging or for 295machine specific performance. 296 297 <p>This option may be specified more than once. The DT_AUXILIARY entries 298will be created in the order in which they appear on the command line. 299 300 <p><a name="index-g_t_002dF-_0040var_007bname_007d-42"></a><a name="index-g_t_002d_002dfilter_003d_0040var_007bname_007d-43"></a><br><dt><code>-F </code><var>name</var><dt><code>--filter=</code><var>name</var><dd>When creating an ELF shared object, set the internal DT_FILTER field to 301the specified name. This tells the dynamic linker that the symbol table 302of the shared object which is being created should be used as a filter 303on the symbol table of the shared object <var>name</var>. 304 305 <p>If you later link a program against this filter object, then, when you 306run the program, the dynamic linker will see the DT_FILTER field. The 307dynamic linker will resolve symbols according to the symbol table of the 308filter object as usual, but it will actually link to the definitions 309found in the shared object <var>name</var>. Thus the filter object can be 310used to select a subset of the symbols provided by the object 311<var>name</var>. 312 313 <p>Some older linkers used the <samp><span class="option">-F</span></samp> option throughout a compilation 314toolchain for specifying object-file format for both input and output 315object files. 316The <span class="sc">gnu</span> linker uses other mechanisms for this purpose: the 317<samp><span class="option">-b</span></samp>, <samp><span class="option">--format</span></samp>, <samp><span class="option">--oformat</span></samp> options, the 318<code>TARGET</code> command in linker scripts, and the <code>GNUTARGET</code> 319environment variable. 320The <span class="sc">gnu</span> linker will ignore the <samp><span class="option">-F</span></samp> option when not 321creating an ELF shared object. 322 323 <p><a name="index-finalization-function-44"></a><a name="index-g_t_002dfini_003d_0040var_007bname_007d-45"></a><br><dt><code>-fini=</code><var>name</var><dd>When creating an ELF executable or shared object, call NAME when the 324executable or shared object is unloaded, by setting DT_FINI to the 325address of the function. By default, the linker uses <code>_fini</code> as 326the function to call. 327 328 <p><a name="index-g_t_002dg-46"></a><br><dt><code>-g</code><dd>Ignored. Provided for compatibility with other tools. 329 330 <p><a name="index-g_t_002dG-_0040var_007bvalue_007d-47"></a><a name="index-g_t_002d_002dgpsize_003d_0040var_007bvalue_007d-48"></a><a name="index-object-size-49"></a><br><dt><code>-G </code><var>value</var><dt><code>--gpsize=</code><var>value</var><dd>Set the maximum size of objects to be optimized using the GP register to 331<var>size</var>. This is only meaningful for object file formats such as 332MIPS ECOFF which supports putting large and small objects into different 333sections. This is ignored for other object file formats. 334 335 <p><a name="index-runtime-library-name-50"></a><a name="index-g_t_002dh-_0040var_007bname_007d-51"></a><a name="index-g_t_002dsoname_003d_0040var_007bname_007d-52"></a><br><dt><code>-h </code><var>name</var><dt><code>-soname=</code><var>name</var><dd>When creating an ELF shared object, set the internal DT_SONAME field to 336the specified name. When an executable is linked with a shared object 337which has a DT_SONAME field, then when the executable is run the dynamic 338linker will attempt to load the shared object specified by the DT_SONAME 339field rather than the using the file name given to the linker. 340 341 <p><a name="index-g_t_002di-53"></a><a name="index-incremental-link-54"></a><br><dt><code>-i</code><dd>Perform an incremental link (same as option ‘<samp><span class="samp">-r</span></samp>’). 342 343 <p><a name="index-initialization-function-55"></a><a name="index-g_t_002dinit_003d_0040var_007bname_007d-56"></a><br><dt><code>-init=</code><var>name</var><dd>When creating an ELF executable or shared object, call NAME when the 344executable or shared object is loaded, by setting DT_INIT to the address 345of the function. By default, the linker uses <code>_init</code> as the 346function to call. 347 348 <p><a name="index-archive-files_002c-from-cmd-line-57"></a><a name="index-g_t_002dl-_0040var_007bnamespec_007d-58"></a><a name="index-g_t_002d_002dlibrary_003d_0040var_007bnamespec_007d-59"></a><br><dt><code>-l </code><var>namespec</var><dt><code>--library=</code><var>namespec</var><dd>Add the archive or object file specified by <var>namespec</var> to the 349list of files to link. This option may be used any number of times. 350If <var>namespec</var> is of the form <samp><span class="file">:</span><var>filename</var></samp>, <samp><span class="command">ld</span></samp> 351will search the library path for a file called <var>filename</var>, otherwise it 352will search the library path for a file called <samp><span class="file">lib</span><var>namespec</var><span class="file">.a</span></samp>. 353 354 <p>On systems which support shared libraries, <samp><span class="command">ld</span></samp> may also search for 355files other than <samp><span class="file">lib</span><var>namespec</var><span class="file">.a</span></samp>. Specifically, on ELF 356and SunOS systems, <samp><span class="command">ld</span></samp> will search a directory for a library 357called <samp><span class="file">lib</span><var>namespec</var><span class="file">.so</span></samp> before searching for one called 358<samp><span class="file">lib</span><var>namespec</var><span class="file">.a</span></samp>. (By convention, a <code>.so</code> extension 359indicates a shared library.) Note that this behavior does not apply 360to <samp><span class="file">:</span><var>filename</var></samp>, which always specifies a file called 361<var>filename</var>. 362 363 <p>The linker will search an archive only once, at the location where it is 364specified on the command line. If the archive defines a symbol which 365was undefined in some object which appeared before the archive on the 366command line, the linker will include the appropriate file(s) from the 367archive. However, an undefined symbol in an object appearing later on 368the command line will not cause the linker to search the archive again. 369 370 <p>See the <samp><span class="option">-(</span></samp> option for a way to force the linker to search 371archives multiple times. 372 373 <p>You may list the same archive multiple times on the command line. 374 375 <p>This type of archive searching is standard for Unix linkers. However, 376if you are using <samp><span class="command">ld</span></samp> on AIX, note that it is different from the 377behaviour of the AIX linker. 378 379 <p><a name="index-search-directory_002c-from-cmd-line-60"></a><a name="index-g_t_002dL-_0040var_007bdir_007d-61"></a><a name="index-g_t_002d_002dlibrary_002dpath_003d_0040var_007bdir_007d-62"></a><br><dt><code>-L </code><var>searchdir</var><dt><code>--library-path=</code><var>searchdir</var><dd>Add path <var>searchdir</var> to the list of paths that <samp><span class="command">ld</span></samp> will search 380for archive libraries and <samp><span class="command">ld</span></samp> control scripts. You may use this 381option any number of times. The directories are searched in the order 382in which they are specified on the command line. Directories specified 383on the command line are searched before the default directories. All 384<samp><span class="option">-L</span></samp> options apply to all <samp><span class="option">-l</span></samp> options, regardless of the 385order in which the options appear. <samp><span class="option">-L</span></samp> options do not affect 386how <samp><span class="command">ld</span></samp> searches for a linker script unless <samp><span class="option">-T</span></samp> 387option is specified. 388 389 <p>If <var>searchdir</var> begins with <code>=</code>, then the <code>=</code> will be replaced 390by the <dfn>sysroot prefix</dfn>, a path specified when the linker is configured. 391 392 <p>The default set of paths searched (without being specified with 393‘<samp><span class="samp">-L</span></samp>’) depends on which emulation mode <samp><span class="command">ld</span></samp> is using, and in 394some cases also on how it was configured. See <a href="Environment.html#Environment">Environment</a>. 395 396 <p>The paths can also be specified in a link script with the 397<code>SEARCH_DIR</code> command. Directories specified this way are searched 398at the point in which the linker script appears in the command line. 399 400 <p><a name="index-emulation-63"></a><a name="index-g_t_002dm-_0040var_007bemulation_007d-64"></a><br><dt><code>-m </code><var>emulation</var><dd>Emulate the <var>emulation</var> linker. You can list the available 401emulations with the ‘<samp><span class="samp">--verbose</span></samp>’ or ‘<samp><span class="samp">-V</span></samp>’ options. 402 403 <p>If the ‘<samp><span class="samp">-m</span></samp>’ option is not used, the emulation is taken from the 404<code>LDEMULATION</code> environment variable, if that is defined. 405 406 <p>Otherwise, the default emulation depends upon how the linker was 407configured. 408 409 <p><a name="index-link-map-65"></a><a name="index-g_t_002dM-66"></a><a name="index-g_t_002d_002dprint_002dmap-67"></a><br><dt><code>-M</code><dt><code>--print-map</code><dd>Print a link map to the standard output. A link map provides 410information about the link, including the following: 411 412 <ul> 413<li>Where object files are mapped into memory. 414<li>How common symbols are allocated. 415<li>All archive members included in the link, with a mention of the symbol 416which caused the archive member to be brought in. 417<li>The values assigned to symbols. 418 419 <p>Note - symbols whose values are computed by an expression which 420involves a reference to a previous value of the same symbol may not 421have correct result displayed in the link map. This is because the 422linker discards intermediate results and only retains the final value 423of an expression. Under such circumstances the linker will display 424the final value enclosed by square brackets. Thus for example a 425linker script containing: 426 427 <pre class="smallexample"> foo = 1 428 foo = foo * 4 429 foo = foo + 8 430</pre> 431 <p>will produce the following output in the link map if the <samp><span class="option">-M</span></samp> 432option is used: 433 434 <pre class="smallexample"> 0x00000001 foo = 0x1 435 [0x0000000c] foo = (foo * 0x4) 436 [0x0000000c] foo = (foo + 0x8) 437</pre> 438 <p>See <a href="Expressions.html#Expressions">Expressions</a> for more information about expressions in linker 439scripts. 440</ul> 441 442 <p><a name="index-g_t_002dn-68"></a><a name="index-read_002donly-text-69"></a><a name="index-NMAGIC-70"></a><a name="index-g_t_002d_002dnmagic-71"></a><br><dt><code>-n</code><dt><code>--nmagic</code><dd>Turn off page alignment of sections, and disable linking against shared 443libraries. If the output format supports Unix style magic numbers, 444mark the output as <code>NMAGIC</code>. 445 446 <p><a name="index-g_t_002dN-72"></a><a name="index-g_t_002d_002domagic-73"></a><a name="index-read_002fwrite-from-cmd-line-74"></a><a name="index-OMAGIC-75"></a><br><dt><code>-N</code><dt><code>--omagic</code><dd>Set the text and data sections to be readable and writable. Also, do 447not page-align the data segment, and disable linking against shared 448libraries. If the output format supports Unix style magic numbers, 449mark the output as <code>OMAGIC</code>. Note: Although a writable text section 450is allowed for PE-COFF targets, it does not conform to the format 451specification published by Microsoft. 452 453 <p><a name="index-g_t_002d_002dno_002domagic-76"></a><a name="index-OMAGIC-77"></a><br><dt><code>--no-omagic</code><dd>This option negates most of the effects of the <samp><span class="option">-N</span></samp> option. It 454sets the text section to be read-only, and forces the data segment to 455be page-aligned. Note - this option does not enable linking against 456shared libraries. Use <samp><span class="option">-Bdynamic</span></samp> for this. 457 458 <p><a name="index-g_t_002do-_0040var_007boutput_007d-78"></a><a name="index-g_t_002d_002doutput_003d_0040var_007boutput_007d-79"></a><a name="index-naming-the-output-file-80"></a><br><dt><code>-o </code><var>output</var><dt><code>--output=</code><var>output</var><dd>Use <var>output</var> as the name for the program produced by <samp><span class="command">ld</span></samp>; if this 459option is not specified, the name <samp><span class="file">a.out</span></samp> is used by default. The 460script command <code>OUTPUT</code> can also specify the output file name. 461 462 <p><a name="index-g_t_002dO-_0040var_007blevel_007d-81"></a><a name="index-generating-optimized-output-82"></a><br><dt><code>-O </code><var>level</var><dd>If <var>level</var> is a numeric values greater than zero <samp><span class="command">ld</span></samp> optimizes 463the output. This might take significantly longer and therefore probably 464should only be enabled for the final binary. At the moment this 465option only affects ELF shared library generation. Future releases of 466the linker may make more use of this option. Also currently there is 467no difference in the linker's behaviour for different non-zero values 468of this option. Again this may change with future releases. 469 470 <p><a name="index-g_t_002dq-83"></a><a name="index-g_t_002d_002demit_002drelocs-84"></a><a name="index-retain-relocations-in-final-executable-85"></a><br><dt><code>-q</code><dt><code>--emit-relocs</code><dd>Leave relocation sections and contents in fully linked executables. 471Post link analysis and optimization tools may need this information in 472order to perform correct modifications of executables. This results 473in larger executables. 474 475 <p>This option is currently only supported on ELF platforms. 476 477 <p><a name="index-g_t_002d_002dforce_002ddynamic-86"></a><a name="index-forcing-the-creation-of-dynamic-sections-87"></a><br><dt><code>--force-dynamic</code><dd>Force the output file to have dynamic sections. This option is specific 478to VxWorks targets. 479 480 <p><a name="index-partial-link-88"></a><a name="index-relocatable-output-89"></a><a name="index-g_t_002dr-90"></a><a name="index-g_t_002d_002drelocatable-91"></a><br><dt><code>-r</code><dt><code>--relocatable</code><dd>Generate relocatable output—i.e., generate an output file that can in 481turn serve as input to <samp><span class="command">ld</span></samp>. This is often called <dfn>partial 482linking</dfn>. As a side effect, in environments that support standard Unix 483magic numbers, this option also sets the output file's magic number to 484<code>OMAGIC</code>. 485<!-- ; see @option{-N}. --> 486If this option is not specified, an absolute file is produced. When 487linking C++ programs, this option <em>will not</em> resolve references to 488constructors; to do that, use ‘<samp><span class="samp">-Ur</span></samp>’. 489 490 <p>When an input file does not have the same format as the output file, 491partial linking is only supported if that input file does not contain any 492relocations. Different output formats can have further restrictions; for 493example some <code>a.out</code>-based formats do not support partial linking 494with input files in other formats at all. 495 496 <p>This option does the same thing as ‘<samp><span class="samp">-i</span></samp>’. 497 498 <p><a name="index-g_t_002dR-_0040var_007bfile_007d-92"></a><a name="index-g_t_002d_002djust_002dsymbols_003d_0040var_007bfile_007d-93"></a><a name="index-symbol_002donly-input-94"></a><br><dt><code>-R </code><var>filename</var><dt><code>--just-symbols=</code><var>filename</var><dd>Read symbol names and their addresses from <var>filename</var>, but do not 499relocate it or include it in the output. This allows your output file 500to refer symbolically to absolute locations of memory defined in other 501programs. You may use this option more than once. 502 503 <p>For compatibility with other ELF linkers, if the <samp><span class="option">-R</span></samp> option is 504followed by a directory name, rather than a file name, it is treated as 505the <samp><span class="option">-rpath</span></samp> option. 506 507 <p><a name="index-g_t_002ds-95"></a><a name="index-g_t_002d_002dstrip_002dall-96"></a><a name="index-strip-all-symbols-97"></a><br><dt><code>-s</code><dt><code>--strip-all</code><dd>Omit all symbol information from the output file. 508 509 <p><a name="index-g_t_002dS-98"></a><a name="index-g_t_002d_002dstrip_002ddebug-99"></a><a name="index-strip-debugger-symbols-100"></a><br><dt><code>-S</code><dt><code>--strip-debug</code><dd>Omit debugger symbol information (but not all symbols) from the output file. 510 511 <p><a name="index-g_t_002dt-101"></a><a name="index-g_t_002d_002dtrace-102"></a><a name="index-input-files_002c-displaying-103"></a><br><dt><code>-t</code><dt><code>--trace</code><dd>Print the names of the input files as <samp><span class="command">ld</span></samp> processes them. 512 513 <p><a name="index-g_t_002dT-_0040var_007bscript_007d-104"></a><a name="index-g_t_002d_002dscript_003d_0040var_007bscript_007d-105"></a><a name="index-script-files-106"></a><br><dt><code>-T </code><var>scriptfile</var><dt><code>--script=</code><var>scriptfile</var><dd>Use <var>scriptfile</var> as the linker script. This script replaces 514<samp><span class="command">ld</span></samp>'s default linker script (rather than adding to it), so 515<var>commandfile</var> must specify everything necessary to describe the 516output file. See <a href="Scripts.html#Scripts">Scripts</a>. If <var>scriptfile</var> does not exist in 517the current directory, <code>ld</code> looks for it in the directories 518specified by any preceding ‘<samp><span class="samp">-L</span></samp>’ options. Multiple ‘<samp><span class="samp">-T</span></samp>’ 519options accumulate. 520 521 <p><a name="index-g_t_002ddT-_0040var_007bscript_007d-107"></a><a name="index-g_t_002d_002ddefault_002dscript_003d_0040var_007bscript_007d-108"></a><a name="index-script-files-109"></a><br><dt><code>-dT </code><var>scriptfile</var><dt><code>--default-script=</code><var>scriptfile</var><dd>Use <var>scriptfile</var> as the default linker script. See <a href="Scripts.html#Scripts">Scripts</a>. 522 523 <p>This option is similar to the <samp><span class="option">--script</span></samp> option except that 524processing of the script is delayed until after the rest of the 525command line has been processed. This allows options placed after the 526<samp><span class="option">--default-script</span></samp> option on the command line to affect the 527behaviour of the linker script, which can be important when the linker 528command line cannot be directly controlled by the user. (eg because 529the command line is being constructed by another tool, such as 530‘<samp><span class="samp">gcc</span></samp>’). 531 532 <p><a name="index-g_t_002du-_0040var_007bsymbol_007d-110"></a><a name="index-g_t_002d_002dundefined_003d_0040var_007bsymbol_007d-111"></a><a name="index-undefined-symbol-112"></a><br><dt><code>-u </code><var>symbol</var><dt><code>--undefined=</code><var>symbol</var><dd>Force <var>symbol</var> to be entered in the output file as an undefined 533symbol. Doing this may, for example, trigger linking of additional 534modules from standard libraries. ‘<samp><span class="samp">-u</span></samp>’ may be repeated with 535different option arguments to enter additional undefined symbols. This 536option is equivalent to the <code>EXTERN</code> linker script command. 537 538 <p><a name="index-g_t_002dUr-113"></a><a name="index-constructors-114"></a><br><dt><code>-Ur</code><dd>For anything other than C++ programs, this option is equivalent to 539‘<samp><span class="samp">-r</span></samp>’: it generates relocatable output—i.e., an output file that can in 540turn serve as input to <samp><span class="command">ld</span></samp>. When linking C++ programs, ‘<samp><span class="samp">-Ur</span></samp>’ 541<em>does</em> resolve references to constructors, unlike ‘<samp><span class="samp">-r</span></samp>’. 542It does not work to use ‘<samp><span class="samp">-Ur</span></samp>’ on files that were themselves linked 543with ‘<samp><span class="samp">-Ur</span></samp>’; once the constructor table has been built, it cannot 544be added to. Use ‘<samp><span class="samp">-Ur</span></samp>’ only for the last partial link, and 545‘<samp><span class="samp">-r</span></samp>’ for the others. 546 547 <p><a name="index-g_t_002d_002dunique_005b_003d_0040var_007bSECTION_007d_005d-115"></a><br><dt><code>--unique[=</code><var>SECTION</var><code>]</code><dd>Creates a separate output section for every input section matching 548<var>SECTION</var>, or if the optional wildcard <var>SECTION</var> argument is 549missing, for every orphan input section. An orphan section is one not 550specifically mentioned in a linker script. You may use this option 551multiple times on the command line; It prevents the normal merging of 552input sections with the same name, overriding output section assignments 553in a linker script. 554 555 <p><a name="index-g_t_002dv-116"></a><a name="index-g_t_002dV-117"></a><a name="index-g_t_002d_002dversion-118"></a><a name="index-version-119"></a><br><dt><code>-v</code><dt><code>--version</code><dt><code>-V</code><dd>Display the version number for <samp><span class="command">ld</span></samp>. The <samp><span class="option">-V</span></samp> option also 556lists the supported emulations. 557 558 <p><a name="index-g_t_002dx-120"></a><a name="index-g_t_002d_002ddiscard_002dall-121"></a><a name="index-deleting-local-symbols-122"></a><br><dt><code>-x</code><dt><code>--discard-all</code><dd>Delete all local symbols. 559 560 <p><a name="index-g_t_002dX-123"></a><a name="index-g_t_002d_002ddiscard_002dlocals-124"></a><a name="index-local-symbols_002c-deleting-125"></a><br><dt><code>-X</code><dt><code>--discard-locals</code><dd>Delete all temporary local symbols. (These symbols start with 561system-specific local label prefixes, typically ‘<samp><span class="samp">.L</span></samp>’ for ELF systems 562or ‘<samp><span class="samp">L</span></samp>’ for traditional a.out systems.) 563 564 <p><a name="index-g_t_002dy-_0040var_007bsymbol_007d-126"></a><a name="index-g_t_002d_002dtrace_002dsymbol_003d_0040var_007bsymbol_007d-127"></a><a name="index-symbol-tracing-128"></a><br><dt><code>-y </code><var>symbol</var><dt><code>--trace-symbol=</code><var>symbol</var><dd>Print the name of each linked file in which <var>symbol</var> appears. This 565option may be given any number of times. On many systems it is necessary 566to prepend an underscore. 567 568 <p>This option is useful when you have an undefined symbol in your link but 569don't know where the reference is coming from. 570 571 <p><a name="index-g_t_002dY-_0040var_007bpath_007d-129"></a><br><dt><code>-Y </code><var>path</var><dd>Add <var>path</var> to the default library search path. This option exists 572for Solaris compatibility. 573 574 <p><a name="index-g_t_002dz-_0040var_007bkeyword_007d-130"></a><br><dt><code>-z </code><var>keyword</var><dd>The recognized keywords are: 575 <dl> 576<dt>‘<samp><span class="samp">combreloc</span></samp>’<dd>Combines multiple reloc sections and sorts them to make dynamic symbol 577lookup caching possible. 578 579 <br><dt>‘<samp><span class="samp">defs</span></samp>’<dd>Disallows undefined symbols in object files. Undefined symbols in 580shared libraries are still allowed. 581 582 <br><dt>‘<samp><span class="samp">execstack</span></samp>’<dd>Marks the object as requiring executable stack. 583 584 <br><dt>‘<samp><span class="samp">initfirst</span></samp>’<dd>This option is only meaningful when building a shared object. 585It marks the object so that its runtime initialization will occur 586before the runtime initialization of any other objects brought into 587the process at the same time. Similarly the runtime finalization of 588the object will occur after the runtime finalization of any other 589objects. 590 591 <br><dt>‘<samp><span class="samp">interpose</span></samp>’<dd>Marks the object that its symbol table interposes before all symbols 592but the primary executable. 593 594 <br><dt>‘<samp><span class="samp">lazy</span></samp>’<dd>When generating an executable or shared library, mark it to tell the 595dynamic linker to defer function call resolution to the point when 596the function is called (lazy binding), rather than at load time. 597Lazy binding is the default. 598 599 <br><dt>‘<samp><span class="samp">loadfltr</span></samp>’<dd>Marks the object that its filters be processed immediately at 600runtime. 601 602 <br><dt>‘<samp><span class="samp">muldefs</span></samp>’<dd>Allows multiple definitions. 603 604 <br><dt>‘<samp><span class="samp">nocombreloc</span></samp>’<dd>Disables multiple reloc sections combining. 605 606 <br><dt>‘<samp><span class="samp">nocopyreloc</span></samp>’<dd>Disables production of copy relocs. 607 608 <br><dt>‘<samp><span class="samp">nodefaultlib</span></samp>’<dd>Marks the object that the search for dependencies of this object will 609ignore any default library search paths. 610 611 <br><dt>‘<samp><span class="samp">nodelete</span></samp>’<dd>Marks the object shouldn't be unloaded at runtime. 612 613 <br><dt>‘<samp><span class="samp">nodlopen</span></samp>’<dd>Marks the object not available to <code>dlopen</code>. 614 615 <br><dt>‘<samp><span class="samp">nodump</span></samp>’<dd>Marks the object can not be dumped by <code>dldump</code>. 616 617 <br><dt>‘<samp><span class="samp">noexecstack</span></samp>’<dd>Marks the object as not requiring executable stack. 618 619 <br><dt>‘<samp><span class="samp">norelro</span></samp>’<dd>Don't create an ELF <code>PT_GNU_RELRO</code> segment header in the object. 620 621 <br><dt>‘<samp><span class="samp">now</span></samp>’<dd>When generating an executable or shared library, mark it to tell the 622dynamic linker to resolve all symbols when the program is started, or 623when the shared library is linked to using dlopen, instead of 624deferring function call resolution to the point when the function is 625first called. 626 627 <br><dt>‘<samp><span class="samp">origin</span></samp>’<dd>Marks the object may contain $ORIGIN. 628 629 <br><dt>‘<samp><span class="samp">relro</span></samp>’<dd>Create an ELF <code>PT_GNU_RELRO</code> segment header in the object. 630 631 <br><dt>‘<samp><span class="samp">max-page-size=</span><var>value</var></samp>’<dd>Set the emulation maximum page size to <var>value</var>. 632 633 <br><dt>‘<samp><span class="samp">common-page-size=</span><var>value</var></samp>’<dd>Set the emulation common page size to <var>value</var>. 634 635 </dl> 636 637 <p>Other keywords are ignored for Solaris compatibility. 638 639 <p><a name="index-g_t_002d_0028-131"></a><a name="index-groups-of-archives-132"></a><br><dt><code>-( </code><var>archives</var><code> -)</code><dt><code>--start-group </code><var>archives</var><code> --end-group</code><dd>The <var>archives</var> should be a list of archive files. They may be 640either explicit file names, or ‘<samp><span class="samp">-l</span></samp>’ options. 641 642 <p>The specified archives are searched repeatedly until no new undefined 643references are created. Normally, an archive is searched only once in 644the order that it is specified on the command line. If a symbol in that 645archive is needed to resolve an undefined symbol referred to by an 646object in an archive that appears later on the command line, the linker 647would not be able to resolve that reference. By grouping the archives, 648they all be searched repeatedly until all possible references are 649resolved. 650 651 <p>Using this option has a significant performance cost. It is best to use 652it only when there are unavoidable circular references between two or 653more archives. 654 655 <p><a name="index-g_t_002d_002daccept_002dunknown_002dinput_002darch-133"></a><a name="index-g_t_002d_002dno_002daccept_002dunknown_002dinput_002darch-134"></a><br><dt><code>--accept-unknown-input-arch</code><dt><code>--no-accept-unknown-input-arch</code><dd>Tells the linker to accept input files whose architecture cannot be 656recognised. The assumption is that the user knows what they are doing 657and deliberately wants to link in these unknown input files. This was 658the default behaviour of the linker, before release 2.14. The default 659behaviour from release 2.14 onwards is to reject such input files, and 660so the ‘<samp><span class="samp">--accept-unknown-input-arch</span></samp>’ option has been added to 661restore the old behaviour. 662 663 <p><a name="index-g_t_002d_002das_002dneeded-135"></a><a name="index-g_t_002d_002dno_002das_002dneeded-136"></a><br><dt><code>--as-needed</code><dt><code>--no-as-needed</code><dd>This option affects ELF DT_NEEDED tags for dynamic libraries mentioned 664on the command line after the <samp><span class="option">--as-needed</span></samp> option. Normally 665the linker will add a DT_NEEDED tag for each dynamic library mentioned 666on the command line, regardless of whether the library is actually 667needed or not. <samp><span class="option">--as-needed</span></samp> causes a DT_NEEDED tag to only be 668emitted for a library that satisfies an undefined symbol reference 669from a regular object file or, if the library is not found in the 670DT_NEEDED lists of other libraries linked up to that point, an 671undefined symbol reference from another dynamic library. 672<samp><span class="option">--no-as-needed</span></samp> restores the default behaviour. 673 674 <p><a name="index-g_t_002d_002dadd_002dneeded-137"></a><a name="index-g_t_002d_002dno_002dadd_002dneeded-138"></a><br><dt><code>--add-needed</code><dt><code>--no-add-needed</code><dd>These two options have been deprecated because of the similarity of 675their names to the <samp><span class="option">--as-needed</span></samp> and <samp><span class="option">--no-as-needed</span></samp> 676options. They have been replaced by <samp><span class="option">--copy-dt-needed-entries</span></samp> 677and <samp><span class="option">--no-copy-dt-needed-entries</span></samp>. 678 679 <p><a name="index-g_t_002dassert-_0040var_007bkeyword_007d-139"></a><br><dt><code>-assert </code><var>keyword</var><dd>This option is ignored for SunOS compatibility. 680 681 <p><a name="index-g_t_002dBdynamic-140"></a><a name="index-g_t_002ddy-141"></a><a name="index-g_t_002dcall_005fshared-142"></a><br><dt><code>-Bdynamic</code><dt><code>-dy</code><dt><code>-call_shared</code><dd>Link against dynamic libraries. This is only meaningful on platforms 682for which shared libraries are supported. This option is normally the 683default on such platforms. The different variants of this option are 684for compatibility with various systems. You may use this option 685multiple times on the command line: it affects library searching for 686<samp><span class="option">-l</span></samp> options which follow it. 687 688 <p><a name="index-g_t_002dBgroup-143"></a><br><dt><code>-Bgroup</code><dd>Set the <code>DF_1_GROUP</code> flag in the <code>DT_FLAGS_1</code> entry in the dynamic 689section. This causes the runtime linker to handle lookups in this 690object and its dependencies to be performed only inside the group. 691<samp><span class="option">--unresolved-symbols=report-all</span></samp> is implied. This option is 692only meaningful on ELF platforms which support shared libraries. 693 694 <p><a name="index-g_t_002dBstatic-144"></a><a name="index-g_t_002ddn-145"></a><a name="index-g_t_002dnon_005fshared-146"></a><a name="index-g_t_002dstatic-147"></a><br><dt><code>-Bstatic</code><dt><code>-dn</code><dt><code>-non_shared</code><dt><code>-static</code><dd>Do not link against shared libraries. This is only meaningful on 695platforms for which shared libraries are supported. The different 696variants of this option are for compatibility with various systems. You 697may use this option multiple times on the command line: it affects 698library searching for <samp><span class="option">-l</span></samp> options which follow it. This 699option also implies <samp><span class="option">--unresolved-symbols=report-all</span></samp>. This 700option can be used with <samp><span class="option">-shared</span></samp>. Doing so means that a 701shared library is being created but that all of the library's external 702references must be resolved by pulling in entries from static 703libraries. 704 705 <p><a name="index-g_t_002dBsymbolic-148"></a><br><dt><code>-Bsymbolic</code><dd>When creating a shared library, bind references to global symbols to the 706definition within the shared library, if any. Normally, it is possible 707for a program linked against a shared library to override the definition 708within the shared library. This option is only meaningful on ELF 709platforms which support shared libraries. 710 711 <p><a name="index-g_t_002dBsymbolic_002dfunctions-149"></a><br><dt><code>-Bsymbolic-functions</code><dd>When creating a shared library, bind references to global function 712symbols to the definition within the shared library, if any. 713This option is only meaningful on ELF platforms which support shared 714libraries. 715 716 <p><a name="index-g_t_002d_002ddynamic_002dlist_003d_0040var_007bdynamic_002dlist_002dfile_007d-150"></a><br><dt><code>--dynamic-list=</code><var>dynamic-list-file</var><dd>Specify the name of a dynamic list file to the linker. This is 717typically used when creating shared libraries to specify a list of 718global symbols whose references shouldn't be bound to the definition 719within the shared library, or creating dynamically linked executables 720to specify a list of symbols which should be added to the symbol table 721in the executable. This option is only meaningful on ELF platforms 722which support shared libraries. 723 724 <p>The format of the dynamic list is the same as the version node without 725scope and node name. See <a href="VERSION.html#VERSION">VERSION</a> for more information. 726 727 <p><a name="index-g_t_002d_002ddynamic_002dlist_002ddata-151"></a><br><dt><code>--dynamic-list-data</code><dd>Include all global data symbols to the dynamic list. 728 729 <p><a name="index-g_t_002d_002ddynamic_002dlist_002dcpp_002dnew-152"></a><br><dt><code>--dynamic-list-cpp-new</code><dd>Provide the builtin dynamic list for C++ operator new and delete. It 730is mainly useful for building shared libstdc++. 731 732 <p><a name="index-g_t_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo-153"></a><br><dt><code>--dynamic-list-cpp-typeinfo</code><dd>Provide the builtin dynamic list for C++ runtime type identification. 733 734 <p><a name="index-g_t_002d_002dcheck_002dsections-154"></a><a name="index-g_t_002d_002dno_002dcheck_002dsections-155"></a><br><dt><code>--check-sections</code><dt><code>--no-check-sections</code><dd>Asks the linker <em>not</em> to check section addresses after they have 735been assigned to see if there are any overlaps. Normally the linker will 736perform this check, and if it finds any overlaps it will produce 737suitable error messages. The linker does know about, and does make 738allowances for sections in overlays. The default behaviour can be 739restored by using the command line switch <samp><span class="option">--check-sections</span></samp>. 740Section overlap is not usually checked for relocatable links. You can 741force checking in that case by using the <samp><span class="option">--check-sections</span></samp> 742option. 743 744 <p><a name="index-g_t_002d_002dcopy_002ddt_002dneeded_002dentries-156"></a><a name="index-g_t_002d_002dno_002dcopy_002ddt_002dneeded_002dentries-157"></a><br><dt><code>--copy-dt-needed-entries</code><dt><code>--no-copy-dt-needed-entries</code><dd>This option affects the treatment of dynamic libraries referred to 745by DT_NEEDED tags <em>inside</em> ELF dynamic libraries mentioned on the 746command line. Normally the linker won't add a DT_NEEDED tag to the 747output binary for each library mentioned in a DT_NEEDED tag in an 748input dynamic library. With <samp><span class="option">--copy-dt-needed-entries</span></samp> 749specified on the command line however any dynamic libraries that 750follow it will have their DT_NEEDED entries added. The default 751behaviour can be restored with <samp><span class="option">--no-copy-dt-needed-entries</span></samp>. 752 753 <p>This option also has an effect on the resolution of symbols in dynamic 754libraries. With <samp><span class="option">--copy-dt-needed-entries</span></samp> dynamic libraries 755mentioned on the command line will be recursively searched, following 756their DT_NEEDED tags to other libraries, in order to resolve symbols 757required by the output binary. With the default setting however 758the searching of dynamic libraries that follow it will stop with the 759dynamic library itself. No DT_NEEDED links will be traversed to resolve 760symbols. 761 762 <p><a name="index-cross-reference-table-158"></a><a name="index-g_t_002d_002dcref-159"></a><br><dt><code>--cref</code><dd>Output a cross reference table. If a linker map file is being 763generated, the cross reference table is printed to the map file. 764Otherwise, it is printed on the standard output. 765 766 <p>The format of the table is intentionally simple, so that it may be 767easily processed by a script if necessary. The symbols are printed out, 768sorted by name. For each symbol, a list of file names is given. If the 769symbol is defined, the first file listed is the location of the 770definition. The remaining files contain references to the symbol. 771 772 <p><a name="index-common-allocation-160"></a><a name="index-g_t_002d_002dno_002ddefine_002dcommon-161"></a><br><dt><code>--no-define-common</code><dd>This option inhibits the assignment of addresses to common symbols. 773The script command <code>INHIBIT_COMMON_ALLOCATION</code> has the same effect. 774See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>. 775 776 <p>The ‘<samp><span class="samp">--no-define-common</span></samp>’ option allows decoupling 777the decision to assign addresses to Common symbols from the choice 778of the output file type; otherwise a non-Relocatable output type 779forces assigning addresses to Common symbols. 780Using ‘<samp><span class="samp">--no-define-common</span></samp>’ allows Common symbols that are referenced 781from a shared library to be assigned addresses only in the main program. 782This eliminates the unused duplicate space in the shared library, 783and also prevents any possible confusion over resolving to the wrong 784duplicate when there are many dynamic modules with specialized search 785paths for runtime symbol resolution. 786 787 <p><a name="index-symbols_002c-from-command-line-162"></a><a name="index-g_t_002d_002ddefsym_003d_0040var_007bsymbol_007d_003d_0040var_007bexp_007d-163"></a><br><dt><code>--defsym=</code><var>symbol</var><code>=</code><var>expression</var><dd>Create a global symbol in the output file, containing the absolute 788address given by <var>expression</var>. You may use this option as many 789times as necessary to define multiple symbols in the command line. A 790limited form of arithmetic is supported for the <var>expression</var> in this 791context: you may give a hexadecimal constant or the name of an existing 792symbol, or use <code>+</code> and <code>-</code> to add or subtract hexadecimal 793constants or symbols. If you need more elaborate expressions, consider 794using the linker command language from a script (see <a href="Assignments.html#Assignments">Assignment: Symbol Definitions</a>). <em>Note:</em> there should be no white 795space between <var>symbol</var>, the equals sign (“<=>”), and 796<var>expression</var>. 797 798 <p><a name="index-demangling_002c-from-command-line-164"></a><a name="index-g_t_002d_002ddemangle_005b_003d_0040var_007bstyle_007d_005d-165"></a><a name="index-g_t_002d_002dno_002ddemangle-166"></a><br><dt><code>--demangle[=</code><var>style</var><code>]</code><dt><code>--no-demangle</code><dd>These options control whether to demangle symbol names in error messages 799and other output. When the linker is told to demangle, it tries to 800present symbol names in a readable fashion: it strips leading 801underscores if they are used by the object file format, and converts C++ 802mangled symbol names into user readable names. Different compilers have 803different mangling styles. The optional demangling style argument can be used 804to choose an appropriate demangling style for your compiler. The linker will 805demangle by default unless the environment variable ‘<samp><span class="samp">COLLECT_NO_DEMANGLE</span></samp>’ 806is set. These options may be used to override the default. 807 808 <p><a name="index-dynamic-linker_002c-from-command-line-167"></a><a name="index-g_t_002dI_0040var_007bfile_007d-168"></a><a name="index-g_t_002d_002ddynamic_002dlinker_003d_0040var_007bfile_007d-169"></a><br><dt><code>-I</code><var>file</var><dt><code>--dynamic-linker=</code><var>file</var><dd>Set the name of the dynamic linker. This is only meaningful when 809generating dynamically linked ELF executables. The default dynamic 810linker is normally correct; don't use this unless you know what you are 811doing. 812 813 <p><a name="index-g_t_002d_002dfatal_002dwarnings-170"></a><a name="index-g_t_002d_002dno_002dfatal_002dwarnings-171"></a><br><dt><code>--fatal-warnings</code><dt><code>--no-fatal-warnings</code><dd>Treat all warnings as errors. The default behaviour can be restored 814with the option <samp><span class="option">--no-fatal-warnings</span></samp>. 815 816 <p><a name="index-g_t_002d_002dforce_002dexe_002dsuffix-172"></a><br><dt><code>--force-exe-suffix</code><dd>Make sure that an output file has a .exe suffix. 817 818 <p>If a successfully built fully linked output file does not have a 819<code>.exe</code> or <code>.dll</code> suffix, this option forces the linker to copy 820the output file to one of the same name with a <code>.exe</code> suffix. This 821option is useful when using unmodified Unix makefiles on a Microsoft 822Windows host, since some versions of Windows won't run an image unless 823it ends in a <code>.exe</code> suffix. 824 825 <p><a name="index-g_t_002d_002dgc_002dsections-173"></a><a name="index-g_t_002d_002dno_002dgc_002dsections-174"></a><a name="index-garbage-collection-175"></a><br><dt><code>--gc-sections</code><dt><code>--no-gc-sections</code><dd>Enable garbage collection of unused input sections. It is ignored on 826targets that do not support this option. The default behaviour (of not 827performing this garbage collection) can be restored by specifying 828‘<samp><span class="samp">--no-gc-sections</span></samp>’ on the command line. 829 830 <p>‘<samp><span class="samp">--gc-sections</span></samp>’ decides which input sections are used by 831examining symbols and relocations. The section containing the entry 832symbol and all sections containing symbols undefined on the 833command-line will be kept, as will sections containing symbols 834referenced by dynamic objects. Note that when building shared 835libraries, the linker must assume that any visible symbol is 836referenced. Once this initial set of sections has been determined, 837the linker recursively marks as used any section referenced by their 838relocations. See ‘<samp><span class="samp">--entry</span></samp>’ and ‘<samp><span class="samp">--undefined</span></samp>’. 839 840 <p>This option can be set when doing a partial link (enabled with option 841‘<samp><span class="samp">-r</span></samp>’). In this case the root of symbols kept must be explicitly 842specified either by an ‘<samp><span class="samp">--entry</span></samp>’ or ‘<samp><span class="samp">--undefined</span></samp>’ option or by 843a <code>ENTRY</code> command in the linker script. 844 845 <p><a name="index-g_t_002d_002dprint_002dgc_002dsections-176"></a><a name="index-g_t_002d_002dno_002dprint_002dgc_002dsections-177"></a><a name="index-garbage-collection-178"></a><br><dt><code>--print-gc-sections</code><dt><code>--no-print-gc-sections</code><dd>List all sections removed by garbage collection. The listing is 846printed on stderr. This option is only effective if garbage 847collection has been enabled via the ‘<samp><span class="samp">--gc-sections</span></samp>’) option. The 848default behaviour (of not listing the sections that are removed) can 849be restored by specifying ‘<samp><span class="samp">--no-print-gc-sections</span></samp>’ on the command 850line. 851 852 <p><a name="index-g_t_002d_002dprint_002doutput_002dformat-179"></a><a name="index-output-format-180"></a><br><dt><code>--print-output-format</code><dd>Print the name of the default output format (perhaps influenced by 853other command-line options). This is the string that would appear 854in an <code>OUTPUT_FORMAT</code> linker script command (see <a href="File-Commands.html#File-Commands">File Commands</a>). 855 856 <p><a name="index-help-181"></a><a name="index-usage-182"></a><a name="index-g_t_002d_002dhelp-183"></a><br><dt><code>--help</code><dd>Print a summary of the command-line options on the standard output and exit. 857 858 <p><a name="index-g_t_002d_002dtarget_002dhelp-184"></a><br><dt><code>--target-help</code><dd>Print a summary of all target specific options on the standard output and exit. 859 860 <p><a name="index-g_t_002dMap_003d_0040var_007bmapfile_007d-185"></a><br><dt><code>-Map=</code><var>mapfile</var><dd>Print a link map to the file <var>mapfile</var>. See the description of the 861<samp><span class="option">-M</span></samp> option, above. 862 863 <p><a name="index-memory-usage-186"></a><a name="index-g_t_002d_002dno_002dkeep_002dmemory-187"></a><br><dt><code>--no-keep-memory</code><dd><samp><span class="command">ld</span></samp> normally optimizes for speed over memory usage by caching the 864symbol tables of input files in memory. This option tells <samp><span class="command">ld</span></samp> to 865instead optimize for memory usage, by rereading the symbol tables as 866necessary. This may be required if <samp><span class="command">ld</span></samp> runs out of memory space 867while linking a large executable. 868 869 <p><a name="index-g_t_002d_002dno_002dundefined-188"></a><a name="index-g_t_002dz-defs-189"></a><br><dt><code>--no-undefined</code><dt><code>-z defs</code><dd>Report unresolved symbol references from regular object files. This 870is done even if the linker is creating a non-symbolic shared library. 871The switch <samp><span class="option">--[no-]allow-shlib-undefined</span></samp> controls the 872behaviour for reporting unresolved references found in shared 873libraries being linked in. 874 875 <p><a name="index-g_t_002d_002dallow_002dmultiple_002ddefinition-190"></a><a name="index-g_t_002dz-muldefs-191"></a><br><dt><code>--allow-multiple-definition</code><dt><code>-z muldefs</code><dd>Normally when a symbol is defined multiple times, the linker will 876report a fatal error. These options allow multiple definitions and the 877first definition will be used. 878 879 <p><a name="index-g_t_002d_002dallow_002dshlib_002dundefined-192"></a><a name="index-g_t_002d_002dno_002dallow_002dshlib_002dundefined-193"></a><br><dt><code>--allow-shlib-undefined</code><dt><code>--no-allow-shlib-undefined</code><dd>Allows or disallows undefined symbols in shared libraries. 880This switch is similar to <samp><span class="option">--no-undefined</span></samp> except that it 881determines the behaviour when the undefined symbols are in a 882shared library rather than a regular object file. It does not affect 883how undefined symbols in regular object files are handled. 884 885 <p>The default behaviour is to report errors for any undefined symbols 886referenced in shared libraries if the linker is being used to create 887an executable, but to allow them if the linker is being used to create 888a shared library. 889 890 <p>The reasons for allowing undefined symbol references in shared 891libraries specified at link time are that: 892 893 <ul> 894<li>A shared library specified at link time may not be the same as the one 895that is available at load time, so the symbol might actually be 896resolvable at load time. 897<li>There are some operating systems, eg BeOS and HPPA, where undefined 898symbols in shared libraries are normal. 899 900 <p>The BeOS kernel for example patches shared libraries at load time to 901select whichever function is most appropriate for the current 902architecture. This is used, for example, to dynamically select an 903appropriate memset function. 904</ul> 905 906 <p><a name="index-g_t_002d_002dno_002dundefined_002dversion-194"></a><br><dt><code>--no-undefined-version</code><dd>Normally when a symbol has an undefined version, the linker will ignore 907it. This option disallows symbols with undefined version and a fatal error 908will be issued instead. 909 910 <p><a name="index-g_t_002d_002ddefault_002dsymver-195"></a><br><dt><code>--default-symver</code><dd>Create and use a default symbol version (the soname) for unversioned 911exported symbols. 912 913 <p><a name="index-g_t_002d_002ddefault_002dimported_002dsymver-196"></a><br><dt><code>--default-imported-symver</code><dd>Create and use a default symbol version (the soname) for unversioned 914imported symbols. 915 916 <p><a name="index-g_t_002d_002dno_002dwarn_002dmismatch-197"></a><br><dt><code>--no-warn-mismatch</code><dd>Normally <samp><span class="command">ld</span></samp> will give an error if you try to link together input 917files that are mismatched for some reason, perhaps because they have 918been compiled for different processors or for different endiannesses. 919This option tells <samp><span class="command">ld</span></samp> that it should silently permit such possible 920errors. This option should only be used with care, in cases when you 921have taken some special action that ensures that the linker errors are 922inappropriate. 923 924 <p><a name="index-g_t_002d_002dno_002dwarn_002dsearch_002dmismatch-198"></a><br><dt><code>--no-warn-search-mismatch</code><dd>Normally <samp><span class="command">ld</span></samp> will give a warning if it finds an incompatible 925library during a library search. This option silences the warning. 926 927 <p><a name="index-g_t_002d_002dno_002dwhole_002darchive-199"></a><br><dt><code>--no-whole-archive</code><dd>Turn off the effect of the <samp><span class="option">--whole-archive</span></samp> option for subsequent 928archive files. 929 930 <p><a name="index-output-file-after-errors-200"></a><a name="index-g_t_002d_002dnoinhibit_002dexec-201"></a><br><dt><code>--noinhibit-exec</code><dd>Retain the executable output file whenever it is still usable. 931Normally, the linker will not produce an output file if it encounters 932errors during the link process; it exits without writing an output file 933when it issues any error whatsoever. 934 935 <p><a name="index-g_t_002dnostdlib-202"></a><br><dt><code>-nostdlib</code><dd>Only search library directories explicitly specified on the 936command line. Library directories specified in linker scripts 937(including linker scripts specified on the command line) are ignored. 938 939 <p><a name="index-g_t_002d_002doformat_003d_0040var_007boutput_002dformat_007d-203"></a><br><dt><code>--oformat=</code><var>output-format</var><dd><samp><span class="command">ld</span></samp> may be configured to support more than one kind of object 940file. If your <samp><span class="command">ld</span></samp> is configured this way, you can use the 941‘<samp><span class="samp">--oformat</span></samp>’ option to specify the binary format for the output 942object file. Even when <samp><span class="command">ld</span></samp> is configured to support alternative 943object formats, you don't usually need to specify this, as <samp><span class="command">ld</span></samp> 944should be configured to produce as a default output format the most 945usual format on each machine. <var>output-format</var> is a text string, the 946name of a particular format supported by the BFD libraries. (You can 947list the available binary formats with ‘<samp><span class="samp">objdump -i</span></samp>’.) The script 948command <code>OUTPUT_FORMAT</code> can also specify the output format, but 949this option overrides it. See <a href="BFD.html#BFD">BFD</a>. 950 951 <p><a name="index-g_t_002dpie-204"></a><a name="index-g_t_002d_002dpic_002dexecutable-205"></a><br><dt><code>-pie</code><dt><code>--pic-executable</code><dd><a name="index-position-independent-executables-206"></a>Create a position independent executable. This is currently only supported on 952ELF platforms. Position independent executables are similar to shared 953libraries in that they are relocated by the dynamic linker to the virtual 954address the OS chooses for them (which can vary between invocations). Like 955normal dynamically linked executables they can be executed and symbols 956defined in the executable cannot be overridden by shared libraries. 957 958 <p><a name="index-g_t_002dqmagic-207"></a><br><dt><code>-qmagic</code><dd>This option is ignored for Linux compatibility. 959 960 <p><a name="index-g_t_002dQy-208"></a><br><dt><code>-Qy</code><dd>This option is ignored for SVR4 compatibility. 961 962 <p><a name="index-g_t_002d_002drelax-209"></a><a name="index-synthesizing-linker-210"></a><a name="index-relaxing-addressing-modes-211"></a><a name="index-g_t_002d_002dno_002drelax-212"></a><br><dt><code>--relax</code><dt><code>--no-relax</code><dd>An option with machine dependent effects. 963This option is only supported on a few targets. 964See <a href="H8_002f300.html#H8_002f300"><samp><span class="command">ld</span></samp> and the H8/300</a>. 965See <a href="i960.html#i960"><samp><span class="command">ld</span></samp> and the Intel 960 family</a>. 966See <a href="Xtensa.html#Xtensa"><samp><span class="command">ld</span></samp> and Xtensa Processors</a>. 967See <a href="M68HC11_002f68HC12.html#M68HC11_002f68HC12"><samp><span class="command">ld</span></samp> and the 68HC11 and 68HC12</a>. 968See <a href="PowerPC-ELF32.html#PowerPC-ELF32"><samp><span class="command">ld</span></samp> and PowerPC 32-bit ELF Support</a>. 969 970 <p>On some platforms the ‘<samp><span class="samp">--relax</span></samp>’ option performs target specific, 971global optimizations that become possible when the linker resolves 972addressing in the program, such as relaxing address modes, 973synthesizing new instructions, selecting shorter version of current 974instructions, and combinig constant values. 975 976 <p>On some platforms these link time global optimizations may make symbolic 977debugging of the resulting executable impossible. 978This is known to be the case for the Matsushita MN10200 and MN10300 979family of processors. 980 981 <p>On platforms where this is not supported, ‘<samp><span class="samp">--relax</span></samp>’ is accepted, 982but ignored. 983 984 <p>On platforms where ‘<samp><span class="samp">--relax</span></samp>’ is accepted the option 985‘<samp><span class="samp">--no-relax</span></samp>’ can be used to disable the feature. 986 987 <p><a name="index-retaining-specified-symbols-213"></a><a name="index-stripping-all-but-some-symbols-214"></a><a name="index-symbols_002c-retaining-selectively-215"></a><a name="index-g_t_002d_002dretain_002dsymbols_002dfile_003d_0040var_007bfilename_007d-216"></a><br><dt><code>--retain-symbols-file=</code><var>filename</var><dd>Retain <em>only</em> the symbols listed in the file <var>filename</var>, 988discarding all others. <var>filename</var> is simply a flat file, with one 989symbol name per line. This option is especially useful in environments 990(such as VxWorks) 991where a large global symbol table is accumulated gradually, to conserve 992run-time memory. 993 994 <p>‘<samp><span class="samp">--retain-symbols-file</span></samp>’ does <em>not</em> discard undefined symbols, 995or symbols needed for relocations. 996 997 <p>You may only specify ‘<samp><span class="samp">--retain-symbols-file</span></samp>’ once in the command 998line. It overrides ‘<samp><span class="samp">-s</span></samp>’ and ‘<samp><span class="samp">-S</span></samp>’. 999 1000 <br><dt><code>-rpath=</code><var>dir</var><dd><a name="index-runtime-library-search-path-217"></a><a name="index-g_t_002drpath_003d_0040var_007bdir_007d-218"></a>Add a directory to the runtime library search path. This is used when 1001linking an ELF executable with shared objects. All <samp><span class="option">-rpath</span></samp> 1002arguments are concatenated and passed to the runtime linker, which uses 1003them to locate shared objects at runtime. The <samp><span class="option">-rpath</span></samp> option is 1004also used when locating shared objects which are needed by shared 1005objects explicitly included in the link; see the description of the 1006<samp><span class="option">-rpath-link</span></samp> option. If <samp><span class="option">-rpath</span></samp> is not used when linking an 1007ELF executable, the contents of the environment variable 1008<code>LD_RUN_PATH</code> will be used if it is defined. 1009 1010 <p>The <samp><span class="option">-rpath</span></samp> option may also be used on SunOS. By default, on 1011SunOS, the linker will form a runtime search patch out of all the 1012<samp><span class="option">-L</span></samp> options it is given. If a <samp><span class="option">-rpath</span></samp> option is used, the 1013runtime search path will be formed exclusively using the <samp><span class="option">-rpath</span></samp> 1014options, ignoring the <samp><span class="option">-L</span></samp> options. This can be useful when using 1015gcc, which adds many <samp><span class="option">-L</span></samp> options which may be on NFS mounted 1016file systems. 1017 1018 <p>For compatibility with other ELF linkers, if the <samp><span class="option">-R</span></samp> option is 1019followed by a directory name, rather than a file name, it is treated as 1020the <samp><span class="option">-rpath</span></samp> option. 1021 1022 <p><a name="index-link_002dtime-runtime-library-search-path-219"></a><a name="index-g_t_002drpath_002dlink_003d_0040var_007bdir_007d-220"></a><br><dt><code>-rpath-link=</code><var>dir</var><dd>When using ELF or SunOS, one shared library may require another. This 1023happens when an <code>ld -shared</code> link includes a shared library as one 1024of the input files. 1025 1026 <p>When the linker encounters such a dependency when doing a non-shared, 1027non-relocatable link, it will automatically try to locate the required 1028shared library and include it in the link, if it is not included 1029explicitly. In such a case, the <samp><span class="option">-rpath-link</span></samp> option 1030specifies the first set of directories to search. The 1031<samp><span class="option">-rpath-link</span></samp> option may specify a sequence of directory names 1032either by specifying a list of names separated by colons, or by 1033appearing multiple times. 1034 1035 <p>This option should be used with caution as it overrides the search path 1036that may have been hard compiled into a shared library. In such a case it 1037is possible to use unintentionally a different search path than the 1038runtime linker would do. 1039 1040 <p>The linker uses the following search paths to locate required shared 1041libraries: 1042 <ol type=1 start=1> 1043<li>Any directories specified by <samp><span class="option">-rpath-link</span></samp> options. 1044<li>Any directories specified by <samp><span class="option">-rpath</span></samp> options. The difference 1045between <samp><span class="option">-rpath</span></samp> and <samp><span class="option">-rpath-link</span></samp> is that directories 1046specified by <samp><span class="option">-rpath</span></samp> options are included in the executable and 1047used at runtime, whereas the <samp><span class="option">-rpath-link</span></samp> option is only effective 1048at link time. Searching <samp><span class="option">-rpath</span></samp> in this way is only supported 1049by native linkers and cross linkers which have been configured with 1050the <samp><span class="option">--with-sysroot</span></samp> option. 1051<li>On an ELF system, for native linkers, if the <samp><span class="option">-rpath</span></samp> and 1052<samp><span class="option">-rpath-link</span></samp> options were not used, search the contents of the 1053environment variable <code>LD_RUN_PATH</code>. 1054<li>On SunOS, if the <samp><span class="option">-rpath</span></samp> option was not used, search any 1055directories specified using <samp><span class="option">-L</span></samp> options. 1056<li>For a native linker, the search the contents of the environment 1057variable <code>LD_LIBRARY_PATH</code>. 1058<li>For a native ELF linker, the directories in <code>DT_RUNPATH</code> or 1059<code>DT_RPATH</code> of a shared library are searched for shared 1060libraries needed by it. The <code>DT_RPATH</code> entries are ignored if 1061<code>DT_RUNPATH</code> entries exist. 1062<li>The default directories, normally <samp><span class="file">/lib</span></samp> and <samp><span class="file">/usr/lib</span></samp>. 1063<li>For a native linker on an ELF system, if the file <samp><span class="file">/etc/ld.so.conf</span></samp> 1064exists, the list of directories found in that file. 1065 </ol> 1066 1067 <p>If the required shared library is not found, the linker will issue a 1068warning and continue with the link. 1069 1070 <p><a name="index-g_t_002dshared-221"></a><a name="index-g_t_002dBshareable-222"></a><br><dt><code>-shared</code><dt><code>-Bshareable</code><dd><a name="index-shared-libraries-223"></a>Create a shared library. This is currently only supported on ELF, XCOFF 1071and SunOS platforms. On SunOS, the linker will automatically create a 1072shared library if the <samp><span class="option">-e</span></samp> option is not used and there are 1073undefined symbols in the link. 1074 1075 <p><a name="index-g_t_002d_002dsort_002dcommon-224"></a><br><dt><code>--sort-common</code><dt><code>--sort-common=ascending</code><dt><code>--sort-common=descending</code><dd>This option tells <samp><span class="command">ld</span></samp> to sort the common symbols by alignment in 1076ascending or descending order when it places them in the appropriate output 1077sections. The symbol alignments considered are sixteen-byte or larger, 1078eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps 1079between symbols due to alignment constraints. If no sorting order is 1080specified, then descending order is assumed. 1081 1082 <p><a name="index-g_t_002d_002dsort_002dsection_003dname-225"></a><br><dt><code>--sort-section=name</code><dd>This option will apply <code>SORT_BY_NAME</code> to all wildcard section 1083patterns in the linker script. 1084 1085 <p><a name="index-g_t_002d_002dsort_002dsection_003dalignment-226"></a><br><dt><code>--sort-section=alignment</code><dd>This option will apply <code>SORT_BY_ALIGNMENT</code> to all wildcard section 1086patterns in the linker script. 1087 1088 <p><a name="index-g_t_002d_002dsplit_002dby_002dfile-227"></a><br><dt><code>--split-by-file[=</code><var>size</var><code>]</code><dd>Similar to <samp><span class="option">--split-by-reloc</span></samp> but creates a new output section for 1089each input file when <var>size</var> is reached. <var>size</var> defaults to a 1090size of 1 if not given. 1091 1092 <p><a name="index-g_t_002d_002dsplit_002dby_002dreloc-228"></a><br><dt><code>--split-by-reloc[=</code><var>count</var><code>]</code><dd>Tries to creates extra sections in the output file so that no single 1093output section in the file contains more than <var>count</var> relocations. 1094This is useful when generating huge relocatable files for downloading into 1095certain real time kernels with the COFF object file format; since COFF 1096cannot represent more than 65535 relocations in a single section. Note 1097that this will fail to work with object file formats which do not 1098support arbitrary sections. The linker will not split up individual 1099input sections for redistribution, so if a single input section contains 1100more than <var>count</var> relocations one output section will contain that 1101many relocations. <var>count</var> defaults to a value of 32768. 1102 1103 <p><a name="index-g_t_002d_002dstats-229"></a><br><dt><code>--stats</code><dd>Compute and display statistics about the operation of the linker, such 1104as execution time and memory usage. 1105 1106 <p><a name="index-g_t_002d_002dsysroot_003d_0040var_007bdirectory_007d-230"></a><br><dt><code>--sysroot=</code><var>directory</var><dd>Use <var>directory</var> as the location of the sysroot, overriding the 1107configure-time default. This option is only supported by linkers 1108that were configured using <samp><span class="option">--with-sysroot</span></samp>. 1109 1110 <p><a name="index-g_t_002d_002dtraditional_002dformat-231"></a><a name="index-traditional-format-232"></a><br><dt><code>--traditional-format</code><dd>For some targets, the output of <samp><span class="command">ld</span></samp> is different in some ways from 1111the output of some existing linker. This switch requests <samp><span class="command">ld</span></samp> to 1112use the traditional format instead. 1113 1114 <p><a name="index-dbx-233"></a>For example, on SunOS, <samp><span class="command">ld</span></samp> combines duplicate entries in the 1115symbol string table. This can reduce the size of an output file with 1116full debugging information by over 30 percent. Unfortunately, the SunOS 1117<code>dbx</code> program can not read the resulting program (<code>gdb</code> has no 1118trouble). The ‘<samp><span class="samp">--traditional-format</span></samp>’ switch tells <samp><span class="command">ld</span></samp> to not 1119combine duplicate entries. 1120 1121 <p><a name="index-g_t_002d_002dsection_002dstart_003d_0040var_007bsectionname_007d_003d_0040var_007borg_007d-234"></a><br><dt><code>--section-start=</code><var>sectionname</var><code>=</code><var>org</var><dd>Locate a section in the output file at the absolute 1122address given by <var>org</var>. You may use this option as many 1123times as necessary to locate multiple sections in the command 1124line. 1125<var>org</var> must be a single hexadecimal integer; 1126for compatibility with other linkers, you may omit the leading 1127‘<samp><span class="samp">0x</span></samp>’ usually associated with hexadecimal values. <em>Note:</em> there 1128should be no white space between <var>sectionname</var>, the equals 1129sign (“<=>”), and <var>org</var>. 1130 1131 <p><a name="index-g_t_002dTbss_003d_0040var_007borg_007d-235"></a><a name="index-g_t_002dTdata_003d_0040var_007borg_007d-236"></a><a name="index-g_t_002dTtext_003d_0040var_007borg_007d-237"></a><a name="index-segment-origins_002c-cmd-line-238"></a><br><dt><code>-Tbss=</code><var>org</var><dt><code>-Tdata=</code><var>org</var><dt><code>-Ttext=</code><var>org</var><dd>Same as <samp><span class="option">--section-start</span></samp>, with <code>.bss</code>, <code>.data</code> or 1132<code>.text</code> as the <var>sectionname</var>. 1133 1134 <p><a name="index-g_t_002dTtext_002dsegment_003d_0040var_007borg_007d-239"></a><br><dt><code>-Ttext-segment=</code><var>org</var><dd><a name="index-text-segment-origin_002c-cmd-line-240"></a>When creating an ELF executable or shared object, it will set the address 1135of the first byte of the text segment. 1136 1137 <p><a name="index-g_t_002d_002dunresolved_002dsymbols-241"></a><br><dt><code>--unresolved-symbols=</code><var>method</var><dd>Determine how to handle unresolved symbols. There are four possible 1138values for ‘<samp><span class="samp">method</span></samp>’: 1139 1140 <dl> 1141<dt>‘<samp><span class="samp">ignore-all</span></samp>’<dd>Do not report any unresolved symbols. 1142 1143 <br><dt>‘<samp><span class="samp">report-all</span></samp>’<dd>Report all unresolved symbols. This is the default. 1144 1145 <br><dt>‘<samp><span class="samp">ignore-in-object-files</span></samp>’<dd>Report unresolved symbols that are contained in shared libraries, but 1146ignore them if they come from regular object files. 1147 1148 <br><dt>‘<samp><span class="samp">ignore-in-shared-libs</span></samp>’<dd>Report unresolved symbols that come from regular object files, but 1149ignore them if they come from shared libraries. This can be useful 1150when creating a dynamic binary and it is known that all the shared 1151libraries that it should be referencing are included on the linker's 1152command line. 1153</dl> 1154 1155 <p>The behaviour for shared libraries on their own can also be controlled 1156by the <samp><span class="option">--[no-]allow-shlib-undefined</span></samp> option. 1157 1158 <p>Normally the linker will generate an error message for each reported 1159unresolved symbol but the option <samp><span class="option">--warn-unresolved-symbols</span></samp> 1160can change this to a warning. 1161 1162 <p><a name="index-g_t_002d_002dverbose_005b_003d_0040var_007bNUMBER_007d_005d-242"></a><a name="index-verbose_005b_003d_0040var_007bNUMBER_007d_005d-243"></a><br><dt><code>--dll-verbose</code><dt><code>--verbose[=</code><var>NUMBER</var><code>]</code><dd>Display the version number for <samp><span class="command">ld</span></samp> and list the linker emulations 1163supported. Display which input files can and cannot be opened. Display 1164the linker script being used by the linker. If the optional <var>NUMBER</var> 1165argument > 1, plugin symbol status will also be displayed. 1166 1167 <p><a name="index-g_t_002d_002dversion_002dscript_003d_0040var_007bversion_002dscriptfile_007d-244"></a><a name="index-version-script_002c-symbol-versions-245"></a><br><dt><code>--version-script=</code><var>version-scriptfile</var><dd>Specify the name of a version script to the linker. This is typically 1168used when creating shared libraries to specify additional information 1169about the version hierarchy for the library being created. This option 1170is only fully supported on ELF platforms which support shared libraries; 1171see <a href="VERSION.html#VERSION">VERSION</a>. It is partially supported on PE platforms, which can 1172use version scripts to filter symbol visibility in auto-export mode: any 1173symbols marked ‘<samp><span class="samp">local</span></samp>’ in the version script will not be exported. 1174See <a href="WIN32.html#WIN32">WIN32</a>. 1175 1176 <p><a name="index-g_t_002d_002dwarn_002dcommon-246"></a><a name="index-warnings_002c-on-combining-symbols-247"></a><a name="index-combining-symbols_002c-warnings-on-248"></a><br><dt><code>--warn-common</code><dd>Warn when a common symbol is combined with another common symbol or with 1177a symbol definition. Unix linkers allow this somewhat sloppy practise, 1178but linkers on some other operating systems do not. This option allows 1179you to find potential problems from combining global symbols. 1180Unfortunately, some C libraries use this practise, so you may get some 1181warnings about symbols in the libraries as well as in your programs. 1182 1183 <p>There are three kinds of global symbols, illustrated here by C examples: 1184 1185 <dl> 1186<dt>‘<samp><span class="samp">int i = 1;</span></samp>’<dd>A definition, which goes in the initialized data section of the output 1187file. 1188 1189 <br><dt>‘<samp><span class="samp">extern int i;</span></samp>’<dd>An undefined reference, which does not allocate space. 1190There must be either a definition or a common symbol for the 1191variable somewhere. 1192 1193 <br><dt>‘<samp><span class="samp">int i;</span></samp>’<dd>A common symbol. If there are only (one or more) common symbols for a 1194variable, it goes in the uninitialized data area of the output file. 1195The linker merges multiple common symbols for the same variable into a 1196single symbol. If they are of different sizes, it picks the largest 1197size. The linker turns a common symbol into a declaration, if there is 1198a definition of the same variable. 1199</dl> 1200 1201 <p>The ‘<samp><span class="samp">--warn-common</span></samp>’ option can produce five kinds of warnings. 1202Each warning consists of a pair of lines: the first describes the symbol 1203just encountered, and the second describes the previous symbol 1204encountered with the same name. One or both of the two symbols will be 1205a common symbol. 1206 1207 <ol type=1 start=1> 1208<li>Turning a common symbol into a reference, because there is already a 1209definition for the symbol. 1210 <pre class="smallexample"> <var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' 1211 overridden by definition 1212 <var>file</var>(<var>section</var>): warning: defined here 1213</pre> 1214 <li>Turning a common symbol into a reference, because a later definition for 1215the symbol is encountered. This is the same as the previous case, 1216except that the symbols are encountered in a different order. 1217 <pre class="smallexample"> <var>file</var>(<var>section</var>): warning: definition of `<var>symbol</var>' 1218 overriding common 1219 <var>file</var>(<var>section</var>): warning: common is here 1220</pre> 1221 <li>Merging a common symbol with a previous same-sized common symbol. 1222 <pre class="smallexample"> <var>file</var>(<var>section</var>): warning: multiple common 1223 of `<var>symbol</var>' 1224 <var>file</var>(<var>section</var>): warning: previous common is here 1225</pre> 1226 <li>Merging a common symbol with a previous larger common symbol. 1227 <pre class="smallexample"> <var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' 1228 overridden by larger common 1229 <var>file</var>(<var>section</var>): warning: larger common is here 1230</pre> 1231 <li>Merging a common symbol with a previous smaller common symbol. This is 1232the same as the previous case, except that the symbols are 1233encountered in a different order. 1234 <pre class="smallexample"> <var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' 1235 overriding smaller common 1236 <var>file</var>(<var>section</var>): warning: smaller common is here 1237</pre> 1238 </ol> 1239 1240 <p><a name="index-g_t_002d_002dwarn_002dconstructors-249"></a><br><dt><code>--warn-constructors</code><dd>Warn if any global constructors are used. This is only useful for a few 1241object file formats. For formats like COFF or ELF, the linker can not 1242detect the use of global constructors. 1243 1244 <p><a name="index-g_t_002d_002dwarn_002dmultiple_002dgp-250"></a><br><dt><code>--warn-multiple-gp</code><dd>Warn if multiple global pointer values are required in the output file. 1245This is only meaningful for certain processors, such as the Alpha. 1246Specifically, some processors put large-valued constants in a special 1247section. A special register (the global pointer) points into the middle 1248of this section, so that constants can be loaded efficiently via a 1249base-register relative addressing mode. Since the offset in 1250base-register relative mode is fixed and relatively small (e.g., 16 1251bits), this limits the maximum size of the constant pool. Thus, in 1252large programs, it is often necessary to use multiple global pointer 1253values in order to be able to address all possible constants. This 1254option causes a warning to be issued whenever this case occurs. 1255 1256 <p><a name="index-g_t_002d_002dwarn_002donce-251"></a><a name="index-warnings_002c-on-undefined-symbols-252"></a><a name="index-undefined-symbols_002c-warnings-on-253"></a><br><dt><code>--warn-once</code><dd>Only warn once for each undefined symbol, rather than once per module 1257which refers to it. 1258 1259 <p><a name="index-g_t_002d_002dwarn_002dsection_002dalign-254"></a><a name="index-warnings_002c-on-section-alignment-255"></a><a name="index-section-alignment_002c-warnings-on-256"></a><br><dt><code>--warn-section-align</code><dd>Warn if the address of an output section is changed because of 1260alignment. Typically, the alignment will be set by an input section. 1261The address will only be changed if it not explicitly specified; that 1262is, if the <code>SECTIONS</code> command does not specify a start address for 1263the section (see <a href="SECTIONS.html#SECTIONS">SECTIONS</a>). 1264 1265 <p><a name="index-g_t_002d_002dwarn_002dshared_002dtextrel-257"></a><br><dt><code>--warn-shared-textrel</code><dd>Warn if the linker adds a DT_TEXTREL to a shared object. 1266 1267 <p><a name="index-g_t_002d_002dwarn_002dalternate_002dem-258"></a><br><dt><code>--warn-alternate-em</code><dd>Warn if an object has alternate ELF machine code. 1268 1269 <p><a name="index-g_t_002d_002dwarn_002dunresolved_002dsymbols-259"></a><br><dt><code>--warn-unresolved-symbols</code><dd>If the linker is going to report an unresolved symbol (see the option 1270<samp><span class="option">--unresolved-symbols</span></samp>) it will normally generate an error. 1271This option makes it generate a warning instead. 1272 1273 <p><a name="index-g_t_002d_002derror_002dunresolved_002dsymbols-260"></a><br><dt><code>--error-unresolved-symbols</code><dd>This restores the linker's default behaviour of generating errors when 1274it is reporting unresolved symbols. 1275 1276 <p><a name="index-g_t_002d_002dwhole_002darchive-261"></a><a name="index-including-an-entire-archive-262"></a><br><dt><code>--whole-archive</code><dd>For each archive mentioned on the command line after the 1277<samp><span class="option">--whole-archive</span></samp> option, include every object file in the archive 1278in the link, rather than searching the archive for the required object 1279files. This is normally used to turn an archive file into a shared 1280library, forcing every object to be included in the resulting shared 1281library. This option may be used more than once. 1282 1283 <p>Two notes when using this option from gcc: First, gcc doesn't know 1284about this option, so you have to use <samp><span class="option">-Wl,-whole-archive</span></samp>. 1285Second, don't forget to use <samp><span class="option">-Wl,-no-whole-archive</span></samp> after your 1286list of archives, because gcc will add its own list of archives to 1287your link and you may not want this flag to affect those as well. 1288 1289 <p><a name="index-g_t_002d_002dwrap_003d_0040var_007bsymbol_007d-263"></a><br><dt><code>--wrap=</code><var>symbol</var><dd>Use a wrapper function for <var>symbol</var>. Any undefined reference to 1290<var>symbol</var> will be resolved to <code>__wrap_</code><var>symbol</var>. Any 1291undefined reference to <code>__real_</code><var>symbol</var> will be resolved to 1292<var>symbol</var>. 1293 1294 <p>This can be used to provide a wrapper for a system function. The 1295wrapper function should be called <code>__wrap_</code><var>symbol</var>. If it 1296wishes to call the system function, it should call 1297<code>__real_</code><var>symbol</var>. 1298 1299 <p>Here is a trivial example: 1300 1301 <pre class="smallexample"> void * 1302 __wrap_malloc (size_t c) 1303 { 1304 printf ("malloc called with %zu\n", c); 1305 return __real_malloc (c); 1306 } 1307</pre> 1308 <p>If you link other code with this file using <samp><span class="option">--wrap malloc</span></samp>, then 1309all calls to <code>malloc</code> will call the function <code>__wrap_malloc</code> 1310instead. The call to <code>__real_malloc</code> in <code>__wrap_malloc</code> will 1311call the real <code>malloc</code> function. 1312 1313 <p>You may wish to provide a <code>__real_malloc</code> function as well, so that 1314links without the <samp><span class="option">--wrap</span></samp> option will succeed. If you do this, 1315you should not put the definition of <code>__real_malloc</code> in the same 1316file as <code>__wrap_malloc</code>; if you do, the assembler may resolve the 1317call before the linker has a chance to wrap it to <code>malloc</code>. 1318 1319 <p><a name="index-g_t_002d_002deh_002dframe_002dhdr-264"></a><br><dt><code>--eh-frame-hdr</code><dd>Request creation of <code>.eh_frame_hdr</code> section and ELF 1320<code>PT_GNU_EH_FRAME</code> segment header. 1321 1322 <p><a name="index-g_t_002d_002dld_002dgenerated_002dunwind_002dinfo-265"></a><br><dt><code>--no-ld-generated-unwind-info</code><dd>Request creation of <code>.eh_frame</code> unwind info for linker 1323generated code sections like PLT. This option is on by default 1324if linker generated unwind info is supported. 1325 1326 <p><a name="index-g_t_002d_002denable_002dnew_002ddtags-266"></a><a name="index-g_t_002d_002ddisable_002dnew_002ddtags-267"></a><br><dt><code>--enable-new-dtags</code><dt><code>--disable-new-dtags</code><dd>This linker can create the new dynamic tags in ELF. But the older ELF 1327systems may not understand them. If you specify 1328<samp><span class="option">--enable-new-dtags</span></samp>, the dynamic tags will be created as needed. 1329If you specify <samp><span class="option">--disable-new-dtags</span></samp>, no new dynamic tags will be 1330created. By default, the new dynamic tags are not created. Note that 1331those options are only available for ELF systems. 1332 1333 <p><a name="index-g_t_002d_002dhash_002dsize_003d_0040var_007bnumber_007d-268"></a><br><dt><code>--hash-size=</code><var>number</var><dd>Set the default size of the linker's hash tables to a prime number 1334close to <var>number</var>. Increasing this value can reduce the length of 1335time it takes the linker to perform its tasks, at the expense of 1336increasing the linker's memory requirements. Similarly reducing this 1337value can reduce the memory requirements at the expense of speed. 1338 1339 <p><a name="index-g_t_002d_002dhash_002dstyle_003d_0040var_007bstyle_007d-269"></a><br><dt><code>--hash-style=</code><var>style</var><dd>Set the type of linker's hash table(s). <var>style</var> can be either 1340<code>sysv</code> for classic ELF <code>.hash</code> section, <code>gnu</code> for 1341new style GNU <code>.gnu.hash</code> section or <code>both</code> for both 1342the classic ELF <code>.hash</code> and new style GNU <code>.gnu.hash</code> 1343hash tables. The default is <code>sysv</code>. 1344 1345 <p><a name="index-g_t_002d_002dreduce_002dmemory_002doverheads-270"></a><br><dt><code>--reduce-memory-overheads</code><dd>This option reduces memory requirements at ld runtime, at the expense of 1346linking speed. This was introduced to select the old O(n^2) algorithm 1347for link map file generation, rather than the new O(n) algorithm which uses 1348about 40% more memory for symbol storage. 1349 1350 <p>Another effect of the switch is to set the default hash table size to 13511021, which again saves memory at the cost of lengthening the linker's 1352run time. This is not done however if the <samp><span class="option">--hash-size</span></samp> switch 1353has been used. 1354 1355 <p>The <samp><span class="option">--reduce-memory-overheads</span></samp> switch may be also be used to 1356enable other tradeoffs in future versions of the linker. 1357 1358 <p><a name="index-g_t_002d_002dbuild_002did-271"></a><a name="index-g_t_002d_002dbuild_002did_003d_0040var_007bstyle_007d-272"></a><br><dt><code>--build-id</code><dt><code>--build-id=</code><var>style</var><dd>Request creation of <code>.note.gnu.build-id</code> ELF note section. 1359The contents of the note are unique bits identifying this linked 1360file. <var>style</var> can be <code>uuid</code> to use 128 random bits, 1361<code>sha1</code> to use a 160-bit <span class="sc">SHA1</span> hash on the normative 1362parts of the output contents, <code>md5</code> to use a 128-bit 1363<span class="sc">MD5</span> hash on the normative parts of the output contents, or 1364<code>0x</code><var>hexstring</var> to use a chosen bit string specified as 1365an even number of hexadecimal digits (<code>-</code> and <code>:</code> 1366characters between digit pairs are ignored). If <var>style</var> is 1367omitted, <code>sha1</code> is used. 1368 1369 <p>The <code>md5</code> and <code>sha1</code> styles produces an identifier 1370that is always the same in an identical output file, but will be 1371unique among all nonidentical output files. It is not intended 1372to be compared as a checksum for the file's contents. A linked 1373file may be changed later by other tools, but the build ID bit 1374string identifying the original linked file does not change. 1375 1376 <p>Passing <code>none</code> for <var>style</var> disables the setting from any 1377<code>--build-id</code> options earlier on the command line. 1378 1379 <p><a name="index-g_t_002d_002dno_002dpoison_002dsystem_002ddirectories-273"></a><br><dt><code>--no-poison-system-directories</code><dd>Do not warn for <samp><span class="option">-L</span></samp> options using system directories such as 1380<samp><span class="file">/usr/lib</span></samp> when cross linking. This option is intended for use 1381in chroot environments when such directories contain the correct 1382libraries for the target system rather than the host. 1383 1384 <p><a name="index-g_t_002d_002derror_002dpoison_002dsystem_002ddirectories-274"></a><br><dt><code>--error-poison-system-directories</code><dd>Give an error instead of a warning for <samp><span class="option">-L</span></samp> options using 1385system directories when cross linking. 1386</dl> 1387 1388<!-- man end --> 1389<h4 class="subsection">2.1.1 Options Specific to i386 PE Targets</h4> 1390 1391<!-- man begin OPTIONS --> 1392<p>The i386 PE linker supports the <samp><span class="option">-shared</span></samp> option, which causes 1393the output to be a dynamically linked library (DLL) instead of a 1394normal executable. You should name the output <code>*.dll</code> when you 1395use this option. In addition, the linker fully supports the standard 1396<code>*.def</code> files, which may be specified on the linker command line 1397like an object file (in fact, it should precede archives it exports 1398symbols from, to ensure that they get linked in, just like a normal 1399object file). 1400 1401 <p>In addition to the options common to all targets, the i386 PE linker 1402support additional command line options that are specific to the i386 1403PE target. Options that take values may be separated from their 1404values by either a space or an equals sign. 1405 1406 1407<a name="index-g_t_002d_002dadd_002dstdcall_002dalias-275"></a> 1408<dl><dt><code>--add-stdcall-alias</code><dd>If given, symbols with a stdcall suffix (@<var>nn</var>) will be exported 1409as-is and also with the suffix stripped. 1410[This option is specific to the i386 PE targeted port of the linker] 1411 1412 <p><a name="index-g_t_002d_002dbase_002dfile-276"></a><br><dt><code>--base-file </code><var>file</var><dd>Use <var>file</var> as the name of a file in which to save the base 1413addresses of all the relocations needed for generating DLLs with 1414<samp><span class="file">dlltool</span></samp>. 1415[This is an i386 PE specific option] 1416 1417 <p><a name="index-g_t_002d_002ddll-277"></a><br><dt><code>--dll</code><dd>Create a DLL instead of a regular executable. You may also use 1418<samp><span class="option">-shared</span></samp> or specify a <code>LIBRARY</code> in a given <code>.def</code> 1419file. 1420[This option is specific to the i386 PE targeted port of the linker] 1421 1422 <p><a name="index-g_t_002d_002denable_002dlong_002dsection_002dnames-278"></a><a name="index-g_t_002d_002ddisable_002dlong_002dsection_002dnames-279"></a><br><dt><code>--enable-long-section-names</code><dt><code>--disable-long-section-names</code><dd>The PE variants of the Coff object format add an extension that permits 1423the use of section names longer than eight characters, the normal limit 1424for Coff. By default, these names are only allowed in object files, as 1425fully-linked executable images do not carry the Coff string table required 1426to support the longer names. As a GNU extension, it is possible to 1427allow their use in executable images as well, or to (probably pointlessly!) 1428disallow it in object files, by using these two options. Executable images 1429generated with these long section names are slightly non-standard, carrying 1430as they do a string table, and may generate confusing output when examined 1431with non-GNU PE-aware tools, such as file viewers and dumpers. However, 1432GDB relies on the use of PE long section names to find Dwarf-2 debug 1433information sections in an executable image at runtime, and so if neither 1434option is specified on the command-line, <samp><span class="command">ld</span></samp> will enable long 1435section names, overriding the default and technically correct behaviour, 1436when it finds the presence of debug information while linking an executable 1437image and not stripping symbols. 1438[This option is valid for all PE targeted ports of the linker] 1439 1440 <p><a name="index-g_t_002d_002denable_002dstdcall_002dfixup-280"></a><a name="index-g_t_002d_002ddisable_002dstdcall_002dfixup-281"></a><br><dt><code>--enable-stdcall-fixup</code><dt><code>--disable-stdcall-fixup</code><dd>If the link finds a symbol that it cannot resolve, it will attempt to 1441do “fuzzy linking” by looking for another defined symbol that differs 1442only in the format of the symbol name (cdecl vs stdcall) and will 1443resolve that symbol by linking to the match. For example, the 1444undefined symbol <code>_foo</code> might be linked to the function 1445<code>_foo@12</code>, or the undefined symbol <code>_bar@16</code> might be linked 1446to the function <code>_bar</code>. When the linker does this, it prints a 1447warning, since it normally should have failed to link, but sometimes 1448import libraries generated from third-party dlls may need this feature 1449to be usable. If you specify <samp><span class="option">--enable-stdcall-fixup</span></samp>, this 1450feature is fully enabled and warnings are not printed. If you specify 1451<samp><span class="option">--disable-stdcall-fixup</span></samp>, this feature is disabled and such 1452mismatches are considered to be errors. 1453[This option is specific to the i386 PE targeted port of the linker] 1454 1455 <p><a name="index-g_t_002d_002dleading_002dunderscore-282"></a><a name="index-g_t_002d_002dno_002dleading_002dunderscore-283"></a><br><dt><code>--leading-underscore</code><dt><code>--no-leading-underscore</code><dd>For most targets default symbol-prefix is an underscore and is defined 1456in target's description. By this option it is possible to 1457disable/enable the default underscore symbol-prefix. 1458 1459 <p><a name="index-DLLs_002c-creating-284"></a><a name="index-g_t_002d_002dexport_002dall_002dsymbols-285"></a><br><dt><code>--export-all-symbols</code><dd>If given, all global symbols in the objects used to build a DLL will 1460be exported by the DLL. Note that this is the default if there 1461otherwise wouldn't be any exported symbols. When symbols are 1462explicitly exported via DEF files or implicitly exported via function 1463attributes, the default is to not export anything else unless this 1464option is given. Note that the symbols <code>DllMain@12</code>, 1465<code>DllEntryPoint@0</code>, <code>DllMainCRTStartup@12</code>, and 1466<code>impure_ptr</code> will not be automatically 1467exported. Also, symbols imported from other DLLs will not be 1468re-exported, nor will symbols specifying the DLL's internal layout 1469such as those beginning with <code>_head_</code> or ending with 1470<code>_iname</code>. In addition, no symbols from <code>libgcc</code>, 1471<code>libstd++</code>, <code>libmingw32</code>, or <code>crtX.o</code> will be exported. 1472Symbols whose names begin with <code>__rtti_</code> or <code>__builtin_</code> will 1473not be exported, to help with C++ DLLs. Finally, there is an 1474extensive list of cygwin-private symbols that are not exported 1475(obviously, this applies on when building DLLs for cygwin targets). 1476These cygwin-excludes are: <code>_cygwin_dll_entry@12</code>, 1477<code>_cygwin_crt0_common@8</code>, <code>_cygwin_noncygwin_dll_entry@12</code>, 1478<code>_fmode</code>, <code>_impure_ptr</code>, <code>cygwin_attach_dll</code>, 1479<code>cygwin_premain0</code>, <code>cygwin_premain1</code>, <code>cygwin_premain2</code>, 1480<code>cygwin_premain3</code>, and <code>environ</code>. 1481[This option is specific to the i386 PE targeted port of the linker] 1482 1483 <p><a name="index-g_t_002d_002dexclude_002dsymbols-286"></a><br><dt><code>--exclude-symbols </code><var>symbol</var><code>,</code><var>symbol</var><code>,...</code><dd>Specifies a list of symbols which should not be automatically 1484exported. The symbol names may be delimited by commas or colons. 1485[This option is specific to the i386 PE targeted port of the linker] 1486 1487 <p><a name="index-g_t_002d_002dexclude_002dall_002dsymbols-287"></a><br><dt><code>--exclude-all-symbols</code><dd>Specifies no symbols should be automatically exported. 1488[This option is specific to the i386 PE targeted port of the linker] 1489 1490 <p><a name="index-g_t_002d_002dfile_002dalignment-288"></a><br><dt><code>--file-alignment</code><dd>Specify the file alignment. Sections in the file will always begin at 1491file offsets which are multiples of this number. This defaults to 1492512. 1493[This option is specific to the i386 PE targeted port of the linker] 1494 1495 <p><a name="index-heap-size-289"></a><a name="index-g_t_002d_002dheap-290"></a><br><dt><code>--heap </code><var>reserve</var><dt><code>--heap </code><var>reserve</var><code>,</code><var>commit</var><dd>Specify the number of bytes of memory to reserve (and optionally commit) 1496to be used as heap for this program. The default is 1Mb reserved, 4K 1497committed. 1498[This option is specific to the i386 PE targeted port of the linker] 1499 1500 <p><a name="index-image-base-291"></a><a name="index-g_t_002d_002dimage_002dbase-292"></a><br><dt><code>--image-base </code><var>value</var><dd>Use <var>value</var> as the base address of your program or dll. This is 1501the lowest memory location that will be used when your program or dll 1502is loaded. To reduce the need to relocate and improve performance of 1503your dlls, each should have a unique base address and not overlap any 1504other dlls. The default is 0x400000 for executables, and 0x10000000 1505for dlls. 1506[This option is specific to the i386 PE targeted port of the linker] 1507 1508 <p><a name="index-g_t_002d_002dkill_002dat-293"></a><br><dt><code>--kill-at</code><dd>If given, the stdcall suffixes (@<var>nn</var>) will be stripped from 1509symbols before they are exported. 1510[This option is specific to the i386 PE targeted port of the linker] 1511 1512 <p><a name="index-g_t_002d_002dlarge_002daddress_002daware-294"></a><br><dt><code>--large-address-aware</code><dd>If given, the appropriate bit in the “Characteristics” field of the COFF 1513header is set to indicate that this executable supports virtual addresses 1514greater than 2 gigabytes. This should be used in conjunction with the /3GB 1515or /USERVA=<var>value</var> megabytes switch in the “[operating systems]” 1516section of the BOOT.INI. Otherwise, this bit has no effect. 1517[This option is specific to PE targeted ports of the linker] 1518 1519 <p><a name="index-g_t_002d_002dmajor_002dimage_002dversion-295"></a><br><dt><code>--major-image-version </code><var>value</var><dd>Sets the major number of the “image version”. Defaults to 1. 1520[This option is specific to the i386 PE targeted port of the linker] 1521 1522 <p><a name="index-g_t_002d_002dmajor_002dos_002dversion-296"></a><br><dt><code>--major-os-version </code><var>value</var><dd>Sets the major number of the “os version”. Defaults to 4. 1523[This option is specific to the i386 PE targeted port of the linker] 1524 1525 <p><a name="index-g_t_002d_002dmajor_002dsubsystem_002dversion-297"></a><br><dt><code>--major-subsystem-version </code><var>value</var><dd>Sets the major number of the “subsystem version”. Defaults to 4. 1526[This option is specific to the i386 PE targeted port of the linker] 1527 1528 <p><a name="index-g_t_002d_002dminor_002dimage_002dversion-298"></a><br><dt><code>--minor-image-version </code><var>value</var><dd>Sets the minor number of the “image version”. Defaults to 0. 1529[This option is specific to the i386 PE targeted port of the linker] 1530 1531 <p><a name="index-g_t_002d_002dminor_002dos_002dversion-299"></a><br><dt><code>--minor-os-version </code><var>value</var><dd>Sets the minor number of the “os version”. Defaults to 0. 1532[This option is specific to the i386 PE targeted port of the linker] 1533 1534 <p><a name="index-g_t_002d_002dminor_002dsubsystem_002dversion-300"></a><br><dt><code>--minor-subsystem-version </code><var>value</var><dd>Sets the minor number of the “subsystem version”. Defaults to 0. 1535[This option is specific to the i386 PE targeted port of the linker] 1536 1537 <p><a name="index-DEF-files_002c-creating-301"></a><a name="index-DLLs_002c-creating-302"></a><a name="index-g_t_002d_002doutput_002ddef-303"></a><br><dt><code>--output-def </code><var>file</var><dd>The linker will create the file <var>file</var> which will contain a DEF 1538file corresponding to the DLL the linker is generating. This DEF file 1539(which should be called <code>*.def</code>) may be used to create an import 1540library with <code>dlltool</code> or may be used as a reference to 1541automatically or implicitly exported symbols. 1542[This option is specific to the i386 PE targeted port of the linker] 1543 1544 <p><a name="index-DLLs_002c-creating-304"></a><a name="index-g_t_002d_002dout_002dimplib-305"></a><br><dt><code>--out-implib </code><var>file</var><dd>The linker will create the file <var>file</var> which will contain an 1545import lib corresponding to the DLL the linker is generating. This 1546import lib (which should be called <code>*.dll.a</code> or <code>*.a</code> 1547may be used to link clients against the generated DLL; this behaviour 1548makes it possible to skip a separate <code>dlltool</code> import library 1549creation step. 1550[This option is specific to the i386 PE targeted port of the linker] 1551 1552 <p><a name="index-g_t_002d_002denable_002dauto_002dimage_002dbase-306"></a><br><dt><code>--enable-auto-image-base</code><dd>Automatically choose the image base for DLLs, unless one is specified 1553using the <code>--image-base</code> argument. By using a hash generated 1554from the dllname to create unique image bases for each DLL, in-memory 1555collisions and relocations which can delay program execution are 1556avoided. 1557[This option is specific to the i386 PE targeted port of the linker] 1558 1559 <p><a name="index-g_t_002d_002ddisable_002dauto_002dimage_002dbase-307"></a><br><dt><code>--disable-auto-image-base</code><dd>Do not automatically generate a unique image base. If there is no 1560user-specified image base (<code>--image-base</code>) then use the platform 1561default. 1562[This option is specific to the i386 PE targeted port of the linker] 1563 1564 <p><a name="index-DLLs_002c-linking-to-308"></a><a name="index-g_t_002d_002ddll_002dsearch_002dprefix-309"></a><br><dt><code>--dll-search-prefix </code><var>string</var><dd>When linking dynamically to a dll without an import library, 1565search for <code><string><basename>.dll</code> in preference to 1566<code>lib<basename>.dll</code>. This behaviour allows easy distinction 1567between DLLs built for the various "subplatforms": native, cygwin, 1568uwin, pw, etc. For instance, cygwin DLLs typically use 1569<code>--dll-search-prefix=cyg</code>. 1570[This option is specific to the i386 PE targeted port of the linker] 1571 1572 <p><a name="index-g_t_002d_002denable_002dauto_002dimport-310"></a><br><dt><code>--enable-auto-import</code><dd>Do sophisticated linking of <code>_symbol</code> to <code>__imp__symbol</code> for 1573DATA imports from DLLs, and create the necessary thunking symbols when 1574building the import libraries with those DATA exports. Note: Use of the 1575'auto-import' extension will cause the text section of the image file 1576to be made writable. This does not conform to the PE-COFF format 1577specification published by Microsoft. 1578 1579 <p>Note - use of the 'auto-import' extension will also cause read only 1580data which would normally be placed into the .rdata section to be 1581placed into the .data section instead. This is in order to work 1582around a problem with consts that is described here: 1583http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html 1584 1585 <p>Using 'auto-import' generally will 'just work' – but sometimes you may 1586see this message: 1587 1588 <p>"variable '<var>' can't be auto-imported. Please read the 1589documentation for ld's <code>--enable-auto-import</code> for details." 1590 1591 <p>This message occurs when some (sub)expression accesses an address 1592ultimately given by the sum of two constants (Win32 import tables only 1593allow one). Instances where this may occur include accesses to member 1594fields of struct variables imported from a DLL, as well as using a 1595constant index into an array variable imported from a DLL. Any 1596multiword variable (arrays, structs, long long, etc) may trigger 1597this error condition. However, regardless of the exact data type 1598of the offending exported variable, ld will always detect it, issue 1599the warning, and exit. 1600 1601 <p>There are several ways to address this difficulty, regardless of the 1602data type of the exported variable: 1603 1604 <p>One way is to use –enable-runtime-pseudo-reloc switch. This leaves the task 1605of adjusting references in your client code for runtime environment, so 1606this method works only when runtime environment supports this feature. 1607 1608 <p>A second solution is to force one of the 'constants' to be a variable – 1609that is, unknown and un-optimizable at compile time. For arrays, 1610there are two possibilities: a) make the indexee (the array's address) 1611a variable, or b) make the 'constant' index a variable. Thus: 1612 1613 <pre class="example"> extern type extern_array[]; 1614 extern_array[1] --> 1615 { volatile type *t=extern_array; t[1] } 1616</pre> 1617 <p>or 1618 1619 <pre class="example"> extern type extern_array[]; 1620 extern_array[1] --> 1621 { volatile int t=1; extern_array[t] } 1622</pre> 1623 <p>For structs (and most other multiword data types) the only option 1624is to make the struct itself (or the long long, or the ...) variable: 1625 1626 <pre class="example"> extern struct s extern_struct; 1627 extern_struct.field --> 1628 { volatile struct s *t=&extern_struct; t->field } 1629</pre> 1630 <p>or 1631 1632 <pre class="example"> extern long long extern_ll; 1633 extern_ll --> 1634 { volatile long long * local_ll=&extern_ll; *local_ll } 1635</pre> 1636 <p>A third method of dealing with this difficulty is to abandon 1637'auto-import' for the offending symbol and mark it with 1638<code>__declspec(dllimport)</code>. However, in practise that 1639requires using compile-time #defines to indicate whether you are 1640building a DLL, building client code that will link to the DLL, or 1641merely building/linking to a static library. In making the choice 1642between the various methods of resolving the 'direct address with 1643constant offset' problem, you should consider typical real-world usage: 1644 1645 <p>Original: 1646 <pre class="example"> --foo.h 1647 extern int arr[]; 1648 --foo.c 1649 #include "foo.h" 1650 void main(int argc, char **argv){ 1651 printf("%d\n",arr[1]); 1652 } 1653</pre> 1654 <p>Solution 1: 1655 <pre class="example"> --foo.h 1656 extern int arr[]; 1657 --foo.c 1658 #include "foo.h" 1659 void main(int argc, char **argv){ 1660 /* This workaround is for win32 and cygwin; do not "optimize" */ 1661 volatile int *parr = arr; 1662 printf("%d\n",parr[1]); 1663 } 1664</pre> 1665 <p>Solution 2: 1666 <pre class="example"> --foo.h 1667 /* Note: auto-export is assumed (no __declspec(dllexport)) */ 1668 #if (defined(_WIN32) || defined(__CYGWIN__)) && \ 1669 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) 1670 #define FOO_IMPORT __declspec(dllimport) 1671 #else 1672 #define FOO_IMPORT 1673 #endif 1674 extern FOO_IMPORT int arr[]; 1675 --foo.c 1676 #include "foo.h" 1677 void main(int argc, char **argv){ 1678 printf("%d\n",arr[1]); 1679 } 1680</pre> 1681 <p>A fourth way to avoid this problem is to re-code your 1682library to use a functional interface rather than a data interface 1683for the offending variables (e.g. set_foo() and get_foo() accessor 1684functions). 1685[This option is specific to the i386 PE targeted port of the linker] 1686 1687 <p><a name="index-g_t_002d_002ddisable_002dauto_002dimport-311"></a><br><dt><code>--disable-auto-import</code><dd>Do not attempt to do sophisticated linking of <code>_symbol</code> to 1688<code>__imp__symbol</code> for DATA imports from DLLs. 1689[This option is specific to the i386 PE targeted port of the linker] 1690 1691 <p><a name="index-g_t_002d_002denable_002druntime_002dpseudo_002dreloc-312"></a><br><dt><code>--enable-runtime-pseudo-reloc</code><dd>If your code contains expressions described in –enable-auto-import section, 1692that is, DATA imports from DLL with non-zero offset, this switch will create 1693a vector of 'runtime pseudo relocations' which can be used by runtime 1694environment to adjust references to such data in your client code. 1695[This option is specific to the i386 PE targeted port of the linker] 1696 1697 <p><a name="index-g_t_002d_002ddisable_002druntime_002dpseudo_002dreloc-313"></a><br><dt><code>--disable-runtime-pseudo-reloc</code><dd>Do not create pseudo relocations for non-zero offset DATA imports from 1698DLLs. This is the default. 1699[This option is specific to the i386 PE targeted port of the linker] 1700 1701 <p><a name="index-g_t_002d_002denable_002dextra_002dpe_002ddebug-314"></a><br><dt><code>--enable-extra-pe-debug</code><dd>Show additional debug info related to auto-import symbol thunking. 1702[This option is specific to the i386 PE targeted port of the linker] 1703 1704 <p><a name="index-g_t_002d_002dsection_002dalignment-315"></a><br><dt><code>--section-alignment</code><dd>Sets the section alignment. Sections in memory will always begin at 1705addresses which are a multiple of this number. Defaults to 0x1000. 1706[This option is specific to the i386 PE targeted port of the linker] 1707 1708 <p><a name="index-stack-size-316"></a><a name="index-g_t_002d_002dstack-317"></a><br><dt><code>--stack </code><var>reserve</var><dt><code>--stack </code><var>reserve</var><code>,</code><var>commit</var><dd>Specify the number of bytes of memory to reserve (and optionally commit) 1709to be used as stack for this program. The default is 2Mb reserved, 4K 1710committed. 1711[This option is specific to the i386 PE targeted port of the linker] 1712 1713 <p><a name="index-g_t_002d_002dsubsystem-318"></a><br><dt><code>--subsystem </code><var>which</var><dt><code>--subsystem </code><var>which</var><code>:</code><var>major</var><dt><code>--subsystem </code><var>which</var><code>:</code><var>major</var><code>.</code><var>minor</var><dd>Specifies the subsystem under which your program will execute. The 1714legal values for <var>which</var> are <code>native</code>, <code>windows</code>, 1715<code>console</code>, <code>posix</code>, and <code>xbox</code>. You may optionally set 1716the subsystem version also. Numeric values are also accepted for 1717<var>which</var>. 1718[This option is specific to the i386 PE targeted port of the linker] 1719 1720 <p>The following options set flags in the <code>DllCharacteristics</code> field 1721of the PE file header: 1722[These options are specific to PE targeted ports of the linker] 1723 1724 <p><a name="index-g_t_002d_002ddynamicbase-319"></a><br><dt><code>--dynamicbase</code><dd>The image base address may be relocated using address space layout 1725randomization (ASLR). This feature was introduced with MS Windows 1726Vista for i386 PE targets. 1727 1728 <p><a name="index-g_t_002d_002dforceinteg-320"></a><br><dt><code>--forceinteg</code><dd>Code integrity checks are enforced. 1729 1730 <p><a name="index-g_t_002d_002dnxcompat-321"></a><br><dt><code>--nxcompat</code><dd>The image is compatible with the Data Execution Prevention. 1731This feature was introduced with MS Windows XP SP2 for i386 PE targets. 1732 1733 <p><a name="index-g_t_002d_002dno_002disolation-322"></a><br><dt><code>--no-isolation</code><dd>Although the image understands isolation, do not isolate the image. 1734 1735 <p><a name="index-g_t_002d_002dno_002dseh-323"></a><br><dt><code>--no-seh</code><dd>The image does not use SEH. No SE handler may be called from 1736this image. 1737 1738 <p><a name="index-g_t_002d_002dno_002dbind-324"></a><br><dt><code>--no-bind</code><dd>Do not bind this image. 1739 1740 <p><a name="index-g_t_002d_002dwdmdriver-325"></a><br><dt><code>--wdmdriver</code><dd>The driver uses the MS Windows Driver Model. 1741 1742 <p><a name="index-g_t_002d_002dtsaware-326"></a><br><dt><code>--tsaware</code><dd>The image is Terminal Server aware. 1743 1744 </dl> 1745 1746<!-- man end --> 1747<h4 class="subsection">2.1.2 Options specific to C6X uClinux targets</h4> 1748 1749<!-- man begin OPTIONS --> 1750<p>The C6X uClinux target uses a binary format called DSBT to support shared 1751libraries. Each shared library in the system needs to have a unique index; 1752all executables use an index of 0. 1753 1754 1755<a name="index-g_t_002d_002ddsbt_002dsize-327"></a> 1756<dl><dt><code>--dsbt-size </code><var>size</var><dd>This option sets the number of entires in the DSBT of the current executable 1757or shared library to <var>size</var>. The default is to create a table with 64 1758entries. 1759 1760 <p><a name="index-g_t_002d_002ddsbt_002dindex-328"></a><br><dt><code>--dsbt-index </code><var>index</var><dd>This option sets the DSBT index of the current executable or shared library 1761to <var>index</var>. The default is 0, which is appropriate for generating 1762executables. If a shared library is generated with a DSBT index of 0, the 1763<code>R_C6000_DSBT_INDEX</code> relocs are copied into the output file. 1764 1765 <p><a name="index-g_t_002d_002dno_002dmerge_002dexidx_002dentries-329"></a>The ‘<samp><span class="samp">--no-merge-exidx-entries</span></samp>’ switch disables the merging of adjacent 1766exidx entries in frame unwind info. 1767 1768 </dl> 1769 1770<!-- man end --> 1771<h4 class="subsection">2.1.3 Options specific to Motorola 68HC11 and 68HC12 targets</h4> 1772 1773<!-- man begin OPTIONS --> 1774<p>The 68HC11 and 68HC12 linkers support specific options to control the 1775memory bank switching mapping and trampoline code generation. 1776 1777 1778<a name="index-g_t_002d_002dno_002dtrampoline-330"></a> 1779<dl><dt><code>--no-trampoline</code><dd>This option disables the generation of trampoline. By default a trampoline 1780is generated for each far function which is called using a <code>jsr</code> 1781instruction (this happens when a pointer to a far function is taken). 1782 1783 <p><a name="index-g_t_002d_002dbank_002dwindow-331"></a><br><dt><code>--bank-window </code><var>name</var><dd>This option indicates to the linker the name of the memory region in 1784the ‘<samp><span class="samp">MEMORY</span></samp>’ specification that describes the memory bank window. 1785The definition of such region is then used by the linker to compute 1786paging and addresses within the memory window. 1787 1788 </dl> 1789 1790<!-- man end --> 1791<h4 class="subsection">2.1.4 Options specific to Motorola 68K target</h4> 1792 1793<!-- man begin OPTIONS --> 1794<p>The following options are supported to control handling of GOT generation 1795when linking for 68K targets. 1796 1797 1798<a name="index-g_t_002d_002dgot-332"></a> 1799<dl><dt><code>--got=</code><var>type</var><dd>This option tells the linker which GOT generation scheme to use. 1800<var>type</var> should be one of ‘<samp><span class="samp">single</span></samp>’, ‘<samp><span class="samp">negative</span></samp>’, 1801‘<samp><span class="samp">multigot</span></samp>’ or ‘<samp><span class="samp">target</span></samp>’. For more information refer to the 1802Info entry for <samp><span class="file">ld</span></samp>. 1803 1804 </dl> 1805 1806<!-- man end --> 1807<h4 class="subsection">2.1.5 Options specific to MIPS targets</h4> 1808 1809<!-- man begin OPTIONS --> 1810<p>The following options are supported to control microMIPS instruction 1811generation when linking for MIPS targets. 1812 1813 1814<a name="index-g_t_002d_002dinsn32-333"></a> 1815<dl><dt><code>--insn32</code><dd><a name="index-g_t_002d_002dno_002dinsn32-334"></a><dt><code>--no-insn32</code><dd>These options control the choice of microMIPS instructions used in code 1816generated by the linker, such as that in the PLT or lazy binding stubs, 1817or in relaxation. If ‘<samp><span class="samp">--insn32</span></samp>’ is used, then the linker only uses 181832-bit instruction encodings. By default or if ‘<samp><span class="samp">--no-insn32</span></samp>’ is 1819used, all instruction encodings are used, including 16-bit ones where 1820possible. 1821 1822 </dl> 1823 1824<!-- man end --> 1825 </body></html> 1826 1827