diff options
Diffstat (limited to 'contrib/binutils/ld/ld.1')
| -rw-r--r-- | contrib/binutils/ld/ld.1 | 367 |
1 files changed, 280 insertions, 87 deletions
diff --git a/contrib/binutils/ld/ld.1 b/contrib/binutils/ld/ld.1 index 9d7a53e..87ee202 100644 --- a/contrib/binutils/ld/ld.1 +++ b/contrib/binutils/ld/ld.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 .\" .\" Standard preamble: .\" ======================================================================== @@ -128,7 +128,7 @@ .\" ======================================================================== .\" .IX Title "LD 1" -.TH LD 1 "2002-10-30" "binutils-2.13" "GNU Development Tools" +.TH LD 1 "2004-05-17" "binutils-2.15" "GNU Development Tools" .SH "NAME" ld \- Using LD, the GNU linker .SH "SYNOPSIS" @@ -202,7 +202,7 @@ and the script command language. If \fIno\fR binary input files at all are specified, the linker does not produce any output, and issues the message \fBNo input files\fR. .PP -If the linker can not recognize the format of an object file, it will +If the linker cannot recognize the format of an object file, it will assume that it is a linker script. A script specified in this way augments the main linker script used for the link (either the default linker script or the one specified by using \fB\-T\fR). This feature @@ -219,7 +219,7 @@ option that requires them. .PP For options whose names are multiple letters, either one dash or two can precede the option name; for example, \fB\-trace\-symbol\fR and -\&\fB\-\-trace\-symbol\fR are equivalent. Note \- there is one exception to +\&\fB\-\-trace\-symbol\fR are equivalent. Note\-\-\-there is one exception to this rule. Multiple letter options that start with a lower case 'o' can only be preceeded by two dashes. This is to reduce confusion with the \&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file @@ -233,8 +233,8 @@ immediately following the option that requires them. For example, Unique abbreviations of the names of multiple-letter options are accepted. .PP -Note \- if the linker is being invoked indirectly, via a compiler driver -(eg \fBgcc\fR) then all the linker command line options should be +Note\-\-\-if the linker is being invoked indirectly, via a compiler driver +(e.g. \fBgcc\fR) then all the linker command line options should be prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular compiler driver) like this: .PP @@ -406,11 +406,13 @@ used to select a subset of the symbols provided by the object .Sp Some older linkers used the \fB\-F\fR option throughout a compilation toolchain for specifying object-file format for both input and output -object files. The \s-1GNU\s0 linker uses other mechanisms for this -purpose: the \fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the +object files. +The \s-1GNU\s0 linker uses other mechanisms for this purpose: the +\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the \&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR -environment variable. The \s-1GNU\s0 linker will ignore the \fB\-F\fR -option when not creating an \s-1ELF\s0 shared object. +environment variable. +The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not +creating an \s-1ELF\s0 shared object. .IP "\fB\-fini\fR \fIname\fR" 4 .IX Item "-fini name" When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the @@ -497,6 +499,9 @@ on the command line are searched before the default directories. All \&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the order in which the options appear. .Sp +If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the \fIsysroot prefix\fR, a path specified when the linker is configured. +.Sp The default set of paths searched (without being specified with \&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in some cases also on how it was configured. @@ -523,11 +528,11 @@ configured. Print a link map to the standard output. A link map provides information about the link, including the following: .RS 4 -.IP "\(bu" 4 +.IP "*" 4 Where object files and symbols are mapped into memory. -.IP "\(bu" 4 +.IP "*" 4 How common symbols are allocated. -.IP "\(bu" 4 +.IP "*" 4 All archive members included in the link, with a mention of the symbol which caused the archive member to be brought in. .RE @@ -548,8 +553,17 @@ Turn off page alignment of sections, and mark the output as .IX Item "--omagic" .PD Set the text and data sections to be readable and writable. Also, do -not page-align the data segment. If the output format supports Unix -style magic numbers, mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. +not page-align the data segment, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section +is allowed for PE-COFF targets, it does not conform to the format +specification published by Microsoft. +.IP "\fB\-\-no\-omagic\fR" 4 +.IX Item "--no-omagic" +This option negates most of the effects of the \fB\-N\fR option. It +sets the text section to be read\-only, and forces the data segment to +be page\-aligned. Note \- this option does not enable linking against +shared libraries. Use \fB\-Bdynamic\fR for this. .IP "\fB\-o\fR \fIoutput\fR" 4 .IX Item "-o output" .PD 0 @@ -579,8 +593,8 @@ This option is currently only supported on \s-1ELF\s0 platforms. .IP "\fB\-r\fR" 4 .IX Item "-r" .PD 0 -.IP "\fB\-\-relocateable\fR" 4 -.IX Item "--relocateable" +.IP "\fB\-\-relocatable\fR" 4 +.IX Item "--relocatable" .PD Generate relocatable output\-\-\-i.e., generate an output file that can in turn serve as input to \fBld\fR. This is often called \fIpartial @@ -719,29 +733,69 @@ Add \fIpath\fR to the default library search path. This option exists for Solaris compatibility. .IP "\fB\-z\fR \fIkeyword\fR" 4 .IX Item "-z keyword" -The recognized keywords are \f(CW\*(C`initfirst\*(C'\fR, \f(CW\*(C`interpose\*(C'\fR, -\&\f(CW\*(C`loadfltr\*(C'\fR, \f(CW\*(C`nodefaultlib\*(C'\fR, \f(CW\*(C`nodelete\*(C'\fR, \f(CW\*(C`nodlopen\*(C'\fR, -\&\f(CW\*(C`nodump\*(C'\fR, \f(CW\*(C`now\*(C'\fR, \f(CW\*(C`origin\*(C'\fR, \f(CW\*(C`combreloc\*(C'\fR, \f(CW\*(C`nocombreloc\*(C'\fR -and \f(CW\*(C`nocopyreloc\*(C'\fR. -The other keywords are -ignored for Solaris compatibility. \f(CW\*(C`initfirst\*(C'\fR marks the object -to be initialized first at runtime before any other objects. -\&\f(CW\*(C`interpose\*(C'\fR marks the object that its symbol table interposes -before all symbols but the primary executable. \f(CW\*(C`loadfltr\*(C'\fR marks -the object that its filtees be processed immediately at runtime. -\&\f(CW\*(C`nodefaultlib\*(C'\fR marks the object that the search for dependencies -of this object will ignore any default library search paths. -\&\f(CW\*(C`nodelete\*(C'\fR marks the object shouldn't be unloaded at runtime. -\&\f(CW\*(C`nodlopen\*(C'\fR marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. -\&\f(CW\*(C`nodump\*(C'\fR marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. -\&\f(CW\*(C`now\*(C'\fR marks the object with the non-lazy runtime binding. -\&\f(CW\*(C`origin\*(C'\fR marks the object may contain \f(CW$ORIGIN\fR. -\&\f(CW\*(C`defs\*(C'\fR disallows undefined symbols. -\&\f(CW\*(C`muldefs\*(C'\fR allows multiple definitions. -\&\f(CW\*(C`combreloc\*(C'\fR combines multiple reloc sections and sorts them -to make dynamic symbol lookup caching possible. -\&\f(CW\*(C`nocombreloc\*(C'\fR disables multiple reloc sections combining. -\&\f(CW\*(C`nocopyreloc\*(C'\fR disables production of copy relocs. +The recognized keywords are: +.RS 4 +.IP "\fBcombreloc\fR" 4 +.IX Item "combreloc" +Combines multiple reloc sections and sorts them to make dynamic symbol +lookup caching possible. +.IP "\fBdefs\fR" 4 +.IX Item "defs" +Disallows undefined symbols in object files. Undefined symbols in +shared libraries are still allowed. +.IP "\fBinitfirst\fR" 4 +.IX Item "initfirst" +This option is only meaningful when building a shared object. +It marks the object so that its runtime initialization will occur +before the runtime initialization of any other objects brought into +the process at the same time. Similarly the runtime finalization of +the object will occur after the runtime finalization of any other +objects. +.IP "\fBinterpose\fR" 4 +.IX Item "interpose" +Marks the object that its symbol table interposes before all symbols +but the primary executable. +.IP "\fBloadfltr\fR" 4 +.IX Item "loadfltr" +Marks the object that its filters be processed immediately at +runtime. +.IP "\fBmuldefs\fR" 4 +.IX Item "muldefs" +Allows multiple definitions. +.IP "\fBnocombreloc\fR" 4 +.IX Item "nocombreloc" +Disables multiple reloc sections combining. +.IP "\fBnocopyreloc\fR" 4 +.IX Item "nocopyreloc" +Disables production of copy relocs. +.IP "\fBnodefaultlib\fR" 4 +.IX Item "nodefaultlib" +Marks the object that the search for dependencies of this object will +ignore any default library search paths. +.IP "\fBnodelete\fR" 4 +.IX Item "nodelete" +Marks the object shouldn't be unloaded at runtime. +.IP "\fBnodlopen\fR" 4 +.IX Item "nodlopen" +Marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. +.IP "\fBnodump\fR" 4 +.IX Item "nodump" +Marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. +.IP "\fBnow\fR" 4 +.IX Item "now" +When generating an executable or shared library, mark it to tell the +dynamic linker to resolve all symbols when the program is started, or +when the shared library is linked to using dlopen, instead of +deferring function call resolution to the point when the function is +first called. +.IP "\fBorigin\fR" 4 +.IX Item "origin" +Marks the object may contain \f(CW$ORIGIN\fR. +.RE +.RS 4 +.Sp +Other keywords are ignored for Solaris compatibility. +.RE .IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4 .IX Item "-( archives -)" .PD 0 @@ -763,6 +817,32 @@ resolved. Using this option has a significant performance cost. It is best to use it only when there are unavoidable circular references between two or more archives. +.IP "\fB\-\-accept\-unknown\-input\-arch\fR" 4 +.IX Item "--accept-unknown-input-arch" +.PD 0 +.IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4 +.IX Item "--no-accept-unknown-input-arch" +.PD +Tells the linker to accept input files whose architecture cannot be +recognised. The assumption is that the user knows what they are doing +and deliberately wants to link in these unknown input files. This was +the default behaviour of the linker, before release 2.14. The default +behaviour from release 2.14 onwards is to reject such input files, and +so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to +restore the old behaviour. +.IP "\fB\-\-as\-needed\fR" 4 +.IX Item "--as-needed" +.PD 0 +.IP "\fB\-\-no\-as\-needed\fR" 4 +.IX Item "--no-as-needed" +.PD +This option affects \s-1ELF\s0 \s-1DT_NEEDED\s0 tags for dynamic libraries mentioned +on the command line after the \fB\-\-as\-needed\fR option. Normally, +the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed. \fB\-\-as\-needed\fR causes \s-1DT_NEEDED\s0 tags to only be emitted +for libraries that satisfy some reference from regular objects. +\&\fB\-\-no\-as\-needed\fR restores the default behaviour. .IP "\fB\-assert\fR \fIkeyword\fR" 4 .IX Item "-assert keyword" This option is ignored for SunOS compatibility. @@ -785,8 +865,8 @@ multiple times on the command line: it affects library searching for Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic section. This causes the runtime linker to handle lookups in this object and its dependencies to be performed only inside the group. -\&\fB\-\-no\-undefined\fR is implied. This option is only meaningful on \s-1ELF\s0 -platforms which support shared libraries. +\&\fB\-\-unresolved\-symbols=report\-all\fR is implied. This option is +only meaningful on \s-1ELF\s0 platforms which support shared libraries. .IP "\fB\-Bstatic\fR" 4 .IX Item "-Bstatic" .PD 0 @@ -801,7 +881,8 @@ Do not link against shared libraries. This is only meaningful on platforms for which shared libraries are supported. The different variants of this option are for compatibility with various systems. You may use this option multiple times on the command line: it affects -library searching for \fB\-l\fR options which follow it. +library searching for \fB\-l\fR options which follow it. This +option also implies \fB\-\-unresolved\-symbols=report\-all\fR. .IP "\fB\-Bsymbolic\fR" 4 .IX Item "-Bsymbolic" When creating a shared library, bind references to global symbols to the @@ -934,9 +1015,11 @@ while linking a large executable. .IP "\fB\-z defs\fR" 4 .IX Item "-z defs" .PD -Normally when creating a non-symbolic shared library, undefined symbols -are allowed and left to be resolved by the runtime loader. These options -disallows such undefined symbols. +Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the +behaviour for reporting unresolved references found in shared +libraries being linked in. .IP "\fB\-\-allow\-multiple\-definition\fR" 4 .IX Item "--allow-multiple-definition" .PD 0 @@ -948,16 +1031,25 @@ report a fatal error. These options allow multiple definitions and the first definition will be used. .IP "\fB\-\-allow\-shlib\-undefined\fR" 4 .IX Item "--allow-shlib-undefined" -Allow undefined symbols in shared objects even when \-\-no\-undefined is -set. The net result will be that undefined symbols in regular objects -will still trigger an error, but undefined symbols in shared objects -will be ignored. The implementation of no_undefined makes the -assumption that the runtime linker will choke on undefined symbols. -However there is at least one system (BeOS) where undefined symbols in -shared libraries is normal since the kernel patches them at load time to -select which function is most appropriate for the current architecture. -I.E. dynamically select an appropriate memset function. Apparently it -is also normal for \s-1HPPA\s0 shared libraries to have undefined symbols. +.PD 0 +.IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4 +.IX Item "--no-allow-shlib-undefined" +.PD +Allows (the default) or disallows undefined symbols in shared libraries. +This switch is similar to \fB\-\-no\-undefined\fR except that it +determines the behaviour when the undefined symbols are in a +shared library rather than a regular object file. It does not affect +how undefined symbols in regular object files are handled. +.Sp +The reason that \fB\-\-allow\-shlib\-undefined\fR is the default is that +the shared library being specified at link time may not be the same as +the one that is available at load time, so the symbols might actually be +resolvable at load time. Plus there are some systems, (eg BeOS) where +undefined symbols in shared libraries is normal. (The kernel patches +them at load time to select which function is most appropriate +for the current architecture. This is used for example to dynamically +select an appropriate memset function). Apparently it is also normal +for \s-1HPPA\s0 shared libraries to have undefined symbols. .IP "\fB\-\-no\-undefined\-version\fR" 4 .IX Item "--no-undefined-version" Normally when a symbol has an undefined version, the linker will ignore @@ -1000,6 +1092,18 @@ name of a particular format supported by the \s-1BFD\s0 libraries. (You can list the available binary formats with \fBobjdump \-i\fR.) The script command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but this option overrides it. +.IP "\fB\-pie\fR" 4 +.IX Item "-pie" +.PD 0 +.IP "\fB\-\-pic\-executable\fR" 4 +.IX Item "--pic-executable" +.PD +Create a position independent executable. This is currently only supported on +\&\s-1ELF\s0 platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the \s-1OS\s0 chooses for them (which can vary between invocations). Like +normal dynamically linked executables they can be executed and symbols +defined in the executable cannot be overridden by shared libraries. .IP "\fB\-qmagic\fR" 4 .IX Item "-qmagic" This option is ignored for Linux compatibility. @@ -1186,11 +1290,40 @@ sign (``\fB=\fR''), and \fIorg\fR. .IP "\fB\-Ttext\fR \fIorg\fR" 4 .IX Item "-Ttext org" .PD -Use \fIorg\fR as the starting address for\-\-\-respectively\-\-\-the -\&\f(CW\*(C`bss\*(C'\fR, \f(CW\*(C`data\*(C'\fR, or the \f(CW\*(C`text\*(C'\fR segment of the output file. -\&\fIorg\fR must be a single hexadecimal integer; -for compatibility with other linkers, you may omit the leading -\&\fB0x\fR usually associated with hexadecimal values. +Same as \-\-section\-start, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or +\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR. +.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4 +.IX Item "--unresolved-symbols=method" +Determine how to handle unresolved symbols. There are four possible +values for \fBmethod\fR: +.RS 4 +.IP "\fBignore-all\fR" 4 +.IX Item "ignore-all" +Do not report any unresolved symbols. +.IP "\fBreport-all\fR" 4 +.IX Item "report-all" +Report all unresolved symbols. This is the default. +.IP "\fBignore-in-object-files\fR" 4 +.IX Item "ignore-in-object-files" +Report unresolved symbols that are contained in shared libraries, but +ignore them if they come from regular object files. +.IP "\fBignore-in-shared-libs\fR" 4 +.IX Item "ignore-in-shared-libs" +Report unresolved symbols that come from regular object files, but +ignore them if they come from shared libraries. This can be useful +when creating a dynamic binary and it is known that all the shared +libraries that it should be referencing are included on the linker's +command line. +.RE +.RS 4 +.Sp +The behaviour for shared libraries on their own can also be controlled +by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option. +.Sp +Normally the linker will generate an error message for each reported +unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR +can change this to a warning. +.RE .IP "\fB\-\-dll\-verbose\fR" 4 .IX Item "--dll-verbose" .PD 0 @@ -1204,15 +1337,15 @@ the linker script being used by the linker. .IX Item "--version-script=version-scriptfile" Specify the name of a version script to the linker. This is typically used when creating shared libraries to specify additional information -about the version heirarchy for the library being created. This option +about the version hierarchy for the library being created. This option is only meaningful on \s-1ELF\s0 platforms which support shared libraries. .IP "\fB\-\-warn\-common\fR" 4 .IX Item "--warn-common" Warn when a common symbol is combined with another common symbol or with -a symbol definition. Unix linkers allow this somewhat sloppy practice, +a symbol definition. Unix linkers allow this somewhat sloppy practise, but linkers on some other operating systems do not. This option allows you to find potential problems from combining global symbols. -Unfortunately, some C libraries use this practice, so you may get some +Unfortunately, some C libraries use this practise, so you may get some warnings about symbols in the libraries as well as in your programs. .Sp There are three kinds of global symbols, illustrated here by C examples: @@ -1319,6 +1452,15 @@ alignment. Typically, the alignment will be set by an input section. The address will only be changed if it not explicitly specified; that is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for the section. +.IP "\fB\-\-warn\-unresolved\-symbols\fR" 4 +.IX Item "--warn-unresolved-symbols" +If the linker is going to report an unresolved symbol (see the option +\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error. +This option makes it generate a warning instead. +.IP "\fB\-\-error\-unresolved\-symbols\fR" 4 +.IX Item "--error-unresolved-symbols" +This restores the linker's default behaviour of generating errors when +it is reporting unresolved symbols. .IP "\fB\-\-whole\-archive\fR" 4 .IX Item "--whole-archive" For each archive mentioned on the command line after the @@ -1349,9 +1491,9 @@ Here is a trivial example: .Sp .Vb 6 \& void * -\& __wrap_malloc (int c) +\& __wrap_malloc (size_t c) \& { -\& printf ("malloc called with %ld\en", c); +\& printf ("malloc called with %zu\en", c); \& return __real_malloc (c); \& } .Ve @@ -1396,16 +1538,19 @@ values by either a space or an equals sign. .IX Item "--add-stdcall-alias" If given, symbols with a stdcall suffix (@\fInn\fR) will be exported as-is and also with the suffix stripped. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-base\-file\fR \fIfile\fR" 4 .IX Item "--base-file file" Use \fIfile\fR as the name of a file in which to save the base addresses of all the relocations needed for generating DLLs with \&\fIdlltool\fR. +[This is an i386 \s-1PE\s0 specific option] .IP "\fB\-\-dll\fR" 4 .IX Item "--dll" Create a \s-1DLL\s0 instead of a regular executable. You may also use \&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR file. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-enable\-stdcall\-fixup\fR" 4 .IX Item "--enable-stdcall-fixup" .PD 0 @@ -1413,7 +1558,7 @@ file. .IX Item "--disable-stdcall-fixup" .PD If the link finds a symbol that it cannot resolve, it will attempt to -do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs +do ``fuzzy linking'' by looking for another defined symbol that differs only in the format of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking to the match. For example, the undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function @@ -1425,6 +1570,7 @@ to be usable. If you specify \fB\-\-enable\-stdcall\-fixup\fR, this feature is fully enabled and warnings are not printed. If you specify \&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such mismatches are considered to be errors. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-export\-all\-symbols\fR" 4 .IX Item "--export-all-symbols" If given, all global symbols in the objects used to build a \s-1DLL\s0 will @@ -1449,10 +1595,12 @@ These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR, \&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR, \&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR, \&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4 .IX Item "--exclude-symbols symbol,symbol,..." Specifies a list of symbols which should not be automatically exported. The symbol names may be delimited by commas or colons. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4 .IX Item "--exclude-libs lib,lib,..." Specifies a list of archive libraries from which symbols should not be automatically @@ -1460,11 +1608,13 @@ exported. The library names may be delimited by commas or colons. Specifying \&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from automatic export. Symbols explicitly listed in a .def file are still exported, regardless of this option. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-file\-alignment\fR" 4 .IX Item "--file-alignment" Specify the file alignment. Sections in the file will always begin at file offsets which are multiples of this number. This defaults to 512. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-heap\fR \fIreserve\fR" 4 .IX Item "--heap reserve" .PD 0 @@ -1474,6 +1624,7 @@ file offsets which are multiples of this number. This defaults to Specify the amount of memory to reserve (and optionally commit) to be used as heap for this program. The default is 1Mb reserved, 4K committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-image\-base\fR \fIvalue\fR" 4 .IX Item "--image-base value" Use \fIvalue\fR as the base address of your program or dll. This is @@ -1482,28 +1633,36 @@ is loaded. To reduce the need to relocate and improve performance of your dlls, each should have a unique base address and not overlap any other dlls. The default is 0x400000 for executables, and 0x10000000 for dlls. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-kill\-at\fR" 4 .IX Item "--kill-at" If given, the stdcall suffixes (@\fInn\fR) will be stripped from symbols before they are exported. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4 .IX Item "--major-image-version value" -Sets the major number of the \*(L"image version\*(R". Defaults to 1. +Sets the major number of the ``image version''. Defaults to 1. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4 .IX Item "--major-os-version value" -Sets the major number of the \*(L"os version\*(R". Defaults to 4. +Sets the major number of the ``os version''. Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4 .IX Item "--major-subsystem-version value" -Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4. +Sets the major number of the ``subsystem version''. Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4 .IX Item "--minor-image-version value" -Sets the minor number of the \*(L"image version\*(R". Defaults to 0. +Sets the minor number of the ``image version''. Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4 .IX Item "--minor-os-version value" -Sets the minor number of the \*(L"os version\*(R". Defaults to 0. +Sets the minor number of the ``os version''. Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4 .IX Item "--minor-subsystem-version value" -Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0. +Sets the minor number of the ``subsystem version''. Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-output\-def\fR \fIfile\fR" 4 .IX Item "--output-def file" The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0 @@ -1511,14 +1670,16 @@ file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 (which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to automatically or implicitly exported symbols. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-out\-implib\fR \fIfile\fR" 4 .IX Item "--out-implib file" The linker will create the file \fIfile\fR which will contain an import lib corresponding to the \s-1DLL\s0 the linker is generating. This import lib (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR -may be used to link clients against the generated \s-1DLL\s0; this behavior +may be used to link clients against the generated \s-1DLL\s0; this behaviour makes it possible to skip a separate \f(CW\*(C`dlltool\*(C'\fR import library creation step. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-enable\-auto\-image\-base\fR" 4 .IX Item "--enable-auto-image-base" Automatically choose the image base for DLLs, unless one is specified @@ -1526,25 +1687,33 @@ using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument. By using a hash generated from the dllname to create unique image bases for each \s-1DLL\s0, in-memory collisions and relocations which can delay program execution are avoided. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-disable\-auto\-image\-base\fR" 4 .IX Item "--disable-auto-image-base" Do not automatically generate a unique image base. If there is no user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4 .IX Item "--dll-search-prefix string" -When linking dynamically to a dll without an import library, i +When linking dynamically to a dll without an import library, search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to -\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behavior allows easy distinction +\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction between DLLs built for the various \*(L"subplatforms\*(R": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically use \&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-enable\-auto\-import\fR" 4 .IX Item "--enable-auto-import" Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \&\s-1DATA\s0 imports from DLLs, and create the necessary thunking symbols when -building the DLLs with those \s-1DATA\s0 exports. This generally will 'just -work' \*(-- but sometimes you may see this message: +building the import libraries with those \s-1DATA\s0 exports. Note: Use of the +\&'auto\-import' extension will cause the text section of the image file +to be made writable. This does not conform to the PE-COFF format +specification published by Microsoft. +.Sp +Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may +see this message: .Sp "variable '<var>' can't be auto\-imported. Please read the documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details." @@ -1562,7 +1731,11 @@ the warning, and exit. There are several ways to address this difficulty, regardless of the data type of the exported variable: .Sp -One solution is to force one of the 'constants' to be a variable \*(-- +One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so +this method works only when runtime environment supports this feature. +.Sp +A second solution is to force one of the 'constants' to be a variable \*(-- that is, unknown and un-optimizable at compile time. For arrays, there are two possibilities: a) make the indexee (the array's address) a variable, or b) make the 'constant' index a variable. Thus: @@ -1598,9 +1771,9 @@ or \& { volatile long long * local_ll=&extern_ll; *local_ll } .Ve .Sp -A second method of dealing with this difficulty is to abandon +A third method of dealing with this difficulty is to abandon \&'auto\-import' for the offending symbol and mark it with -\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR. However, in practice that +\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR. However, in practise that requires using compile-time #defines to indicate whether you are building a \s-1DLL\s0, building client code that will link to the \s-1DLL\s0, or merely building/linking to a static library. In making the choice @@ -1652,21 +1825,37 @@ Solution 2: \& } .Ve .Sp -A third way to avoid this problem is to re-code your +A fourth way to avoid this problem is to re-code your library to use a functional interface rather than a data interface for the offending variables (e.g. \fIset_foo()\fR and \fIget_foo()\fR accessor functions). +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-disable\-auto\-import\fR" 4 .IX Item "--disable-auto-import" -Do not attempt to do sophisticalted linking of \f(CW\*(C`_symbol\*(C'\fR to +Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--enable-runtime-pseudo-reloc" +If your code contains expressions described in \-\-enable\-auto\-import section, +that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime +environment to adjust references to such data in your client code. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--disable-runtime-pseudo-reloc" +Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from +DLLs. This is the default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4 .IX Item "--enable-extra-pe-debug" Show additional debug info related to auto-import symbol thunking. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-section\-alignment\fR" 4 .IX Item "--section-alignment" Sets the section alignment. Sections in memory will always begin at addresses which are a multiple of this number. Defaults to 0x1000. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-stack\fR \fIreserve\fR" 4 .IX Item "--stack reserve" .PD 0 @@ -1676,6 +1865,7 @@ addresses which are a multiple of this number. Defaults to 0x1000. Specify the amount of memory to reserve (and optionally commit) to be used as stack for this program. The default is 2Mb reserved, 4K committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 .IX Item "--subsystem which" .PD 0 @@ -1688,10 +1878,12 @@ Specifies the subsystem under which your program will execute. The legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, \&\f(CW\*(C`console\*(C'\fR, and \f(CW\*(C`posix\*(C'\fR. You may optionally set the subsystem version also. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" -You can change the behavior of \fBld\fR with the environment variables -\&\f(CW\*(C`GNUTARGET\*(C'\fR, \f(CW\*(C`LDEMULATION\*(C'\fR, and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR. +You can change the behaviour of \fBld\fR with the environment variables +\&\f(CW\*(C`GNUTARGET\*(C'\fR, +\&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR. .PP \&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't use \fB\-b\fR (or its synonym \fB\-\-format\fR). Its value should be one @@ -1726,11 +1918,12 @@ the Info entries for \fIbinutils\fR and \&\fIld\fR. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc. +Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, +2002, 2003, 2004 Free Software Foundation, Inc. .PP Permission is granted to copy, distribute and/or modify this document under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the -section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". +section entitled ``\s-1GNU\s0 Free Documentation License''. |
